Use WP Queue in WordPress to Run Time-Consuming Tasks Through a Job Queue

When developing WordPress applications, we sometimes need to perform expensive tasks, such as sending email to a thousand subscribers. If all of that work runs in a single PHP request, it may hit execution time limits and fail partway through. That is the kind of situation where a job queue becomes valuable.

WordPress does not include a built-in general-purpose queue system, so you either need to build one or use a library. This article focuses on one such library for WordPress: WP Queue.

How WP Queue works and how to install it

Like many queue systems, WP Queue stores jobs in the database. Once the queue exists, your code only needs to push jobs into it and let WP Queue run them in the order you configure. The queue still needs a scheduler to dispatch those jobs, and in this setup that scheduler is based on the WordPress Cron system.

Installing the library is simple. Run the following command in the root of your theme or plugin project:

composer require a5hleyrich/wp-queue

Because WP Queue is a PHP library rather than a standalone plugin, you also need to install the queue tables in the WordPress database before using it. The SQL looks like this. If you execute it directly in phpMyAdmin, replace {$wpdb->prefix} with your real table prefix, which is often wp_.

CREATE TABLE {$wpdb->prefix}queue_jobs (
id bigint(20) NOT NULL AUTO_INCREMENT,
job longtext NOT NULL,
attempts tinyint(3) NOT NULL DEFAULT 0,
reserved_at datetime DEFAULT NULL,
available_at datetime NOT NULL,
created_at datetime NOT NULL,
PRIMARY KEY (id)
);

If you are using WP Queue inside a theme or plugin, you can also call the helper function wp_queue_install_tables() during initialization instead of running the SQL manually.

Use WP Queue to implement queued jobs

Before adding jobs to the queue, create a job class. The class should extend WP_QueueJob and usually only needs a handler method. Any data needed by the job can be passed through the constructor and stored as public properties.

<?php
use WP_QueueJob;

class Subscribe_User_Job extends Job {
    /**
     * @var int
     */
    public $user_id;

    /**
     * Subscribe_User_Job constructor.
     *
     * @param int $user_id
     */
    public function __construct( $user_id ) {
        $this->user_id = $user_id;
    }

    public function handle() {
        // Run the expensive job logic here.
    }
}

Dispatch jobs from the queue

Once the job class exists, you can push jobs into the queue like this:

wp_queue()->push( new Subscribe_User_Job( 12345 ) );

You can also delay a queued job by passing an extra delay value. For example, the following job will be delayed by one hour:

wp_queue()->push( new Subscribe_User_Job( 12345 ), 3600 );

Customize how queued jobs are run

The queue still needs a dispatcher to process jobs. The following call schedules queue execution using WordPress’s cron system:

wp_queue()->cron();

You can also control how many times failed jobs should be retried:

wp_queue()->cron( 3 );

With WP Queue in place, large repetitive tasks can be processed much more safely and reliably in WordPress themes or plugins. If you want a real-world example, it is worth looking at the code of the WP Image Processing Queue library to see how it uses WP Queue in practice.