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

\ActionScheduler_DBStoreMigrator

Class ActionScheduler_DBStoreMigrator

A class for direct saving of actions to the table data store during migration.

Summary

Methods
Properties
Constants
init()
save_unique_action()
save_action()
fetch_action()
query_actions()
action_counts()
cancel_action()
cancel_actions_by_hook()
cancel_actions_by_group()
delete_action()
get_date()
stake_claim()
set_claim_filter()
get_claim_filter()
get_claim_count()
get_claim_id()
find_actions_by_claim_id()
release_claim()
unclaim_action()
mark_failure()
log_execution()
mark_complete()
get_status()
find_action()
query_action()
extra_action_counts()
get_status_labels()
has_pending_actions_due()
mark_migrated()
instance()
mark_failed_fetch_action()
No public properties found
STATUS_COMPLETE
STATUS_PENDING
STATUS_RUNNING
STATUS_FAILED
STATUS_CANCELED
DEFAULT_CLASS
hash_args()
get_args_for_query()
get_group_ids()
create_group()
get_null_action()
make_action_from_db_record()
get_query_actions_sql()
get_date_gmt()
generate_claim_id()
claim_actions()
validate_sql_comparator()
get_scheduled_date_string()
get_scheduled_date_string_local()
validate_args()
validate_schedule()
validate_action()
hook()
unhook()
get_local_timezone()
$max_args_length
$max_index_length
$claim_filters
N/A
save_action_to_db()
build_insert_sql()
build_where_clause_for_insert()
get_placeholder_for_column()
bulk_cancel_actions()
$claim_before_date
$store
N/A

Constants

STATUS_COMPLETE

STATUS_COMPLETE = 'complete'

STATUS_PENDING

STATUS_PENDING = 'pending'

STATUS_RUNNING

STATUS_RUNNING = 'in-progress'

STATUS_FAILED

STATUS_FAILED = 'failed'

STATUS_CANCELED

STATUS_CANCELED = 'canceled'

DEFAULT_CLASS

DEFAULT_CLASS = 'ActionScheduler_wpPostStore'

Properties

$max_args_length

$max_args_length : int

Maximum length of args.

Type

normal

$max_index_length

$max_index_length : int

Maximum length of index.

Type

normal

$claim_filters

$claim_filters : array

List of claim filters.

Type

normal

$claim_before_date

$claim_before_date : \DateTime|null

Used to share information about the before_date property of claims internally.

This is used in preference to passing the same information as a method param for backwards-compatibility reasons.

Type

normal

$store

$store : \ActionScheduler_Store

ActionScheduler_Store instance.

Type

normal

Methods

init()

init() : mixed

Callable initialization function optionally overridden in derived classes.

Returns

mixed

save_unique_action()

save_unique_action(\ActionScheduler_Action  $action, \DateTime|null  $scheduled_date = null) : int

Save an action, checks if this is a unique action before actually saving.

Parameters

\ActionScheduler_Action $action

Action object.
\DateTime|null $scheduled_date

Optional schedule date. Default null.

Throws

\RuntimeException

Throws exception when saving the action fails.

Returns

int —

Action ID.

save_action()

save_action(\ActionScheduler_Action  $action, null|\DateTime  $scheduled_date = null, null|\DateTime  $last_attempt_date = null) : string

Save an action with optional last attempt date.

Normally, saving an action sets its attempted date to 0000-00-00 00:00:00 because when an action is first saved, it can't have been attempted yet, but migrated completed actions will have an attempted date, so we need to save that when first saving the action.

Parameters

\ActionScheduler_Action $action

Action to migrate.
null|\DateTime $scheduled_date

Optional date of the first instance to store.
null|\DateTime $last_attempt_date

Optional date the action was last attempted.

Throws

\RuntimeException

When the action is not saved.

Returns

string —

The action ID

fetch_action()

fetch_action(string  $action_id) : \ActionScheduler_Action

Get action.

Parameters

string $action_id

Action ID.

Returns

\ActionScheduler_Action

query_actions()

query_actions(array  $query = array(), string  $query_type = 'select') : string|array|null

Query for action count or list of action IDs.

Parameters

array $query

{ Query filtering options.

 @type string       $hook             The name of the actions. Optional.
 @type string|array $status           The status or statuses of the actions. Optional.
 @type array        $args             The args array of the actions. Optional.
 @type DateTime     $date             The scheduled date of the action. Used in UTC timezone. Optional.
 @type string       $date_compare     Operator for selecting by $date param. Accepted values are '!=', '>', '>=', '<', '<=', '='. Defaults to '<='.
 @type DateTime     $modified         The last modified date of the action. Used in UTC timezone. Optional.
 @type string       $modified_compare Operator for comparing $modified param. Accepted values are '!=', '>', '>=', '<', '<=', '='. Defaults to '<='.
 @type string       $group            The group the action belongs to. Optional.
 @type bool|int     $claimed          TRUE to find claimed actions, FALSE to find unclaimed actions, an int to find a specific claim ID. Optional.
 @type int          $per_page         Number of results to return. Defaults to 5.
 @type int          $offset           The query pagination offset. Defaults to 0.
 @type int          $orderby          Accepted values are 'hook', 'group', 'modified', 'date' or 'none'. Defaults to 'date'.
 @type string       $order            Accepted values are 'ASC' or 'DESC'. Defaults to 'ASC'.

}
string $query_type

Whether to select or count the results. Default, select.

Returns

string|array|null —

The IDs of actions matching the query. Null on failure.

action_counts()

action_counts() : array

Get a count of all actions in the store, grouped by status

Returns

array

cancel_action()

cancel_action(string  $action_id) : mixed

Cancel action.

Parameters

string $action_id

Action ID.

Returns

mixed

cancel_actions_by_hook()

cancel_actions_by_hook(string  $hook) : void

Cancel pending actions by hook.

Parameters

string $hook

Hook name.

cancel_actions_by_group()

cancel_actions_by_group(string  $group) : void

Cancel pending actions by group.

Parameters

string $group

Group slug.

delete_action()

delete_action(string  $action_id) : mixed

Delete action.

Parameters

string $action_id

Action ID.

Returns

mixed

get_date()

get_date(string  $action_id) : \DateTime

Get action's schedule or run timestamp.

Parameters

string $action_id

Action ID.

Returns

\DateTime —

The date the action is schedule to run, or the date that it ran.

stake_claim()

stake_claim(int  $max_actions = 10, \DateTime|null  $before_date = null, array  $hooks = array(), string  $group = '') : \ActionScheduler_ActionClaim

Make a claim.

Parameters

int $max_actions

Maximum number of actions to claim.
\DateTime|null $before_date

Claim only actions schedule before the given date. Defaults to now.
array $hooks

Claim only actions with a hook or hooks.
string $group

Claim only actions in the given group.

Returns

\ActionScheduler_ActionClaim

set_claim_filter()

set_claim_filter(string  $filter_name, mixed  $filter_values) : void

Set a claim filter.

Parameters

string $filter_name

Claim filter name.
mixed $filter_values

Values to filter.

get_claim_filter()

get_claim_filter(string  $filter_name) : mixed

Get the claim filter value.

Parameters

string $filter_name

Claim filter name.

Returns

mixed

get_claim_count()

get_claim_count() : int

Get claim count.

Returns

int

get_claim_id()

get_claim_id(string  $action_id) : mixed

Get action's claim ID.

Parameters

string $action_id

Action ID.

Returns

mixed

find_actions_by_claim_id()

find_actions_by_claim_id(string  $claim_id) : array

Find actions by claim ID.

Parameters

string $claim_id

Claim ID.

Returns

array

release_claim()

release_claim(\ActionScheduler_ActionClaim  $claim) : mixed

Release the claim.

Parameters

\ActionScheduler_ActionClaim $claim

Claim object.

Returns

mixed

unclaim_action()

unclaim_action(string  $action_id) : mixed

Un-claim the action.

Parameters

string $action_id

Action ID.

Returns

mixed

mark_failure()

mark_failure(string  $action_id) : mixed

Mark action as failed.

Parameters

string $action_id

Action ID.

Returns

mixed

log_execution()

log_execution(string  $action_id) : mixed

Log action's execution.

Parameters

string $action_id

Actoin ID.

Returns

mixed

mark_complete()

mark_complete(string  $action_id) : mixed

Mark action as complete.

Parameters

string $action_id

Action ID.

Returns

mixed

get_status()

get_status(string  $action_id) : string

Get action's status.

Parameters

string $action_id

Action ID.

Returns

string

find_action()

find_action(string  $hook, array  $params = array()) : string|null

Find an action.

Note: the query ordering changes based on the passed 'status' value.

Parameters

string $hook

Action hook.
array $params

Parameters of the action to find.

Returns

string|null —

ID of the next action matching the criteria or NULL if not found.

query_action()

query_action(array  $query) : int|null

Run query to get a single action ID.

Parameters

array $query

Query parameters.

Returns

int|null

extra_action_counts()

extra_action_counts() : array

Get additional action counts.

  • add past-due actions

Returns

array

get_status_labels()

get_status_labels() : array<string,string>

Get status labels.

Returns

array

has_pending_actions_due()

has_pending_actions_due() : string

Check if there are any pending scheduled actions due to run.

Returns

string

mark_migrated()

mark_migrated(int  $action_id) : mixed

Callable function to mark an action as migrated optionally overridden in derived classes.

Parameters

int $action_id

Action ID.

Returns

mixed

instance()

instance() : \ActionScheduler_Store

Get instance.

Returns

\ActionScheduler_Store

mark_failed_fetch_action()

mark_failed_fetch_action(int  $action_id) : mixed

Mark an action that failed to fetch correctly as failed.

Parameters

int $action_id

The ID of the action.

Returns

mixed

hash_args()

hash_args(string  $args) : string

Generate a hash from json_encoded $args using MD5 as this isn't for security.

Parameters

string $args

JSON encoded action args.

Returns

string

get_args_for_query()

get_args_for_query(array  $args) : string

Get action args query param value from action args.

Parameters

array $args

Action args.

Returns

string

get_group_ids()

get_group_ids(string|array  $slugs, bool  $create_if_not_exists = true) : array

Get a group's ID based on its name/slug.

Parameters

string|array $slugs

The string name of a group, or names for several groups.
bool $create_if_not_exists

Whether to create the group if it does not already exist. Default, true - create the group.

Returns

array —

The group IDs, if they exist or were successfully created. May be empty.

create_group()

create_group(string  $slug) : int

Create an action group.

Parameters

string $slug

Group slug.

Returns

int —

Group ID.

get_null_action()

get_null_action() : \ActionScheduler_NullAction

Create a null action.

Returns

\ActionScheduler_NullAction

make_action_from_db_record()

make_action_from_db_record(object  $data) : \ActionScheduler_Action|\ActionScheduler_CanceledAction|\ActionScheduler_FinishedAction

Create an action from a database record.

Parameters

object $data

Action database record.

Returns

\ActionScheduler_Action|\ActionScheduler_CanceledAction|\ActionScheduler_FinishedAction

get_query_actions_sql()

get_query_actions_sql(array  $query, string  $select_or_count = 'select') : string

Returns the SQL statement to query (or count) actions.

Parameters

array $query

Filtering options.
string $select_or_count

Whether the SQL should select and return the IDs or just the row count.

Throws

\InvalidArgumentException

If the query is invalid.

\RuntimeException

When "unknown partial args matching value".

Returns

string —

SQL statement already properly escaped.

get_date_gmt()

get_date_gmt(int  $action_id) : \DateTime

Get the GMT schedule date for an action.

Parameters

int $action_id

Action ID.

Throws

\InvalidArgumentException

If action cannot be identified.

Returns

\DateTime —

The GMT date the action is scheduled to run, or the date that it ran.

generate_claim_id()

generate_claim_id() : int

Generate a new action claim.

Returns

int —

Claim ID.

claim_actions()

claim_actions(string  $claim_id, int  $limit, \DateTime|null  $before_date = null, array  $hooks = array(), string  $group = '') : int

Mark actions claimed.

Parameters

string $claim_id

Claim Id.
int $limit

Number of action to include in claim.
\DateTime|null $before_date

Should use UTC timezone.
array $hooks

Hooks to filter for.
string $group

Group to filter for.

Throws

\InvalidArgumentException

Throws InvalidArgumentException if group doesn't exist.

\RuntimeException

Throws RuntimeException if unable to claim action.

Returns

int —

The number of actions that were claimed.

validate_sql_comparator()

validate_sql_comparator(string  $comparison_operator) : string

Validate SQL operator.

Parameters

string $comparison_operator

Operator.

Returns

string

get_scheduled_date_string()

get_scheduled_date_string(\ActionScheduler_Action  $action, null|\DateTime  $scheduled_date = null) : string

Get the time MySQL formatted date/time string for an action's (next) scheduled date.

Parameters

\ActionScheduler_Action $action

Action.
null|\DateTime $scheduled_date

Action's schedule date (optional).

Returns

string

get_scheduled_date_string_local()

get_scheduled_date_string_local(\ActionScheduler_Action|null  $action, null|\DateTime  $scheduled_date = null) : string

Get the time MySQL formatted date/time string for an action's (next) scheduled date.

Parameters

\ActionScheduler_Action|null $action

Action.
null|\DateTime $scheduled_date

Action's scheduled date (optional).

Returns

string

validate_args()

validate_args(mixed  $args, int  $action_id) : mixed

Validate that we could decode action arguments.

Parameters

mixed $args

The decoded arguments.
int $action_id

The action ID.

Throws

\ActionScheduler_InvalidActionException

When the decoded arguments are invalid.

Returns

mixed

validate_schedule()

validate_schedule(mixed  $schedule, int  $action_id) : mixed

Validate a ActionScheduler_Schedule object.

Parameters

mixed $schedule

The unserialized ActionScheduler_Schedule object.
int $action_id

The action ID.

Throws

\ActionScheduler_InvalidActionException

When the schedule is invalid.

Returns

mixed

validate_action()

validate_action(\ActionScheduler_Action  $action) : mixed

InnoDB indexes have a maximum size of 767 bytes by default, which is only 191 characters with utf8mb4.

Previously, AS wasn't concerned about args length, as we used the (unindex) post_content column. However, with custom tables, we use an indexed VARCHAR column instead.

Parameters

\ActionScheduler_Action $action

Action to be validated.

Throws

\InvalidArgumentException

When json encoded args is too long.

Returns

mixed

hook()

hook() : mixed

Add base hooks

Returns

mixed

unhook()

unhook() : mixed

Remove base hooks

Returns

mixed

get_local_timezone()

get_local_timezone() : \DateTimeZone

Get the site's local time.

Returns

\DateTimeZone

save_action_to_db()

save_action_to_db(\ActionScheduler_Action  $action, ?\DateTime  $date = null, bool  $unique = false) : int

Save an action.

Parameters

\ActionScheduler_Action $action

Action object.
?\DateTime $date

Optional schedule date. Default null.
bool $unique

Whether the action should be unique.

Throws

\RuntimeException

Throws exception when saving the action fails.

Returns

int —

Action ID.

build_insert_sql()

build_insert_sql(array  $data, bool  $unique) : string

Helper function to build insert query.

Parameters

array $data

Row data for action.
bool $unique

Whether the action should be unique.

Returns

string —

Insert query.

build_where_clause_for_insert()

build_where_clause_for_insert(array  $data, string  $table_name, bool  $unique) : string

Helper method to build where clause for action insert statement.

Parameters

array $data

Row data for action.
string $table_name

Action table name.
bool $unique

Where action should be unique.

Returns

string —

Where clause to be used with insert.

get_placeholder_for_column()

get_placeholder_for_column(string  $column_name) : string

Helper method to get $wpdb->prepare placeholder for a given column name.

Parameters

string $column_name

Name of column in actions table.

Returns

string —

Placeholder to use for given column.

bulk_cancel_actions()

bulk_cancel_actions(int[]  $action_ids) : void

Cancel a set of action IDs.

Parameters

int[] $action_ids

List of action IDs.