Download the PHP package activecollab/jobsqueue without Composer

JobsQueue Library

Reason for existence: it's light, with very few dependencies. It can be used with cron + database powered queues for people who are not allowed to run a proper messaging or job management server. Or you can execute jobs through proper messaging or job manager with it.

Installation

To install it, use Composer:

Basic Usage

This library uses three elements:

1. Dispatcher is here to dispatch jobs,
2. Queues make sure that jobs can be queued,
3. Jobs perform the actual work.

As a demonstration, we'll create a simple job that increments a number:

Tip: To fail an attempt, just throw an exception from within execute() method.

Now, lets create a dispatcher instance that manages one MySQL powered queue:

Lets add a job to the queue:

Code that executes jobs from the queue will get this job as next available job:

To run a job and wait for the result, use execute() instead of dispatch():

When called like this, jobs are executed right away. execute() suppresses exceptions by default, so you should set $silent to false if you want exceptions to bubble out:

Job Properties

When constructing a new Job instance, you can set an array of job data, as well as following job properties:

1. priority - Value between 0 and 4294967295 that determins how important the job is (a job with higher value has higher priority). Default is 0 (job is not a priority),
2. attempts - Number of attempts before job is considered to fail and is removed from the queue. Value can be between 1 and 256. Default is 1 (try once and fail if it does not go well),
3. delay - Number of seconds to wait before first execution (in case when first_attempt_delay is not set), as well as retries if the job fails and needs to be retried. Value can be between 1 and 7776000 (90 days). Default is 0 (no delay),
4. first_attempt_delay - Number of seconds to wait before the first job execution.

Accessing Properties in a Job

Once in an job's execute() method, you can access job properties using getData() method:

Batches

Jobs can be added to the queue in batches. Once in a batch, job queue will execute them as any other job, but you will be able to track progress of batch:

All batches have name, so they are easy to find using command line tools.

Channels

In some situations, it is useful to have multiple channels and consumer listening on them. For example, you can have a consumer on a mailing server listening only on mail channel, but not listening on other channels (which jobs it is not suited to perform).

By default, all jobs go to main channel (QueueInterface::MAIN_CHANNEL), but channel can be specified when job is added to the queue:

By default, dispatcher will throw an exception if you try to add a job to an unknown channel. This can be turned off:

Background Process

Jobs can report that they launched a process:

When they do, queue clean up and maintenance routines will not consider this job as stuck as long as process with the given PID is running. When process is done (we can't find it), job is considered to be done.

Information about jobs that launched processes can be found using QueueInterface::getBackgroundProcesses() method. This method returns an array, where each record in an array contains a job ID, job type and process ID:

will output something like this:

Note: Process reporting and watching is not supported on Windows systems at the moment.

Executing CLI commands from jobs

If you need a job to simply run CLI command, there is a handy trait ExecuteCliCommand. You can pass a command call signature, arguments and environment variables to the command.

Example usage:

will produce a CLI command:

Version 5.0 upgrade

Backward compatibility notes:

1. Check all calls to JobsDispatcher::batch() method, and make sure that callbacks do not expect $batch to be passed on by reference.
2. Remove ActiveCollab\JobsQueue\DispatcherInterface and ActiveCollab\JobsQueue\Dispatcher if used in client code.

To do

1. Add logging to all relevant methods in MySQL queue
2. Implement job quarantine