Levente/PartnerExpo-Core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge commit 'd435f549fe9bbfbea64ed9be36104e7a23f9603c' as 'libraries/action-scheduler'

Browse Source
This commit is contained in:
Duskell
2026-03-16 13:15:04 +01:00
parent 4f75604fa0 d435f549fe
commit 76eb96666b
174 changed files with 32087 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
libraries/action-scheduler/docs/CNAME Normal file
View File

@@ -0,0 +1 @@
actionscheduler.org

7
libraries/action-scheduler/docs/_config.yml Normal file
View File

@@ -0,0 +1,7 @@
title: Action Scheduler - Job Queue for WordPress
description: A scalable, traceable job queue for background processing large queues of tasks in WordPress. Designed for distribution in WordPress plugins - no server access required.
theme: jekyll-theme-hacker
permalink: /:slug/
plugins:
- jekyll-seo-tag
- jekyll-sitemap

59
libraries/action-scheduler/docs/_layouts/default.html Normal file
View File

@@ -0,0 +1,59 @@
<!DOCTYPE html>
<html lang="{{ site.lang | default: "en-US" }}">
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="manifest" href="/site.webmanifest">
<link rel="mask-icon" href="/safari-pinned-tab.svg" color="#63c0f5">
<meta name="msapplication-TileColor" content="#151515">
<meta name="theme-color" content="#ffffff">
{% seo %}
</head>
<body>
<header>
<a class="github-corner" href="https://github.com/woocommerce/action-scheduler/" aria-label="View on GitHub">
<svg width="80" height="80" viewBox="0 0 250 250" style="fill:#b5e853; color:#151513; position: fixed; top: 0; border: 0; right: 0;" aria-hidden="true">
<path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path>
</svg>
</a>
<div class="container">
<p><a href="/usage/">Usage</a> | <a href="/admin/">Admin</a> | <a href="/wp-cli/">WP-CLI</a> | <a href="/perf/">Background Processing at Scale</a> | <a href="/api/">API</a> | <a href="/faq/">FAQ</a> | <a href="/version3-0/">Version 3.0</a>
<h1><a href="/">action-scheduler</a></h1>
<h2>A scalable, traceable job queue for background processing large queues of tasks in WordPress. Designed for distribution in WordPress plugins - no server access required.</h2>
</div>
</header>
<div class="container">
<section id="main_content">
{{ content }}
</section>
</div>
<footer>
<div class="container">
<p><a href="/usage/">Usage</a> | <a href="/admin/">Admin</a> | <a href="/wp-cli/">WP-CLI</a> | <a href="/perf/">Background Processing at Scale</a> | <a href="/api/">API</a> | <a href="/faq/">FAQ</a>
</div>
</footer>
{% if site.google_analytics %}
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', '{{ site.google_analytics }}', 'auto');
ga('send', 'pageview');
</script>
{% endif %}
</body>
</html>

22
libraries/action-scheduler/docs/admin.md Normal file
View File

@@ -0,0 +1,22 @@
---
description: Learn how to administer background jobs with the Action Scheduler job queue for WordPress.
---
# Scheduled Actions Administration Screen
Action Scheduler has a built in administration screen for monitoring, debugging and manually triggering scheduled actions.
The administration interface is accessible through both:
1. **Tools > Scheduled Actions**
1. **WooCommerce > Status > Scheduled Actions**, when WooCommerce is installed.
Among other tasks, from the admin screen you can:
* run a pending action
* view the scheduled actions with a specific status, like the all actions which have failed or are in-progress (https://cldup.com/NNTwE88Xl8.png).
* view the log entries for a specific action to find out why it failed.
* sort scheduled actions by hook name, scheduled date, claim ID or group name.
Still have questions? Check out the [FAQ](/faq).
![](https://cldup.com/5BA2BNB1sw.png)

BIN
libraries/action-scheduler/docs/android-chrome-192x192.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

BIN
libraries/action-scheduler/docs/android-chrome-256x256.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

288
libraries/action-scheduler/docs/api.md Normal file
View File

@@ -0,0 +1,288 @@
---
description: Reference guide for background processing functions provided by the Action Scheduler job queue for WordPress.
---
# API Reference
Action Scheduler provides a range of functions for scheduling hooks to run at some time in the future on one or more occasions.
To understand the scheduling functions, it can help to think of them as extensions to WordPress' `do_action()` function that add the ability to delay and repeat when the hook will be triggered.
## WP-Cron APIs vs. Action Scheduler APIs
The Action Scheduler API functions are designed to mirror the WordPress [WP-Cron API functions](http://codex.wordpress.org/Category:WP-Cron_Functions).
Functions return similar values and accept similar arguments to their WP-Cron counterparts. The notable differences are:
* `as_schedule_single_action()` & `as_schedule_recurring_action()` will return the ID of the scheduled action rather than boolean indicating whether the event was scheduled
* `as_schedule_recurring_action()` takes an interval in seconds as the recurring interval rather than an arbitrary string
* `as_schedule_single_action()` & `as_schedule_recurring_action()` can accept a `$group` parameter to group different actions for the one plugin together.
* the `wp_` prefix is substituted with `as_` and the term `event` is replaced with `action`
## API Function Availability
As mentioned in the [Usage - Load Order](usage.md#load-order) section, Action Scheduler will initialize itself on the `'init'` hook with priority `1`. While API functions are loaded prior to this and can be called, they should not be called until after `'init'` with priority `1`, because each component, like the data store, has not yet been initialized.
Do not use Action Scheduler API functions prior to `'init'` hook with priority `1`. Doing so could lead to unexpected results, like data being stored in the incorrect location. To make this easier:
- Action Scheduler provides `Action_Scheduler::is_initialized()` for use in hooks to confirm that the data stores have been initialized.
- It also provides the `'action_scheduler_init'` action hook. It is safe to call API functions during or after this event has fired (tip: you can take advantage of WordPress's [did_action()](https://developer.wordpress.org/reference/functions/did_action/) function to check this).
## Function Reference / `as_enqueue_async_action()`
### Description
Enqueue an action to run one time, as soon as possible.
### Usage
```php
as_enqueue_async_action( $hook, $args, $group, $unique, $priority );
```
### Parameters
- **$hook** (string)(required) Name of the action hook.
- **$args** (array) Arguments to pass to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group to assign this job to. Default: _''_.
- **$unique** (boolean) Whether the action should be unique. Default: _`false`_.
- **$priority** (integer) Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.
### Return value
`(integer)` the action's ID. Zero if there was an error scheduling the action. The error will be sent to `error_log`.
## Function Reference / `as_schedule_single_action()`
### Description
Schedule an action to run one time at some defined point in the future.
### Usage
```php
as_schedule_single_action( $timestamp, $hook, $args, $group, $unique, $priority );
```
### Parameters
- **$timestamp** (integer)(required) The Unix timestamp representing the date you want the action to run.
- **$hook** (string)(required) Name of the action hook.
- **$args** (array) Arguments to pass to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group to assign this job to. Default: _''_.
- **$unique** (boolean) Whether the action should be unique. Default: _`false`_.
- **$priority** (integer) Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.)
### Return value
`(integer)` the action's ID. Zero if there was an error scheduling the action. The error will be sent to `error_log`.
## Function Reference / `as_schedule_recurring_action()`
### Description
Schedule an action to run repeatedly with a specified interval in seconds.
### Usage
```php
as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args, $group, $unique, $priority );
```
### Parameters
- **$timestamp** (integer)(required) The Unix timestamp representing the date you want the action to run.
- **$interval_in_seconds** (integer)(required) How long to wait between runs.
- **$hook** (string)(required) Name of the action hook.
- **$args** (array) Arguments to pass to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group to assign this job to. Default: _''_.
- **$unique** (boolean) Whether the action should be unique. Default: _`false`_.
- **$priority** (integer) Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.
### Return value
`(integer)` the action's ID. Zero if there was an error scheduling the action. The error will be sent to `error_log`.
## Function Reference / `as_schedule_cron_action()`
### Description
Schedule an action that recurs on a cron-like schedule.
If execution of a cron-like action is delayed, the next attempt will still be scheduled according to the provided cron expression.
### Usage
```php
as_schedule_cron_action( $timestamp, $schedule, $hook, $args, $group, $unique, $priority );
```
### Parameters
- **$timestamp** (integer)(required) The Unix timestamp representing the date you want the action to run.
- **$schedule** (string)(required) $schedule A cron-like schedule string, see http://en.wikipedia.org/wiki/Cron.
- **$hook** (string)(required) Name of the action hook.
- **$args** (array) Arguments to pass to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group to assign this job to. Default: _''_.
- **$unique** (boolean) Whether the action should be unique. Default: _`false`_.
- **$priority** (integer) Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.
### Return value
`(integer)` the action's ID. Zero if there was an error scheduling the action. The error will be sent to `error_log`.
## Function Reference / `as_unschedule_action()`
### Description
Cancel the next occurrence of a scheduled action.
### Usage
```php
as_unschedule_action( $hook, $args, $group );
```
### Parameters
- **$hook** (string)(required) Name of the action hook.
- **$args** (array) Arguments passed to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group the job is assigned to. Default: _''_.
### Return value
`(null)`
## Function Reference / `as_unschedule_all_actions()`
### Description
Cancel all occurrences of a scheduled action.
### Usage
```php
as_unschedule_all_actions( $hook, $args, $group )
```
### Parameters
- **$hook** (string)(required) Name of the action hook.
- **$args** (array) Arguments passed to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group the job is assigned to. Default: _''_.
### Return value
`(string|null)` The scheduled action ID if a scheduled action was found, or null if no matching action found.
## Function Reference / `as_next_scheduled_action()`
### Description
Returns the next timestamp for a scheduled action.
### Usage
```php
as_next_scheduled_action( $hook, $args, $group );
```
### Parameters
- **$hook** (string)(required) Name of the action hook. Default: _none_.
- **$args** (array) Arguments passed to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group the job is assigned to. Default: _''_.
### Return value
`(integer|boolean)` 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.
## Function Reference / `as_has_scheduled_action()`
### Description
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. _Available since 3.3.0._
### Usage
```php
as_has_scheduled_action( $hook, $args, $group );
```
### Parameters
- **$hook** (string)(required) Name of the action hook. Default: _none_.
- **$args** (array) Arguments passed to callbacks when the hook triggers. Default: _`array()`_.
- **$group** (string) The group the job is assigned to. Default: _''_.
### Return value
`(boolean)` True if a matching action is pending or in-progress, false otherwise.
## Function Reference / `as_get_scheduled_actions()`
### Description
Find scheduled actions.
### Usage
```php
as_get_scheduled_actions( $args, $return_format );
```
### Parameters
- **$args** (array) Arguments to search and filter results by. 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().
* `'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().
* `'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) The format in which to return the scheduled actions: 'OBJECT', 'ARRAY_A', or 'ids'. Default: _'OBJECT'_.
### Return value
`(array)` Array of action rows matching the criteria specified with `$args`.
## Function Reference / `as_supports()`
### Description
Check if a specific feature is supported by the current version of Action Scheduler.
*Available since 3.9.3.*
### Usage
```php
as_supports( $feature );
```
### Parameters
**$feature** (string) (required)
The feature to check support for.
Currently supported:
- `'ensure_recurring_actions_hook'` — Indicates support for the `action_scheduler_ensure_recurring_actions` hook.
### Return value
`(boolean)`
True if the feature is supported, false otherwise.
### Example
```php
if ( as_supports( 'ensure_recurring_actions_hook' ) ) {
// Safe to depend on the 'action_scheduler_ensure_recurring_actions' hook.
add_action( 'action_scheduler_ensure_recurring_actions', 'my_plugin_schedule_my_recurring_action' );
}
```

BIN
libraries/action-scheduler/docs/apple-touch-icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

57
libraries/action-scheduler/docs/assets/css/style.scss Normal file
View File

@@ -0,0 +1,57 @@
---
---
@import "{{ site.theme }}";
a {
text-shadow: none;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
header h1 a {
color: #b5e853;
}
.container {
max-width: 700px;
}
footer {
margin-top: 6em;
padding: 1.6em 0;
border-top: 1px dashed #b5e853;
}
.footer-image {
text-align: center;
padding-top: 1em;
}
.github-corner:hover .octo-arm {
animation:octocat-wave 560ms ease-in-out
}
@keyframes octocat-wave {
0%,100%{
transform:rotate(0)
}
20%,60%{
transform:rotate(-25deg)
}
40%,80%{
transform:rotate(10deg)
}
}
@media (max-width:500px){
.github-corner:hover .octo-arm {
animation:none
}
.github-corner .octo-arm {
animation:octocat-wave 560ms ease-in-out
}
}

9
libraries/action-scheduler/docs/browserconfig.xml Normal file
View File

@@ -0,0 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<browserconfig>
<msapplication>
<tile>
<square150x150logo src="/mstile-150x150.png"/>
<TileColor>#151515</TileColor>
</tile>
</msapplication>
</browserconfig>

129
libraries/action-scheduler/docs/faq.md Normal file
View File

@@ -0,0 +1,129 @@
## FAQ
### Is it safe to release Action Scheduler in my plugin? Won't its functions conflict with another copy of the library?
Action Scheduler is designed to be used and released in plugins. It avoids redeclaring public API functions when more than one copy of the library is being loaded by different plugins. It will also load only the most recent version of itself (by checking registered versions after all plugins are loaded on the `'plugins_loaded'` hook).
To use it in your plugin (or theme), simply require the `action-scheduler/action-scheduler.php` file. Action Scheduler will take care of the rest. __Note:__ Action Scheduler is only loaded from a theme if it is not included in any active plugins.
### I don't want to use WP-Cron. Does Action Scheduler depend on WP-Cron?
By default, Action Scheduler is initiated by WP-Cron (and the `'shutdown'` hook on admin requests). However, it has no dependency on the WP-Cron system. You can initiate the Action Scheduler queue in other ways with just one or two lines of code.
For example, you can start a queue directly by calling:
```php
ActionScheduler::runner()->run();
```
Or trigger the `'action_scheduler_run_queue'` hook and let Action Scheduler do it for you:
```php
do_action( 'action_scheduler_run_queue', $context_identifier );
```
Further customization can be done by extending the `ActionScheduler_Abstract_QueueRunner` class to create a custom Queue Runner. For an example of a customized queue runner, see the [`ActionScheduler_WPCLI_QueueRunner`](https://github.com/woocommerce/action-scheduler/blob/trunk/classes/WP_CLI/ActionScheduler_WPCLI_QueueRunner.php), which is used when running WP CLI.
Want to create some other method for initiating Action Scheduler? [Open a new issue](https://github.com/woocommerce/action-scheduler/issues/new), we'd love to help you with it.
### I don't want to use WP-Cron, ever. Does Action Scheduler replace WP-Cron?
By default, Action Scheduler is designed to work alongside WP-Cron and not change any of its behaviour. This helps avoid unexpectedly overriding WP-Cron on sites installing your plugin, which may have nothing to do with WP-Cron.
However, we can understand why you might want to replace WP-Cron completely in environments within your control, especially as it gets you the advantages of Action Scheduler. This should be possible without too much code.
You could use the `'schedule_event'` hook in WordPress to use Action Scheduler for only newly scheduled WP-Cron jobs and map the `$event` param to Action Scheduler API functions.
Alternatively, you can use a combination of the `'pre_update_option_cron'` and `'pre_option_cron'` hooks to override all new and previously scheduled WP-Cron jobs (similar to the way [Cavalcade](https://github.com/humanmade/Cavalcade) does it).
If you'd like to create a plugin to do this automatically and want to share your work with others, [open a new issue to let us know](https://github.com/woocommerce/action-scheduler/issues/new), we'd love to help you with it.
### How does Action Scheduler store its data?
Action Scheduler 3.0 and newer stores data in custom tables prefixed with `actionscheduler_`. For the list of all tables and their schemas, refer to the `ActionScheduler_StoreSchema` class.
Prior to Action 3.0, actions were a custom post type, and data was stored in `wp_posts`, `wp_postmeta` and related tables.
Action Scheduler 3+ migrates data from the custom post type to custom tables.
### Can I use a different storage scheme?
Of course! Action Scheduler data storage is completely swappable, and always has been.
If you choose to, you can actually store them anywhere, like in a remote storage service from Amazon Web Services.
To implement a custom store:
1. extend the abstract `ActionScheduler_Store` class, being careful to implement each of its methods
2. attach a callback to `'action_scheduler_store_class'` to tell Action Scheduler your class is the one which should be used to manage storage, e.g.
```
function eg_define_custom_store( $existing_storage_class ) {
return 'My_Radical_Action_Scheduler_Store';
}
add_filter( 'action_scheduler_store_class', 'eg_define_custom_store', 10, 1 );
```
Take a look at the `classes/data-stores/ActionScheduler_DBStore.php` class for an example implementation of `ActionScheduler_Store`.
If you'd like to create a plugin to do this automatically and release it publicly to help others, [open a new issue to let us know](https://github.com/woocommerce/action-scheduler/issues/new), we'd love to help you with it.
### Can I use a different storage scheme just for logging?
Of course! Action Scheduler's logger is completely swappable, and always has been. You can also customise where logs are stored, and the storage mechanism.
To implement a custom logger:
1. extend the abstract `ActionScheduler_Logger` class, being careful to implement each of its methods
2. attach a callback to `'action_scheduler_logger_class'` to tell Action Scheduler your class is the one which should be used to manage logging, e.g.
```
function eg_define_custom_logger( $existing_storage_class ) {
return 'My_Radical_Action_Scheduler_Logger';
}
add_filter( 'action_scheduler_logger_class', 'eg_define_custom_logger', 10, 1 );
```
Take a look at the `classes/data-stores/ActionScheduler_DBLogger.php` class for an example implementation of `ActionScheduler_Logger`.
### I want to run Action Scheduler only on a dedicated application server in my cluster. Can I do that?
Wow, now you're really asking the tough questions. In theory, yes, this is possible. The `ActionScheduler_QueueRunner` class, which is responsible for running queues, is swappable via the `'action_scheduler_queue_runner_class'` filter.
Because of this, you can effectively customise queue running however you need. Whether that means tweaking minor things, like not using WP-Cron at all to initiate queues by overriding `ActionScheduler_QueueRunner::init()`, or completely changing how and where queues are run, by overriding `ActionScheduler_QueueRunner::run()`.
### Is Action Scheduler safe to use on my production site?
Yes, absolutely! Action Scheduler is actively used on tens of thousands of production sites already. Right now it's responsible for scheduling everything from emails to payments.
In fact, every month, Action Scheduler processes millions of payments as part of the [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/) extension.
It requires no setup, and won't override any WordPress APIs (unless you want it to).
### How does Action Scheduler work on WordPress Multisite?
Action Scheduler is designed to manage the scheduled actions on a single site. It has no special handling for running queues across multiple sites in a multisite network. That said, because its storage and Queue Runner are completely swappable, it would be possible to write multisite handling classes to use with it.
If you'd like to create a multisite plugin to do this and release it publicly to help others, [open a new issue to let us know](https://github.com/woocommerce/action-scheduler/issues/new), we'd love to help you with it.
### How can I change the Action Scheduler User-Agent to better identify its requests?
Action Scheduler has a filter available named `as_async_request_queue_runner_post_args` which can be used to filter the arguments that are being sent to the `wp_remote_post` call.
The User-Agent parameter is just one of them and can be adjusted as follows:
```
function eg_define_custom_user_agent( $args ) {
$versions = ActionScheduler_Versions::instance();
$args['user-agent'] = 'Action Scheduler/' . $versions->latest_version();
return $args;
}
add_filter( 'as_async_request_queue_runner_post_args', 'eg_define_custom_user_agent', 10, 1 );
```
### My site has past-due actions; what can I do?
Actions that are past-due have missed their scheduled date; because of [how WP Cron works](https://developer.wordpress.org/plugins/cron/), it is normal to have some past-due actions.
If there are several past-due actions more than one day old, there may be something wrong with your site. If you are using WooCommerce and need help determining the issue, please [contact us on our forum page](https://wordpress.org/support/plugin/woocommerce/).

BIN
libraries/action-scheduler/docs/favicon-16x16.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 589 B

BIN
libraries/action-scheduler/docs/favicon-32x32.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

BIN
libraries/action-scheduler/docs/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.7 KiB

1
libraries/action-scheduler/docs/google14ef723abb376cd3.html Normal file
View File

@@ -0,0 +1 @@
google-site-verification: google14ef723abb376cd3.html

66
libraries/action-scheduler/docs/index.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: Action Scheduler - Background Processing Job Queue for WordPress
---
## WordPress Job Queue with Background Processing
Action Scheduler is a library for triggering a WordPress hook to run at some time in the future (or as soon as possible, in the case of an async action). Each hook can be scheduled with unique data, to allow callbacks to perform operations on that data. The hook can also be scheduled to run on one or more occasions.
Think of it like an extension to `do_action()` which adds the ability to delay and repeat a hook.
It just so happens, this functionality also creates a robust job queue for background processing large queues of tasks in WordPress. With the addition of logging and an [administration interface](/admin/), it also provides traceability on your tasks processed in the background.
### Battle-Tested Background Processing
Every month, Action Scheduler processes millions of payments for [Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/), webhooks for [WooCommerce](https://wordpress.org/plugins/woocommerce/), as well as emails and other events for a range of other plugins.
It's been seen on live sites processing queues in excess of 50,000 jobs and doing resource intensive operations, like processing payments and creating orders, in 10 concurrent queues at a rate of over 10,000 actions / hour without negatively impacting normal site operations.
This is all possible on infrastructure and WordPress sites outside the control of the plugin author.
Action Scheduler is specifically designed for distribution in WordPress plugins (and themes) - no server access required. If your plugin needs background processing, especially of large sets of tasks, Action Scheduler can help.
### How it Works
Action Scheduler stores the hook name, arguments and scheduled date for an action that should be triggered at some time in the future.
The scheduler will attempt to run every minute by attaching itself as a callback to the `'action_scheduler_run_schedule'` hook, which is scheduled using WordPress's built-in [WP-Cron](http://codex.wordpress.org/Function_Reference/wp_cron) system. Once per minute on, it will also check on the `'shutdown'` hook of WP Admin requests whether there are pending actions, and if there are, it will initiate a queue via an async loopback request.
When triggered, Action Scheduler will check for scheduled actions that have a due date at or before this point in time i.e. actions scheduled to run now or at sometime in the past. Action scheduled to run asynchronously, i.e. not scheduled, have a zero date, meaning they will always be due no matter when the check occurs.
### Batch Processing Background Jobs
If there are actions to be processed, Action Scheduler will stake a unique claim for a batch of 25 actions and begin processing that batch. The PHP process spawned to run the batch will then continue processing batches of 25 actions until it uses 90% of available memory or has been processing for 30 seconds.
At that point, if there are additional actions to process, an asynchronous loopback request will be made to the site to continue processing actions in a new request.
This process and the loopback requests will continue until all actions are processed.
### Housekeeping
Before processing a batch, the scheduler will remove any existing claims on actions which have been sitting in a queue for more than five minutes (or more specifically, 10 times the allowed time limit, which defaults to 30 seconds).
Action Scheduler will also delete any actions which were completed or canceled more than a month ago.
If an action runs for more than 5 minutes, Action Scheduler will assume the action has timed out and will mark it as failed. However, if all callbacks attached to the action were to successfully complete sometime after that 5 minute timeout, its status would later be updated to completed.
### Traceable Background Processing
Did your background job run?
Never be left wondering with Action Scheduler's built-in record keeping.
All events for each action are logged in the `actionscheduler_logs` table and displayed in the [administration interface](/admin/).
The events logged by default include when an action:
* is created
* starts (including details of how it was run, e.g. via [WP CLI](/wp-cli/) or WP Cron)
* completes
* fails
If it fails with an error that can be recorded, that error will be recorded in the log and visible in administration interface, making it possible to trace what went wrong at some point in the past on a site you didn't have access to in the past.
## Credits
Action Scheduler is developed and maintained by folks at [Automattic](http://automattic.com/) with significant early development completed by [Flightless](https://flightless.us/).
Collaboration is cool. We'd love to work with you to improve Action Scheduler. [Pull Requests](https://github.com/woocommerce/action-scheduler/pulls) welcome.

BIN
libraries/action-scheduler/docs/mstile-150x150.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.1 KiB

149
libraries/action-scheduler/docs/perf.md Normal file
View File

@@ -0,0 +1,149 @@
---
title: WordPress Background Processing at Scale - Action Scheduler Job Queue
description: Learn how to do WordPress background processing at scale by tuning the Action Scheduler job queue's default WP Cron runner.
---
# Background Processing at Scale
Action Scheduler's default processing is designed to work reliably across all different hosting environments. To achieve that, the default processing thresholds are more conservative than many servers could support.
Specifically, Action Scheduler will only process actions in a request until:
* 90% of available memory is used
* processing another 3 actions would exceed 30 seconds of total request time, based on the average processing time for the current batch
* in a single concurrent queue
While Action Scheduler will initiate an asynchronous loopback request to process additional actions, on sites with very large queues, this can result in slow processing times.
While using [WP CLI to process queues](/wp-cli/) is the best approach to increasing processing speed, on occasion, that is not a viable option. In these cases, it's also possible to increase the processing thresholds in Action Scheduler to increase the rate at which actions are processed by the default queue runner.
## Increasing Time Limit
By default, Action Scheduler will only process actions for a maximum of 30 seconds in each request. This time limit minimizes the risk of a script timeout on unknown hosting environments, some of which enforce 30-second timeouts.
If you know your host supports longer than this time limit for web requests, you can increase this time limit. This allows more actions to be processed in each request and reduces the lag between processing each queue, greatly speeding up the processing rate of scheduled actions.
For example, the following snippet will increase the time limit to 2 minutes (120 seconds):
```php
function eg_increase_time_limit( $time_limit ) {
return 120;
}
add_filter( 'action_scheduler_queue_runner_time_limit', 'eg_increase_time_limit' );
```
Some of the known host time limits are:
* 60 seconds on WP Engine
* 120 seconds on Pantheon
* 120 seconds on SiteGround
## Increasing Batch Size
By default, Action Scheduler will claim a batch of 25 actions. This small batch size is because the default time limit is only 30 seconds; however, if you know your actions are processing very quickly, e.g. taking milliseconds not seconds, or that you have more than 30 seconds available to process each batch, increasing the batch size can slightly improve performance.
This is because claiming a batch has some overhead, so the less often a batch needs to be claimed, the faster actions can be processed.
For example, to increase the batch size to 100, we can use the following function:
```php
function eg_increase_action_scheduler_batch_size( $batch_size ) {
return 100;
}
add_filter( 'action_scheduler_queue_runner_batch_size', 'eg_increase_action_scheduler_batch_size' );
```
## Increasing Concurrent Batches
By default, Action Scheduler will run only one concurrent batch of actions. This is to prevent consuming a lot of available connections or processes on your web server.
However, your server may allow a large number of connections, for example, because it has a high value for Apache's `MaxClients` setting or PHP-FPM's `pm.max_children` setting.
If this is the case, you can use the `'action_scheduler_queue_runner_concurrent_batches'` filter to increase the number of concurrent batches allowed, and therefore speed up large numbers of actions scheduled to be processed simultaneously.
For example, to increase the allowed number of concurrent queues to 10, we can use the following code:
```php
function eg_increase_action_scheduler_concurrent_batches( $concurrent_batches ) {
return 10;
}
add_filter( 'action_scheduler_queue_runner_concurrent_batches', 'eg_increase_action_scheduler_concurrent_batches' );
```
> WARNING: because the async queue runner introduced in Action Scheduler 3.0 will continue asynchronous loopback requests to process actions, increasing the number of concurrent batches can substantially increase server load and take down a site. [WP CLI](/wp-cli/) is a better method to achieve higher throughput.
## Increasing Initialisation Rate of Runners
By default, Action Scheduler initiates at most one queue runner every time the `'action_scheduler_run_queue'` action is triggered by WP Cron.
Because this action is only triggered at most once every minute, then there will rarely be more than one queue processing actions even if the concurrent runners are increased.
To handle larger queues on more powerful servers, it's possible to initiate additional queue runners whenever the `'action_scheduler_run_queue'` action is run.
That can be done by initiating additional secure requests to our server via loopback requests.
The code below demonstrates how to create 5 loopback requests each time a queue begins:
```php
/**
* Trigger 5 additional loopback requests with unique URL params.
*/
function eg_request_additional_runners() {
// allow self-signed SSL certificates
add_filter( 'https_local_ssl_verify', '__return_false', 100 );
for ( $i = 0; $i < 5; $i++ ) {
$response = wp_remote_post( admin_url( 'admin-ajax.php' ), array(
'method' => 'POST',
'timeout' => 45,
'redirection' => 5,
'httpversion' => '1.0',
'blocking' => false,
'headers' => array(),
'body' => array(
'action' => 'eg_create_additional_runners',
'instance' => $i,
'eg_nonce' => wp_create_nonce( 'eg_additional_runner_' . $i ),
),
'cookies' => array(),
) );
}
}
add_action( 'action_scheduler_run_queue', 'eg_request_additional_runners', 0 );
/**
* Handle requests initiated by eg_request_additional_runners() and start a queue runner if the request is valid.
*/
function eg_create_additional_runners() {
if ( isset( $_POST['eg_nonce'] ) && isset( $_POST['instance'] ) && wp_verify_nonce( $_POST['eg_nonce'], 'eg_additional_runner_' . $_POST['instance'] ) ) {
ActionScheduler_QueueRunner::instance()->run();
}
wp_die();
}
add_action( 'wp_ajax_nopriv_eg_create_additional_runners', 'eg_create_additional_runners', 0 );
```
> WARNING: because of the processing rate of scheduled actions, this kind of increase can very easily take down a site. Use only on high-powered servers and be sure to test before attempting to use it in production.
## Cleaning Failed Actions
By default, Action Scheduler does not automatically delete old failed actions. There are two optional methods of removing these actions:
- Include the failed status in the list of statuses to purge:
```php
add_filter( 'action_scheduler_default_cleaner_statuses', function( $statuses ) {
$statuses[] = ActionScheduler_Store::STATUS_FAILED;
return $statuses;
} );
```
- Use [WP CLI](/wp-cli/):
```shell
// Example
wp action-scheduler clean --status=failed --batch-size=50 --before='90 days ago' --pause=2
```
## High Volume Plugin
It's not necessary to add all of this code yourself, there is a handy plugin to get access to each of these increases - the [Action Scheduler - High Volume](https://github.com/woocommerce/action-scheduler-high-volume) plugin.

40
libraries/action-scheduler/docs/safari-pinned-tab.svg Normal file
View File

@@ -0,0 +1,40 @@
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
width="312.000000pt" height="312.000000pt" viewBox="0 0 312.000000 312.000000"
preserveAspectRatio="xMidYMid meet">
<metadata>
Created by potrace 1.11, written by Peter Selinger 2001-2013
</metadata>
<g transform="translate(0.000000,312.000000) scale(0.100000,-0.100000)"
fill="#000000" stroke="none">
<path d="M1837 2924 c-1 -1 -54 -5 -117 -8 -63 -4 -128 -9 -145 -11 -16 -2
-46 -6 -65 -9 -19 -3 -57 -8 -85 -11 -27 -3 -70 -10 -95 -16 -25 -5 -58 -11
-75 -13 -98 -13 -360 -73 -565 -130 -236 -65 -584 -172 -609 -187 -105 -67 24
-294 221 -387 77 -37 152 -61 206 -65 16 -1 22 -8 22 -23 0 -34 35 -107 70
-147 62 -71 161 -119 265 -130 34 -4 40 -8 46 -33 25 -122 151 -205 301 -198
122 5 254 44 270 80 6 13 8 27 5 30 -3 4 -41 1 -84 -5 -119 -18 -155 -19 -217
-9 -74 11 -123 47 -132 94 -7 40 -4 46 28 49 94 12 238 52 260 72 35 32 23 46
-34 38 -29 -4 -62 -9 -73 -11 -45 -10 -255 -11 -320 -2 -81 11 -154 40 -185
73 -24 26 -52 97 -42 106 4 4 45 9 92 12 93 7 90 6 269 43 69 14 134 30 145
36 29 15 56 39 56 50 0 10 -74 3 -144 -12 -22 -5 -144 -8 -270 -6 -251 3 -327
15 -443 71 -47 23 -133 97 -133 115 0 6 150 49 225 64 11 3 83 20 160 39 77
19 154 38 170 41 17 4 39 8 50 10 11 3 56 12 100 21 98 21 104 22 146 29 19 3
43 7 54 10 28 5 94 16 130 20 17 3 44 7 60 10 17 2 50 7 75 11 41 5 87 11 150
20 111 16 452 23 509 11 14 -3 47 -8 75 -11 28 -3 78 -13 111 -21 365 -92 513
-289 509 -679 -1 -102 -35 -265 -56 -265 -5 0 -7 -4 -4 -9 3 -4 -12 -41 -33
-81 -144 -277 -468 -551 -794 -671 -107 -39 -317 -88 -317 -73 0 2 50 118 111
257 61 138 131 299 156 357 25 58 49 114 54 125 5 11 52 119 104 240 90 208
94 221 84 255 -19 58 -67 147 -99 183 -33 38 -86 65 -99 51 -5 -5 -23 -43 -41
-84 -50 -116 -179 -408 -211 -478 -16 -35 -29 -65 -29 -67 0 -2 -18 -43 -40
-90 -22 -47 -40 -88 -40 -90 0 -4 -92 -211 -156 -353 -13 -29 -24 -55 -24 -57
0 -2 -15 -37 -34 -77 -18 -40 -46 -102 -61 -138 -16 -36 -45 -102 -67 -148
-21 -46 -38 -85 -38 -87 0 -2 -34 -81 -76 -175 -55 -124 -74 -178 -70 -196 16
-62 116 -134 207 -148 36 -5 37 -5 63 53 14 32 51 112 82 177 31 66 74 160 96
209 22 50 43 93 47 98 7 7 19 10 82 21 19 3 44 8 55 10 12 2 38 7 57 10 480
76 883 299 1117 618 100 135 202 363 224 498 1 8 5 35 9 60 16 95 13 216 -7
340 -10 59 -60 190 -97 252 -45 76 -151 190 -219 235 -127 85 -324 159 -475
179 -27 3 -53 8 -56 9 -12 8 -344 25 -352 19z"/>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.5 KiB

19
libraries/action-scheduler/docs/site.webmanifest Normal file
View File

@@ -0,0 +1,19 @@
{
"name": "",
"short_name": "",
"icons": [
{
"src": "/android-chrome-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/android-chrome-256x256.png",
"sizes": "256x256",
"type": "image/png"
}
],
"theme_color": "#ffffff",
"background_color": "#ffffff",
"display": "standalone"
}

211
libraries/action-scheduler/docs/usage.md Normal file
View File

@@ -0,0 +1,211 @@
---
description: Learn how to use the Action Scheduler background processing job queue for WordPress in your WordPress plugin.
---
# Usage
Using Action Scheduler requires:
1. installing the library
1. scheduling an action
## Installation
There are two ways to install Action Scheduler:
1. regular WordPress plugin; or
1. a library within your plugin's codebase.
Note that [Action Scheduler follows an L-2 dependency version policy](https://developer.woocommerce.com/2023/10/24/action-scheduler-to-adopt-l-2-dependency-version-policy/). That is, the library requires at least the "latest minus two" version of WordPress and the PHP minimum version requirement of that WordPress version.
### Usage as a Plugin
Action Scheduler includes the necessary file headers to be used as a standard WordPress plugin.
To install it as a plugin:
1. Download the .zip archive of the latest [stable release](https://github.com/woocommerce/action-scheduler/releases)
1. Go to the **Plugins > Add New > Upload** administration screen on your WordPress site
1. Select the archive file you just downloaded
1. Click **Install Now**
1. Click **Activate**
Or clone the Git repository into your site's `wp-content/plugins` folder.
Using Action Scheduler as a plugin can be handy for developing against newer versions, rather than having to update the subtree in your codebase. **When installed as a plugin, Action Scheduler does not provide any user interfaces for scheduling actions**. The only way to interact with Action Scheduler is via code.
### Usage as a Library
To use Action Scheduler as a library:
1. include the Action Scheduler codebase
1. load the library by including the `action-scheduler.php` file
Using a [subtree in your plugin, theme or site's Git repository](https://www.atlassian.com/blog/git/alternatives-to-git-submodule-git-subtree) to include Action Scheduler is the recommended method. Composer can also be used.
To include Action Scheduler as a git subtree:
#### Step 1. Add the Repository as a Remote
```
git remote add -f subtree-action-scheduler https://github.com/woocommerce/action-scheduler.git
```
Adding the subtree as a remote allows us to refer to it in short from via the name `subtree-action-scheduler`, instead of the full GitHub URL.
#### Step 2. Add the Repo as a Subtree
```
git subtree add --prefix libraries/action-scheduler subtree-action-scheduler trunk --squash
```
This will add the `trunk` branch of Action Scheduler to your repository in the folder `libraries/action-scheduler`.
You can change the `--prefix` to change where the code is included. Or change the `trunk` branch to a tag, like `2.1.0` to include only a stable version.
#### Step 3. Update the Subtree
To update Action Scheduler to a new version, use the commands:
```
git fetch subtree-action-scheduler trunk
git subtree pull --prefix libraries/action-scheduler subtree-action-scheduler trunk --squash
```
### Loading Action Scheduler
Regardless of how it is installed, to load Action Scheduler, you only need to include the `action-scheduler.php` file, e.g.
```php
<?php
require_once( plugin_dir_path( __FILE__ ) . '/libraries/action-scheduler/action-scheduler.php' );
```
There is no need to call any functions or do else to initialize Action Scheduler.
When the `action-scheduler.php` file is included, Action Scheduler will register the version in that file and then load the most recent version of itself on the site. It will also load the most recent version of [all API functions](https://actionscheduler.org/api/).
### Load Order
Action Scheduler will register its version on `'plugins_loaded'` with priority `0` - after all other plugin codebases has been loaded. Therefore **the `action-scheduler.php` file must be included before `'plugins_loaded'` priority `0`**.
It is recommended to load it _when the file including it is included_. However, if you need to load it on a hook, then the hook must occur before `'plugins_loaded'`, or you can use `'plugins_loaded'` with negative priority, like `-10`.
Action Scheduler will later initialize itself on `'init'` with priority `1`. Action Scheduler APIs should not be used until after `'init'` with priority `1`. As described in [API Function Availability](/api/#api-function-availability), you can also use the `'action_scheduler_init'` action hook for this purpose.
### Usage in Themes
When using Action Scheduler in themes, it's important to note that if Action Scheduler has been registered by a plugin, then the latest version registered by a plugin will be used, rather than the version included in the theme. This is because of the version dependency handling code using `'plugins_loaded'` since version 1.0.
## Scheduling Recurring Actions on Activation and Ensuring They Remain Scheduled
When developing a plugin or extension that relies on recurring actions, it is essential to schedule those actions when the plugin is first activated or updated.
### Best Practice: Schedule on Activation
Plugins should always schedule any important recurring actions during activation or upgrade routines. This ensures the action is registered as soon as the plugin is enabled.
**Example: Scheduling on Activation**
```php
/**
* Schedule recurring action on plugin activation.
*/
function my_plugin_activate() {
if ( ! as_has_scheduled_action( 'my_plugin_recurring_action' ) ) {
as_schedule_recurring_action(
time(),
HOUR_IN_SECONDS,
'my_plugin_recurring_action'
);
}
}
register_activation_hook( __FILE__, 'my_plugin_activate' );
```
### Ensuring Recurring Actions Remain Scheduled
After initial scheduling, there may be rare cases where a recurring action is lost (e.g., due to a database failure or repeated action failures). The `action_scheduler_ensure_recurring_actions` hook provides a reliable opportunity to check and reschedule the action if necessary.
**Example: Using the Ensure Hook**
```php
/**
* Ensure recurring action remains scheduled.
*/
add_action( 'action_scheduler_ensure_recurring_actions', function() {
if ( ! as_has_scheduled_action( 'my_plugin_recurring_action' ) ) {
as_schedule_recurring_action(
time(),
HOUR_IN_SECONDS,
'my_plugin_recurring_action'
);
}
});
```
### Compatibility Notes:
When using Action Scheduler, be aware of version-specific features and functions. If your plugin may run with older versions of Action Scheduler because it is relying on ActionScheduler to be included separately from your plugin where you cannot be sure of the version being loaded, use the following guidance to ensure compatibility.
**New in 3.9.3: `action_scheduler_ensure_recurring_actions` Hook and `as_supports()`**
* The `action_scheduler_ensure_recurring_actions` hook and the `as_supports()` API method were introduced in Action Scheduler 3.9.3.
* To use this hook, first check that the current Action Scheduler version supports it.
**Example: Ensuring a Recurring Action Remains Scheduled in a Backward Compatible Way**
```php
/**
* Schedules the plugin's recurring action if it is not already scheduled.
*/
function my_plugin_schedule_my_recurring_action() {
if ( ! as_has_scheduled_action( 'my_plugin_recurring_action' ) ) {
as_schedule_recurring_action(
time(),
HOUR_IN_SECONDS,
'my_plugin_recurring_action'
);
}
}
/**
* Add the hooks needed for my_plugin_schedule_my_recurring_action() so it can make sure our hook stays scheduled.
*/
add_action( 'init', function () {
if ( function_exists( 'as_supports' ) && as_supports( 'ensure_recurring_actions_hook' ) ) {
// Preferred: runs periodically in the background.
add_action( 'action_scheduler_ensure_recurring_actions', 'my_plugin_schedule_my_recurring_action' );
} elseif ( is_admin() ) {
// Fallback: runs on every admin request.
my_plugin_schedule_my_recurring_action();
}
} );
```
**Note on `as_has_scheduled_action()` (Added in 3.3.0)**
* The `as_has_scheduled_action()` function was introduced in Action Scheduler 3.3.0.
* If you need to support even older versions, check if the `as_has_scheduled_action` function exists and fallback to `as_next_scheduled_action()` instead.
For more details on all available API functions, their parameters, and when they were added, refer to the [API Reference](https://actionscheduler.org/api/).
### Passing arguments
It is possible to pass arguments to your callbacks. When you initially supply the arguments via a call to `as_schedule_single_action()` or one of its sister functions, they should be in an array. However, your callback function will receive each array item as an individual parameter. Here's an example:
```php
// You must specify the number of arguments to be accepted (in this case, 2).
add_action( 'purchase_notification', 'send_purchase_notification', 10, 2 );
// When scheduling the action, provide the arguments as an array.
as_schedule_single_action( time(), 'purchase_notification', array(
'bob@foo.bar',
'Learning Action Scheduler (e-book)',
) );
// Your callback should accept the appropriate number of parameters (again, in this case, 2).
function send_purchase_notification( $customer_email, $purchased_item ) {
wp_mail(
$customer_email,
'Thank you!',
"You purchased $purchased_item successfully."
);
}
```
The above is a pretty simple illustration, and you would of course need to make changes if you wish to do anything more complex, such as accept a variable number of arguments. However, it hopefully illustrates the basic principles involved.

68
libraries/action-scheduler/docs/version3-0.md Normal file
View File

@@ -0,0 +1,68 @@
## Version 3.0 FAQ
### Do we need to wait for this to be bundled with WooCommerce?
No. Action Scheduler can be run as a standalone plugin. Action Scheduler 3.X is also part of WooCommerce 4.0 and WooCommerce Subscriptions 3.0, so when updating WooCommerce or WooCommerce Subscriptions, Action Scheduler will also be updated.
### Can we safely switch to action scheduler version 3.0 and ditch the custom tables plugin?
Yes! The Action Scheduler Custom Tables plugin code is now part of Action Scheduler itself (with a few improvements). We recommend disabling the Custom Tables plugin immediately after activating Action Scheduler 3.0, or a plugin containing Action Scheduler 3.0, like WooCommerce Subscriptions 3.0 and newer.
### How do we migrate from our own custom data store?
By default, Action Scheduler will only initiate a migration from the internal `WPPostStore` data store. To enable migration from any custom datastore add the following filter `add_filter( 'action_scheduler_migrate_data_store', '__return_true' );`.
### I'm currently on PHP <5.5. When I update PHP will the migration start automatically?
Yes! The migration is initiated as soon as all dependencies are met.
### I would like to update a plugin for testing that includes Action Scheduler 3.0 but would like to postpone the migration until that testing is complete. Is that possible?
Yes, while we recommend migrating to custom tables as soon as possible for performance reasons, you can use `add_filter( 'action_scheduler_migration_dependencies_met', '__return_false' );` to prevent the migration from initiating.
### I updated to Action Scheduler 3.0+, the migration is running, and I'm seeing a lot of `admin-ajax.php?action=as_async_request_queue` requests. Is it possible to reduce this load?
You can increase the delay (in seconds) between these requests with
```
add_filter( 'action_scheduler_async_request_sleep_seconds', function( $sleep ) {
return 10;
} );
```
The default value for this filter is `1` in versions 3.0.X and `5` in versions 3.1.X.
Alternatively, the async queue runner can be disabled while your migration is in process with `add_filter( 'action_scheduler_allow_async_request_runner', '__return_false' );`.
Once the migration is complete, these filters should be removed.
### Is it safe to use Action Scheduler function in the WordPress `shutdown` hook.
No, you should avoid calls to Action Scheduler functions in the `shutdown` hook because the `shutdown` hook is still triggered after a fatal error. If this occurs while WordPress is loading, Action Scheduler is in an unknown state.
### Is there a strong likelihood of migration issues with any of the above?
There is always the possibilities of issues, but it is not a strong likelihood. We tested migrating from Action Scheduler 2.n with the custom data stores (including Action Scheduler Custom Tables plugin) active to Action Scheduler 3.0 on a number of test sites.
As with all major, and minor, upgrades, we still testing the update on a staging site before updating the live site. We also recommending taking a backup before updating the live site.
If you wish to undertake more comprehensive testing on a development or staging site before updating, or want to closely monitor the update on a live site, follow these steps:
#### Stage 1: Prepare your site:
1. Take a backup of your database (AS 3.0 migrates data to custom tables, this can not be undone, you’ll need to restore a backup to downgrade).
1. Go to Tools > Action Scheduler
1. Take a screenshot of the action status counts at the top of the page. Example screenshot: https://cld.wthms.co/kwIqv7
#### Stage 2: Install & Activate Action Scheduler 3.0+ as a plugin
1. The migration will start almost immediately
1. Keep an eye on your error log
1. Report any notices, errors or other issues on GitHub
#### Stage 3: Verify Migration
1. Go to Tools > Action Scheduler
1. Take a screenshot of the action status counts at the top of the page.
1. Verify the counts match the status counts taken in Stage 1 (the Completed counts could be higher because actions will have been completed to run the migration).

100
libraries/action-scheduler/docs/wp-cli.md Normal file
View File

@@ -0,0 +1,100 @@
---
description: Learn how to do WordPress background processing at scale with WP CLI and the Action Scheduler job queue.
---
# WP CLI
Action Scheduler has custom [WP CLI](http://wp-cli.org) commands available for processing actions.
For large sites, WP CLI is a much better choice for running queues of actions than the default WP Cron runner. These are some common cases where WP CLI is a better option:
* long-running tasks - Tasks that take a significant amount of time to run
* large queues - A large number of tasks will naturally take a longer time
* other plugins with extensive WP Cron usage - WP Cron's limited resources are spread across more tasks
With a regular web request, you may have to deal with script timeouts enforced by hosts, or other restraints that make it more challenging to run Action Scheduler tasks. Utilizing WP CLI to run commands directly on the server give you more freedom. This means that you typically don't have the same constraints of a normal web request.
If you choose to utilize WP CLI exclusively, you can disable the normal WP CLI queue runner by installing the [Action Scheduler - Disable Default Queue Runner](https://github.com/woocommerce/action-scheduler-disable-default-runner) plugin. Note that if you do this, you **must** run Action Scheduler via WP CLI or another method, otherwise no scheduled actions will be processed.
## Commands
These are the commands available to use with Action Scheduler:
* `action-scheduler clean`
Options:
* `--batch-size` - This is the number of actions per status to clean in a single batch. Default is `20`.
* `--batches` - This is the number of batches to process. Default 0 means that batches will continue to process until there are no more actions to delete.
* `--status` - Process only actions with specific status or statuses. Default is `canceled` and `complete`. Define multiple statuses as a comma separated string (without spaces), e.g. `--status=complete,failed,canceled`
* `--before` - Process only actions with scheduled date older than this. Defaults to 31 days. e.g `--before='7 days ago'`, `--before='02-Feb-2020 20:20:20'`
* `--pause` - The number of seconds to pause between batches. Default no pause.
* `action-scheduler migrate`
**Note**: This command is only available while the migration to custom tables is in progress.
* `action-scheduler run`
Options:
* `--batch-size` - This is the number of actions to run in a single batch. The default is `100`.
* `--batches` - This is the number of batches to run. Using 0 means that batches will continue running until there are no more actions to run.
* `--hooks` - Process only actions with specific hook or hooks, like `'woocommerce_scheduled_subscription_payment'`. By default, actions with any hook will be processed. Define multiple hooks as a comma separated string (without spaces), e.g. `--hooks=woocommerce_scheduled_subscription_trial_end,woocommerce_scheduled_subscription_payment,woocommerce_scheduled_subscription_expiration`
* `--group` - Process only actions in a specific group, like `'woocommerce-memberships'`. By default, actions in any group (or no group) will be processed.
* `--exclude-groups` - Ignore actions from the specified group or groups (to specify multiple groups, supply a comma-separated list of slugs). This option is ignored if `--group` is also specified.
* `--force` - By default, Action Scheduler limits the number of concurrent batches that can be run at once to ensure the server does not get overwhelmed. Using the `--force` flag overrides this behavior to force the WP CLI queue to run.
* `action-scheduler action cancel`
* `action-scheduler action create`
* `action-scheduler action delete`
* `action-scheduler action generate`
* `action-scheduler action get`
* `action-scheduler action list`
* `action-scheduler action next`
* `action-scheduler action run`
* `action-scheduler datastore`
* `action-scheduler runner`
* `action-scheduler status`
* `action-scheduler version`
The best way to get a full list of commands and their available options is to use WP CLI itself. This can be done by running `wp action-scheduler` to list all Action Scheduler commands, or by including the `--help` flag with any of the individual commands. This will provide all relevant parameters and flags for the command.
## Cautionary Note on Action Dependencies when using `--group` or `--hooks` Options
The `--group` and `--hooks` options should be used with caution if you have an implicit dependency between scheduled actions based on their schedule.
For example, consider two scheduled actions for the same subscription:
* `scheduled_payment` scheduled for `2015-11-13 00:00:00` and
* `scheduled_expiration` scheduled for `2015-11-13 00:01:00`.
Under normal conditions, Action Scheduler will ensure the `scheduled_payment` action is run before the `scheduled_expiration` action. Because that's how they are scheduled.
However, when using the `--hooks` option, the `scheduled_payment` and `scheduled_expiration` actions will be processed in separate queues. As a result, this dependency is not guaranteed.
For example, consider a site with both:
* 100,000 `scheduled_payment` actions, scheduled for `2015-11-13 00:00:00`
* 100 `scheduled_expiration` actions, scheduled for `2015-11-13 00:01:00`
If two queue runners are running alongside each other with each runner dedicated to just one of these hooks, the queue runner handling expiration hooks will complete the processing of the expiration hooks more quickly than the queue runner handling all the payment actions.
**Because of this, the `--group` and `--hooks` options should be used with caution to avoid processing actions with an implicit dependency based on their schedule in separate queues.**
## Improving Performance with `--group` or `--hooks`
Being able to run queues for specific hooks or groups of actions is valuable at scale. Why? Because it means you can restrict the concurrency for similar actions.
For example, let's say you have 300,000 actions queued up comprised of:
* 100,000 renewals payments
* 100,000 email notifications
* 100,000 membership status updates
Action Scheduler's default WP Cron queue runner will process them all together. e.g. when it claims a batch of actions, some may be emails, some membership updates and some renewals.
When you add concurrency to that, you can end up with issues. For example, if you have 3 queues running, they may all be attempting to process similar actions at the same time, which can lead to querying the same database tables with similar queries. Depending on the code/queries running, this can lead to database locks or other issues.
If you can batch based on each action's group, then you can improve performance by processing like actions consecutively, but still processing the full set of actions concurrently.
For example, if one queue is created to process emails, another to process membership updates, and another to process renewal payments, then the same queries won't be run at the same time, and 3 separate queues will be able to run more efficiently.
The WP CLI runner can achieve this using the `--group` option to create queue runners that focus on a specific group and, optionally, the `--exclude-groups` option to create one or more 'catch-all' queue runners that ignore those groups.