Add cancel_all() to WC_Queue_Interface

And the WC_Action_Queue implementation of WC_Queue_Interface.

This avoids ambiguity between the behaviour of cancel(), which can
be confusing given it technically unschedules all actions for cron
or recurring actions, but only the next instance of a single action.

includes/interfaces/class-wc-queue-interface.php

@@ -75,9 +75,9 @@ interface WC_Queue_Interface {
 	public function schedule_cron( $timestamp, $cron_schedule, $hook, $args = array(), $group = '' );
 
 	/**
-	 * Dequeue all actions with a matching hook (and optionally matching args and group) so they are not run.
+	 * Dequeue the next scheduled instance of an action with a matching hook (and optionally matching args and group).
 	 *
-	 * Any recurring actions with a matching hook will also be cancelled, not just the next scheduled action.
+	 * Any recurring actions with a matching hook should also be cancelled, not just the next scheduled action.
 	 *
 	 * @param string $hook The hook that the job will trigger
 	 * @param array $args Args that would have been passed to the job
@@ -85,6 +85,15 @@ interface WC_Queue_Interface {
 	 */
 	public function cancel( $hook, $args = array(), $group = '' );
 
+	/**
+	 * Dequeue all actions with a matching hook (and optionally matching args and group) so no matching actions are ever run.
+	 *
+	 * @param string $hook The hook that the job will trigger
+	 * @param array $args Args that would have been passed to the job
+	 * @param string $group
+	 */
+	public function cancel_all( $hook, $args = array(), $group = '' );
+
 	/**
 	 * Get the date and time for the next scheduled occurence of an action with a given hook
 	 * (an optionally that matches certain args and group), if any.

includes/queue/class-wc-action-queue.php

@@ -83,13 +83,16 @@ class WC_Action_Queue implements WC_Queue_Interface {
 	}
 
 	/**
-	 * Dequeue all actions with a matching hook (and optionally matching args and group) so they are not run.
+	 * Dequeue the next scheduled instance of an action with a matching hook (and optionally matching args and group).
 	 *
-	 * Any recurring actions with a matching hook will also be cancelled, not just the next scheduled action.
+	 * Any recurring actions with a matching hook should also be cancelled, not just the next scheduled action.
 	 *
-	 * Technically, one action in a recurring or Cron action is scheduled at any one point in time. The next
-	 * in the sequence is scheduled after the previous one is run, so only the next scheduled action needs to
-	 * be cancelled/dequeued to stop the sequence.
+	 * While technically only the next instance of a recurring or cron action is unscheduled by this method, that will also
+	 * prevent all future instances of that recurring or cron action from being run. Recurring and cron actions are scheduled
+	 * in a sequence instead of all being scheduled at once. Each successive occurrence of a recurring action is scheduled
+	 * only after the former action is run. As the next instance is never run, because it's unscheduled by this function,
+	 * then the following instance will never be scheduled (or exist), which is effectively the same as being unscheduled
+	 * by this method also.
 	 *
 	 * @param string $hook The hook that the job will trigger.
 	 * @param array  $args Args that would have been passed to the job.
@@ -99,6 +102,17 @@ class WC_Action_Queue implements WC_Queue_Interface {
 		as_unschedule_action( $hook, $args, $group );
 	}
 
+	/**
+	 * Dequeue all actions with a matching hook (and optionally matching args and group) so no matching actions are ever run.
+	 *
+	 * @param string $hook The hook that the job will trigger.
+	 * @param array  $args Args that would have been passed to the job.
+	 * @param string $group Group name.
+	 */
+	public function cancel_all( $hook, $args = array(), $group = '' ) {
+		as_unschedule_all_actions( $hook, $args, $group );
+	}
+
 	/**
 	 * Get the date and time for the next scheduled occurence of an action with a given hook
 	 * (an optionally that matches certain args and group), if any.