This document provides a brief overview of how to use RPQ within your project.
RPQ can be added to your project via composer.
composer require rpq/server
Note that you may need to adjust your
minimum-stability
settings until RPQ has a proper tag.
Once RPQ has been added to your project, you should create a configuration file as outlined in Configuration.
RPQ can be started by running the following command:
./vendor/bin/rpq queue -c /path/to/config.yml
If you wish to use a queue configuration other than default
, use the --name
CLI arguement.
./vendor/bin/rpq queue -c /path/to/config.yml --name <queueName>
RPQ will automatically start listening for new jobs sent to Redis.
Since RPQ created sub-processes, when developing new job classes you do not need to to restart RPQ.
All job classes extends from RPQ\Queue\AbstractJob
, and at minimum must implement the following method:
public function perform(array $args = []): int
This method must return an integer status code. If the return code is 0
, RPQ will consider the job to be successful, otherwise RPQ will consider the job to be failed, and will log the error appropriately, and/or requeue it in the priority queue per it's retry settings.
In general, as long as your perform method returns an integer status code at some point, the job can call any other PHP class you may require.
The STDOUT
and STDERR
outputs of the worker will automatically be logged by the main queue process to the main logger declared within your configuration.
The current job ID assigned to your job can be queried by getting the protected $id
property.
$jobId = $this->id;
If the main RPQ process recieves a SIGQUIT
signal, it will send a SIGTERM
signal to all worker processes. Worker processes can handle this signal by registering a shutdown method.
private function shutdown() {}
Within this function you can register shutdown behavior.
If this method returns true
, then RPQ will assume that the shutdown handled handled, and will return with exit code 0
. RPQ will not requeue your job if this methods returns true
.
If this method returns false
, the worker process will return an exit code 3
. RPQ will automatically requeue your job.
If this method is not explicitly declared within your job, or if you wish to ignore the SIGTERM
signal, your job will continue processing.
Note that if queue configuration declares a
deadline_timeout
, aSIGKILL
will be sent to the jobdealine_timeout
seconds after the initialSIGTERM
signal to sent. It is important to register a shutdown handler for your job to avoid jobs being forcefully killed and requeued.
Note that in order for
pcntl
to listen to jobs, you shoulddeclare(ticks=1)
within your Job listener.
Jobs can be enqueued to RPQ via rpq/client
, which is pre-bundled with rpq/server
. If RPQ is running on a different system from your application, rpq/client
can be included via composer.
composer require rpq/client
Jobs can be pushed to RPQ using their fully-qualified class name, as illustrated in the following example.
$redis = new \Redis();
$redis->connect('127.0.0.1', 6379);
$rpq = new RQP\Client($redis);
$rpq->push('My\Namespaced\Job');
More information on
rpq/client
can be found at https://github.com/charlesportwoodii/rpq-client.