Ultimate Member - PHPDoc
\
Action_Scheduler
Migration
WP_CLI
um
action_scheduler
admin
core
ajax
common
actions
core
rest
frontend
widgets

includes/lib/action-schedulerfunctions.php

General API functions for scheduling actions

Functions

as_enqueue_async_action()

as_enqueue_async_action(string  $hook, array  $args = array(), string  $group = '', bool  $unique = false, int  $priority = 10) : int

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

Parameters

string $hook

The hook to trigger.
array $args

Arguments to pass when the hook triggers.
string $group

The group to assign this job to.
bool $unique

Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
int $priority

Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.

Returns

int —

The action ID. Zero if there was an error scheduling the action.

as_schedule_single_action()

as_schedule_single_action(int  $timestamp, string  $hook, array  $args = array(), string  $group = '', bool  $unique = false, int  $priority = 10) : int

Schedule an action to run one time

Parameters

int $timestamp

When the job will run.
string $hook

The hook to trigger.
array $args

Arguments to pass when the hook triggers.
string $group

The group to assign this job to.
bool $unique

Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
int $priority

Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.

Returns

int —

The action ID. Zero if there was an error scheduling the action.

as_schedule_recurring_action()

as_schedule_recurring_action(int  $timestamp, int  $interval_in_seconds, string  $hook, array  $args = array(), string  $group = '', bool  $unique = false, int  $priority = 10) : int

Schedule a recurring action

Parameters

int $timestamp

When the first instance of the job will run.
int $interval_in_seconds

How long to wait between runs.
string $hook

The hook to trigger.
array $args

Arguments to pass when the hook triggers.
string $group

The group to assign this job to.
bool $unique

Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
int $priority

Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.

Returns

int —

The action ID. Zero if there was an error scheduling the action.

as_schedule_cron_action()

as_schedule_cron_action(int  $timestamp, string  $schedule, string  $hook, array  $args = array(), string  $group = '', bool  $unique = false, int  $priority = 10) : int

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

Parameters

int $timestamp

The first instance of the action will be scheduled to run at a time calculated after this timestamp matching the cron expression. This can be used to delay the first instance of the action.
string $schedule

A cron-link schedule string.
string $hook

The hook to trigger.
array $args

Arguments to pass when the hook triggers.
string $group

The group to assign this job to.
bool $unique

Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
int $priority

Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.

Returns

int —

The action ID. Zero if there was an error scheduling the action.

as_unschedule_action()

as_unschedule_action(string  $hook, array  $args = array(), string  $group = '') : int|null

Cancel the next occurrence of a scheduled action.

While 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. If 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

string $hook

The hook that the job will trigger.
array $args

Args that would have been passed to the job.
string $group

The group the job is assigned to.

Returns

int|null —

The scheduled action ID if a scheduled action was found, or null if no matching action found.

as_unschedule_all_actions()

as_unschedule_all_actions(string  $hook, array  $args = array(), string  $group = '') : mixed

Cancel all occurrences of a scheduled action.

Parameters

string $hook

The hook that the job will trigger.
array $args

Args that would have been passed to the job.
string $group

The group the job is assigned to.

Returns

mixed

as_next_scheduled_action()

as_next_scheduled_action(string  $hook, array  $args = null, string  $group = '') : int|bool

Check if there is an existing action in the queue with a given hook, args and group combination.

An action in the queue could be pending, in-progress or async. If the is pending for a time in future, its scheduled date will be returned as a timestamp. If it is currently being run, or an async action sitting in the queue waiting to be processed, in which case boolean true will be returned. Or there may be no async, in-progress or pending action for this hook, in which case, boolean false will be the return value.

Parameters

string $hook

Name of the hook to search for.
array $args

Arguments of the action to be searched.
string $group

Group of the action to be searched.

Returns

int|bool —

The timestamp for the next occurrence of a pending scheduled action, true for an async or in-progress action or false if there is no matching action.

as_has_scheduled_action()

as_has_scheduled_action(string  $hook, array  $args = null, string  $group = '') : bool

Check if there is a scheduled action in the queue but more efficiently than as_next_scheduled_action().

It's recommended to use this function when you need to know whether a specific action is currently scheduled (pending or in-progress).

Parameters

string $hook

The hook of the action.
array $args

Args that have been passed to the action. Null will matches any args.
string $group

The group the job is assigned to.

Returns

bool —

True if a matching action is pending or in-progress, false otherwise.

as_get_scheduled_actions()

as_get_scheduled_actions(array  $args = array(), string  $return_format = OBJECT) : array

Find scheduled actions

Parameters

array $args

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', 'date' or 'none'. 'order' => 'ASC'.
string $return_format

OBJECT, ARRAY_A, or ids.

Returns

array

as_get_datetime_object()

as_get_datetime_object(mixed  $date_string = null, string  $timezone = 'UTC') : \ActionScheduler_DateTime

Helper function to create an instance of DateTime based on a given string and timezone. By default, will return the current date/time in the UTC timezone.

Needed because new DateTime() called without an explicit timezone will create a date/time in PHP's timezone, but we need to have assurance that a date/time uses the right timezone (which we almost always want to be UTC), which means we need to always include the timezone when instantiating datetimes rather than leaving it up to the PHP default.

Parameters

mixed $date_string

A date/time string. Valid formats are explained in http://php.net/manual/en/datetime.formats.php.
string $timezone

A timezone identifier, like UTC or Europe/Lisbon. The list of valid identifiers is available http://php.net/manual/en/timezones.php.

Returns

\ActionScheduler_DateTime