Documentation

ActionScheduler_wpPostStore extends ActionScheduler_Store
in package

Class ActionScheduler_wpPostStore

Table of Contents

GROUP_TAXONOMY  = 'action-group'
POST_TYPE  = 'scheduled-action'
SCHEDULE_META_KEY  = '_action_manager_schedule'
STATUS_CANCELED  = 'canceled'
STATUS_COMPLETE  = 'complete'
STATUS_FAILED  = 'failed'
STATUS_PENDING  = 'pending'
STATUS_RUNNING  = 'in-progress'
$local_timezone  : DateTimeZone
$max_index_length  : int
$store  : ActionScheduler_Store
action_counts()  : array<string|int, mixed>
Get a count of all actions in the store, grouped by status
cancel_action()  : mixed
delete_action()  : mixed
fetch_action()  : ActionScheduler_Action
filter_insert_post_data()  : mixed
find_action()  : string
find_actions_by_claim_id()  : array<string|int, mixed>
get_claim_count()  : int
get_claim_id()  : mixed
Return an action's claim ID, as stored in the post password column
get_date()  : ActionScheduler_DateTime
get_date_gmt()  : ActionScheduler_DateTime
get_status()  : mixed
Return an action's status, as stored in the post status column
get_status_labels()  : array<string|int, mixed>
init()  : mixed
instance()  : ActionScheduler_Store
log_execution()  : mixed
mark_complete()  : mixed
mark_failure()  : mixed
query_actions()  : string|array<string|int, mixed>
release_claim()  : mixed
save_action()  : string
set_unique_post_slug()  : string
Create a (probably unique) post name for scheduled actions in a more performant manner than wp_unique_post_slug().
stake_claim()  : ActionScheduler_ActionClaim
unclaim_action()  : mixed
claim_actions()  : int
create_post_array()  : mixed
generate_claim_id()  : mixed
get_action_status_by_post_status()  : string
get_actions_by_group()  : array<string|int, mixed>
Get IDs of actions within a certain group and up to a certain date/time.
get_local_timezone()  : DateTimeZone
Get the site's local time.
get_null_action()  : mixed
get_post()  : mixed
get_post_status_by_action_status()  : string
get_query_actions_sql()  : string
Returns the SQL statement to query (or count) actions.
get_scheduled_date_string()  : string
Get the time MySQL formated date/time string for an action's (next) scheduled date.
get_scheduled_date_string_local()  : string
Get the time MySQL formated date/time string for an action's (next) scheduled date.
make_action_from_post()  : mixed
save_action_group()  : mixed
save_post_array()  : mixed
save_post_schedule()  : mixed
validate_action()  : mixed
InnoDB indexes have a maximum size of 767 bytes by default, which is only 191 characters with utf8mb4.
validate_sql_comparator()  : string
get_post_column()  : mixed
validate_args()  : mixed
Validate that we could decode action arguments.

Constants

Properties

Methods

action_counts()

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

public action_counts() : array<string|int, mixed>
Return values
array<string|int, mixed>

cancel_action()

public cancel_action(string $action_id) : mixed
Parameters
$action_id : string
Tags
throws
InvalidArgumentException
Return values
mixed

delete_action()

public delete_action(mixed $action_id) : mixed
Parameters
$action_id : mixed
Return values
mixed

filter_insert_post_data()

public filter_insert_post_data(mixed $postdata) : mixed
Parameters
$postdata : mixed
Return values
mixed

find_action()

public find_action(string $hook[, array<string|int, mixed> $params = array() ]) : string
Parameters
$hook : string
$params : array<string|int, mixed> = array()
Return values
string

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

find_actions_by_claim_id()

public find_actions_by_claim_id(string $claim_id) : array<string|int, mixed>
Parameters
$claim_id : string
Return values
array<string|int, mixed>

get_claim_id()

Return an action's claim ID, as stored in the post password column

public get_claim_id(string $action_id) : mixed
Parameters
$action_id : string
Return values
mixed

get_status()

Return an action's status, as stored in the post status column

public get_status(string $action_id) : mixed
Parameters
$action_id : string
Return values
mixed

get_status_labels()

public get_status_labels() : array<string|int, mixed>
Return values
array<string|int, mixed>

log_execution()

public log_execution(string $action_id) : mixed
Parameters
$action_id : string
Return values
mixed

mark_complete()

public mark_complete(mixed $action_id) : mixed
Parameters
$action_id : mixed
Return values
mixed

mark_failure()

public mark_failure(mixed $action_id) : mixed
Parameters
$action_id : mixed
Return values
mixed

query_actions()

public query_actions([array<string|int, mixed> $query = array() ][, string $query_type = 'select' ]) : string|array<string|int, mixed>
Parameters
$query : array<string|int, mixed> = array()
$query_type : string = 'select'

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

Return values
string|array<string|int, mixed>

The IDs of actions matching the query

set_unique_post_slug()

Create a (probably unique) post name for scheduled actions in a more performant manner than wp_unique_post_slug().

public set_unique_post_slug(string $override_slug, string $slug, int $post_ID, string $post_status, string $post_type) : string

When an action's post status is transitioned to something other than 'draft', 'pending' or 'auto-draft, like 'publish' or 'failed' or 'trash', WordPress will find a unique slug (stored in post_name column) using the wp_unique_post_slug() function. This is done to ensure URL uniqueness. The approach taken by wp_unique_post_slug() is to iterate over existing post_name values that match, and append a number 1 greater than the largest. This makes sense when manually creating a post from the Edit Post screen. It becomes a bottleneck when automatically processing thousands of actions, with a database containing thousands of related post_name values.

WordPress 5.1 introduces the 'pre_wp_unique_post_slug' filter for plugins to address this issue.

We can short-circuit WordPress's wp_unique_post_slug() approach using the 'pre_wp_unique_post_slug' filter. This method is available to be used as a callback on that filter. It provides a more scalable approach to generating a post_name/slug that is probably unique. Because Action Scheduler never actually uses the post_name field, or an action's slug, being probably unique is good enough.

For more backstory on this issue, see:

  • https://github.com/Prospress/action-scheduler/issues/44 and
  • https://core.trac.wordpress.org/ticket/21112
Parameters
$override_slug : string

Short-circuit return value.

$slug : string

The desired slug (post_name).

$post_ID : int

Post ID.

$post_status : string

The post status.

$post_type : string

Post type.

Return values
string

stake_claim()

public stake_claim([int $max_actions = 10 ][, DateTime $before_date = null ][, array<string|int, mixed> $hooks = array() ][, string $group = '' ]) : ActionScheduler_ActionClaim
Parameters
$max_actions : int = 10
$before_date : DateTime = null

Jobs must be schedule before this date. Defaults to now.

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

Claim only actions with a hook or hooks.

$group : string = ''

Claim only actions in the given group.

Tags
throws
RuntimeException

When there is an error staking a claim.

throws
InvalidArgumentException

When the given group is not valid.

Return values
ActionScheduler_ActionClaim

unclaim_action()

public unclaim_action(string $action_id) : mixed
Parameters
$action_id : string
Return values
mixed

claim_actions()

protected claim_actions(string $claim_id, int $limit[, DateTime $before_date = null ][, array<string|int, mixed> $hooks = array() ][, string $group = '' ]) : int
Parameters
$claim_id : string
$limit : int
$before_date : DateTime = null

Should use UTC timezone.

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

Claim only actions with a hook or hooks.

$group : string = ''

Claim only actions in the given group.

Tags
throws
RuntimeException

When there is a database error.

throws
InvalidArgumentException

When the group is invalid.

Return values
int

The number of actions that were claimed

get_action_status_by_post_status()

protected get_action_status_by_post_status(string $post_status) : string
Parameters
$post_status : string
Tags
throws
InvalidArgumentException

if $post_status not in known status fields returned by $this->get_status_labels()

Return values
string

get_actions_by_group()

Get IDs of actions within a certain group and up to a certain date/time.

protected get_actions_by_group(string $group, int $limit, DateTime $date) : array<string|int, mixed>
Parameters
$group : string

The group to use in finding actions.

$limit : int

The number of actions to retrieve.

$date : DateTime

DateTime object representing cutoff time for actions. Actions retrieved will be up to and including this DateTime.

Tags
throws
InvalidArgumentException

When the group does not exist.

Return values
array<string|int, mixed>

IDs of actions in the appropriate group and before the appropriate time.

get_local_timezone()

Get the site's local time.

protected get_local_timezone() : DateTimeZone
Tags
deprecated
2.1.0
Return values
DateTimeZone

get_post_status_by_action_status()

protected get_post_status_by_action_status(string $action_status) : string
Parameters
$action_status : string
Tags
throws
InvalidArgumentException

if $post_status not in known status fields returned by $this->get_status_labels()

Return values
string

get_query_actions_sql()

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

protected get_query_actions_sql(array<string|int, mixed> $query[, string $select_or_count = 'select' ]) : string
Parameters
$query : array<string|int, mixed>

Filtering options

$select_or_count : string = 'select'

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

Tags
throws
InvalidArgumentException

if $select_or_count not count or select

Return values
string

SQL statement. The returned SQL is already properly escaped.

get_scheduled_date_string()

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

protected get_scheduled_date_string(ActionScheduler_Action $action[, DateTime $scheduled_date = NULL ]) : string
Parameters
$action : ActionScheduler_Action
$scheduled_date : DateTime = NULL

(optional)

Return values
string

get_scheduled_date_string_local()

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

protected get_scheduled_date_string_local(ActionScheduler_Action $action[, DateTime $scheduled_date = NULL ]) : string
Parameters
$action : ActionScheduler_Action
$scheduled_date : DateTime = NULL

(optional)

Return values
string

make_action_from_post()

protected make_action_from_post(mixed $post) : mixed
Parameters
$post : mixed
Return values
mixed

save_action_group()

protected save_action_group(mixed $post_id, mixed $group) : mixed
Parameters
$post_id : mixed
$group : mixed
Return values
mixed

save_post_array()

protected save_post_array(mixed $post_array) : mixed
Parameters
$post_array : mixed
Return values
mixed

save_post_schedule()

protected save_post_schedule(mixed $post_id, mixed $schedule) : mixed
Parameters
$post_id : mixed
$schedule : mixed
Return values
mixed

validate_action()

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

protected validate_action(ActionScheduler_Action $action) : mixed

Previously, AS wasn't concerned about args length, as we used the (unindex) post_content column. However, as we prepare to move to custom tables, and can use an indexed VARCHAR column instead, we want to warn developers of this impending requirement.

Parameters
$action : ActionScheduler_Action
Return values
mixed

validate_sql_comparator()

protected validate_sql_comparator(string $comparison_operator) : string
Parameters
$comparison_operator : string
Return values
string

get_post_column()

private get_post_column(mixed $action_id, mixed $column_name) : mixed
Parameters
$action_id : mixed
$column_name : mixed
Return values
mixed

validate_args()

Validate that we could decode action arguments.

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

The decoded arguments.

$action_id : int

The action ID.

Tags
throws
ActionScheduler_InvalidActionException

When the decoded arguments are invalid.

Return values
mixed

Search results