WooCommerce Code Reference

WC_Action_Queue
in package
implements WC_Queue_Interface

WC Action Queue

A job queue using WordPress actions.

Tags
version
3.5.0

Interfaces, Classes and Traits

WC_Queue_Interface
WC Queue Interface

Table of Contents

add()  : string
Enqueue an action to run one time, as soon as possible
cancel()  : mixed
Dequeue the next scheduled instance of an action with a matching hook (and optionally matching args and group).
cancel_all()  : mixed
Dequeue all actions with a matching hook (and optionally matching args and group) so no matching actions are ever run.
get_next()  : WC_DateTime|null
Get the date and time for the next scheduled occurrence of an action with a given hook (an optionally that matches certain args and group), if any.
schedule_cron()  : string
Schedule an action that recurs on a cron-like schedule.
schedule_recurring()  : string
Schedule a recurring action
schedule_single()  : string
Schedule an action to run once at some time in the future
search()  : array<string|int, mixed>
Find scheduled actions

Methods

add()

Enqueue an action to run one time, as soon as possible

public add(string $hook[, array<string|int, mixed> $args = array() ][, string $group = '' ]) : string
Parameters
$hook : string

The hook to trigger.

$args : array<string|int, mixed> = array()

Arguments to pass when the hook triggers.

$group : string = ''

The group to assign this job to.

Return values
stringThe action ID.

cancel()

Dequeue the next scheduled instance of an action with a matching hook (and optionally matching args and group).

public cancel(string $hook[, array<string|int, mixed> $args = array() ][, string $group = '' ]) : mixed

Any recurring actions with a matching hook should also be cancelled, not just the next scheduled action.

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.

Parameters
$hook : string

The hook that the job will trigger.

$args : array<string|int, mixed> = array()

Args that would have been passed to the job.

$group : string = ''

The group the job is assigned to (if any).

Return values
mixed

cancel_all()

Dequeue all actions with a matching hook (and optionally matching args and group) so no matching actions are ever run.

public cancel_all(string $hook[, array<string|int, mixed> $args = array() ][, string $group = '' ]) : mixed
Parameters
$hook : string

The hook that the job will trigger.

$args : array<string|int, mixed> = array()

Args that would have been passed to the job.

$group : string = ''

The group the job is assigned to (if any).

Return values
mixed

get_next()

Get the date and time for the next scheduled occurrence of an action with a given hook (an optionally that matches certain args and group), if any.

public get_next(string $hook[, array<string|int, mixed> $args = null ][, string $group = '' ]) : WC_DateTime|null
Parameters
$hook : string

The hook that the job will trigger.

$args : array<string|int, mixed> = null

Filter to a hook with matching args that will be passed to the job when it runs.

$group : string = ''

Filter to only actions assigned to a specific group.

Return values
WC_DateTime|nullThe date and time for the next occurrence, or null if there is no pending, scheduled action for the given hook.

schedule_cron()

Schedule an action that recurs on a cron-like schedule.

public schedule_cron(int $timestamp, string $cron_schedule, string $hook[, array<string|int, mixed> $args = array() ][, string $group = '' ]) : string
Parameters
$timestamp : int

The schedule will start on or after this time.

$cron_schedule : string

A cron-link schedule string.

$hook : string

The hook to trigger.

$args : array<string|int, mixed> = array()

Arguments to pass when the hook triggers.

$group : string = ''

The group to assign this job to.

Tags
see
http://en.wikipedia.org/wiki/Cron

┬ ┬ ┬ ┬ ┬ ┬ | | | | | | | | | | | + year [optional] | | | | +----- day of week (0 - 7) (Sunday=0 or 7) | | | +---------- month (1 - 12) | | +--------------- day of month (1 - 31) | +-------------------- hour (0 - 23) +------------------------- min (0 - 59)

Return values
stringThe action ID

schedule_recurring()

Schedule a recurring action

public schedule_recurring(int $timestamp, int $interval_in_seconds, string $hook[, array<string|int, mixed> $args = array() ][, string $group = '' ]) : string
Parameters
$timestamp : int

When the first instance of the job will run.

$interval_in_seconds : int

How long to wait between runs.

$hook : string

The hook to trigger.

$args : array<string|int, mixed> = array()

Arguments to pass when the hook triggers.

$group : string = ''

The group to assign this job to.

Return values
stringThe action ID.

schedule_single()

Schedule an action to run once at some time in the future

public schedule_single(int $timestamp, string $hook[, array<string|int, mixed> $args = array() ][, string $group = '' ]) : string
Parameters
$timestamp : int

When the job will run.

$hook : string

The hook to trigger.

$args : array<string|int, mixed> = array()

Arguments to pass when the hook triggers.

$group : string = ''

The group to assign this job to.

Return values
stringThe action ID.

Find scheduled actions

public search([array<string|int, mixed> $args = array() ][, string $return_format = OBJECT ]) : array<string|int, mixed>
Parameters
$args : array<string|int, mixed> = array()

Possible arguments, with their default values: 'hook' => '' - the name of the action that will be triggered 'args' => null - the args array that will be passed with the action 'date' => null - the scheduled date of the action. Expects a DateTime object, a unix timestamp, or a string that can parsed with strtotime(). Used in UTC timezone. 'date_compare' => '<=' - operator for testing "date". accepted values are '!=', '>', '>=', '<', '<=', '=' 'modified' => null - the date the action was last updated. Expects a DateTime object, a unix timestamp, or a string that can parsed with strtotime(). Used in UTC timezone. 'modified_compare' => '<=' - operator for testing "modified". accepted values are '!=', '>', '>=', '<', '<=', '=' 'group' => '' - the group the action belongs to 'status' => '' - ActionScheduler_Store::STATUS_COMPLETE or ActionScheduler_Store::STATUS_PENDING 'claimed' => null - TRUE to find claimed actions, FALSE to find unclaimed actions, a string to find a specific claim ID 'per_page' => 5 - Number of results to return 'offset' => 0 'orderby' => 'date' - accepted values are 'hook', 'group', 'modified', or 'date' 'order' => 'ASC'.

$return_format : string = OBJECT

OBJECT, ARRAY_A, or ids.

Return values
array<string|int, mixed>