Creating background processes in WordPress

If a PHP script runs, the page loads typically as long as the script needs to finish (or throws an error). That is fine for many cases, but if the script needs to process complex and/or many tasks, that take a few minutes or even hours, it would be nice to put that tasks in the background. This post shows you how to create background processes in WordPress.

Advantages of running background processes

Using background processes has various advantages, for example:

• Better user experience, because no tab needs to stay open while a slow task is running.
• Tasks can be split into smaller parts to prevent timeouts.

Background processes in WordPress with »Action Scheduler«

Action Scheduler is a background process solution that can be installed as a plugin or used as a library as part of a plugin. Action Scheduler uses the WordPress hook system and makes it possible to run an action hook:

• once as soon as possible,
• once on a defined time,
• recurring in a specified seconds interval or
• recurring in a cron interval.

Additionally, it brings an admin interface under Tools › Scheduled Actions that lists the planned and processed actions with its parameters and, if there are any, errors.

Installation

The tool can be installed in different ways, at first you need to decide if you want to use it as a WordPress plugin or as part of another plugin. I show you the usage as part of another plugin and install Action Scheduler via Composer:

composer require woocommerce/action-scheduler
Code language: Bash (bash)

The normal way of loading composer packages would be to include the Composer autoloader, but Action Scheduler has its own loading mechanism, so we need to include the action-scheduler.php file manually:

// Load action scheduler.
$action_scheduler = require_once dirname( __FILE__ ) . '/vendor/woocommerce/action-scheduler/action-scheduler.php';
Code language: PHP (php)

That is is, now we can create our first background process.

Create a background process

I will show the usage of Action Scheduler with an action that is processed only once and as fast as possible. All other options and the required parameters are listed on the API page of Action Scheduler.

To run an action once and as soon as possible, we use the function as_enqueue_async_action() that gets the action hook name to run as the first and only required parameter.

The following code would schedule the one_time_action_asap hook for a one-time run at the next possible time, if the GET parameter one_time_action is present. And because we added the function one_time_function_asap() to the action hook, that function will run in the background.

add_action( 'init', function() {
	add_action( 'one_time_action_asap', 'one_time_function_asap' );

	if ( isset( $_GET['one_time_action'] ) ) {
		as_enqueue_async_action( 'one_time_action_asap' );
	}
} );

function one_time_function_asap() {
	// Some time-consuming task.
}
Code language: PHP (php)

The second parameter of as_enqueue_async_action() can be used to pass an array of parameters to the function that is run by the hook. So, let’s imagine a user enters a value into a text field that is added as one_time_action parameter in the URL and should be passed to the background process:

add_action( 'init', function() {
	add_action( 'one_time_action_asap', 'one_time_function_asap' );

	if ( isset( $_GET['one_time_action'] ) ) {
		as_enqueue_async_action(
			'one_time_action_asap',
			[ $_GET['one_time_action'] ]
		);
	}
} );

function one_time_function_asap( $value ) {
	// Some time-consuming task.
	error_log( $value );
}
Code language: PHP (php)

The example code would write the value of one_time_action to the error log if it is enabled. If you pass an array with multiple values, the function gets multiple parameters. Those params are shown in the admin interface of Action Scheduler, which is nice if you need to debug issues with background processes.

And with that, we have our first (slightly silly, but…) action that runs in the background.

Conclusion

Action Scheduler is quickly ready to use and not much complicated to use because it can be used via known WordPress mechanisms.

Compared to WP Background Processing, which was the subject of the first version of this post, I like that Action Scheduler is easier to integrate and, at least for the time of development, that it comes with a user interface where you see the actions with its parameters and can if needed, cancel an action before it is started.

The original version of this post was published on April 14, 2018.