Download the PHP package moderntribe/square1-queues without Composer

Queues

The Queue library provides a utility for background processing of potentially slow, time consuming, or network-dependent tasks.

Configure queues with the MySQL Backend

Include Queue_Definer, Queue_Subscriber and the Mysql_Backend_Definer, Mysql_Backend_Subscriber in your Core.php, ensuring to add the MySQL providers items after the Queue providers.

Run the following to create the queues database table:

Getting the Queue Object

While it is possible (and in rare cases appropriate) to have multiple queues, most often a project will use a single default queue. Using the DI container, your class constructor should receive a \Tribe\Libs\Queues\Contracts\Queue. Autowiring should take care of the rest to give you an instance of the appropriate queue class with the configured backend.

Creating a task handler

If you are putting things into queue, it is very likely you will need to create a custom task handler. To create a Task class, implement Tribe\Project\Queues\Contracts\Task.

The handle( array $args ) method is required and must return true on success (the task is marked as complete and removed from the queue), false on failure (the task is added back into the queue to try again).

The task handler instance is run in isolation, but still supports auto wiring and dependency injection.

Example Task:

Adding a task to the queue

You dispatch tasks to the queue to indicate which class handles the task, and the arguments array to pass to the handle() method. For example, ff your tasks requires a Post ID to complete its process, you can populate the $args variable during dispatch and the static value will be saved in the Queue for when the task is processed.

Processing a queue

Using WP-CLI wp s1 queues process <queue-name>. This will process all items in the queue.

Using the system crontab, set up a job to run every 5 minutes to kick off the queue process. This task will run for approximately five minutes, polling the queue every second for something to do (and sitting idle if there is nothing). After the five-minute time limit, the process will gracefully terminate.

You can customize the timelimit with the --timelimit=<time in seconds> option, e.g. to change from the default 300 to 500 seconds:

Along with the cron to process the queue, also set a cron to clean up old data from the queue. wp s1 queues cleanup <queue-name>

In the event that WP CLI is not available (such as on older WP Engine stacks), then the queues can be processed on WP Cron. Cron support is disabled by default, but is enabled by setting WP_DISABLE_CRON to false. This is not the preferred way of using Queues, but can be used when system level CLI access is not available.

Cron jobs

The queue should run on a cronjob for as long as the timelimit.

Creating additional queues

Add a queue by extending the Tribe\Project\Queues\Contracts\Queue class.

A queue class only requires the method get_name(). The class DefaultQueue is a good example.

To create a Queue object, inject a backend object. The DI container will automatically inject the global backend when autowiring is used. But if you're using an additional queue, chances are you are using it so that you can speak to a different backend.

Built-in tasks

Noop

A good task to test that you have a functional Queue, Noop mostly processes tasks correctly the first time. Add whatever message you'd like to $args['fake'] ex: $queue->dispatch( Noop::class, [ 'fake' => 'custom message' ] );

Email

Built in is a task for wp_mail(). To use it you'll need to add the following to your WP config: define( 'QUEUE_MAIL', true ); You can also optionally define a default queue name with QUEUE_MAIL_QUEUE_NAME. If this value is not set, it will default to default. To process the queued mail items wp s1 queues process <queue-name> with WP-CLI.

Other CLI commands

wp s1 queues add-tasks [--count=0] If you need to test a queue/backend are registered and functioning properly. By default this creates a random (1-50) Noop tasks. Noop fails on processing about 10% of the time so you can also verify ack/nack is functioning as expected.

wp s1 queues list Lists the registered queues and corresponding backends.