Background jobs with php and resque: part 8, a glance at php-resque-ex

In all the previous part of this tutorial serie, we were using php-resque. But in some cases, this original library is not enough.

Php-resque-ex is a fork of php-resque, and provides additional features. It has the same API as php-resque, and can replace it without problems.

PHPRedis support

php-resque-ex will detect and use phpredis if installed, else will fallback to redisent.

Logging support

Instead of piping the worker output to a file, php-resque-ex implements a real logging engine: Monolog.

You can log to various handlers: file, mongodb, syslog, socket, amqp etc … See Monolog documentation for all supported handlers.

You can specify the handler to use by using the LOGHANDLER environment variable. LOGHANDLERTARGET is used to set the handler target.

LOGHANDLER=mongodb LOGHANDLERTARGET=mongodb://127.0.0.1:453 QUEUE=default php resque.php

This command will create a new worker, and log the output to mongodb, located at mongodb://127.0.0.1:453.

If you’re using Fresque or CakeResque, use the --log-handler and --log-handler-target arguments.

By default, php-resque-ex will use the RotatingFile handler, that’s saving the log to a different each day.

Even if you use a log engine, you should still pipe the output to a log file to track php fatal errors.

If you’re using a database, like mongodb to log the events, you can sort and filter events. Each events contains a date, the action done, and the worker ID. You can easily search all events from a worker, or track all the events related to a job.

Job creation delegation

By defaul, when a roekr execute a job, it will instantiate the job class and call the perform() method.

$job = new MyJobClass();
$job->perform();

MyJobClass is the name you gave when you queued the job

Resque::enqueue('default', 'MyJobClass', array());

But what if the classnames doesn’t match ? That could happen in some rare case. Some framework, like CakePHP, uses a special naming scheme for their classname: PluginName.ClassName. The worker must then do some extra work to find and instantiate the right ClassName from PluginName.ClassName.

To do that, you can create a Resque_Job_Creator class

class Resque_Job_Creator
{
    public static function createJob($className, $args) {

        // $className is you job class name, the second arguments when enqueuing a job
        // $args are the arguments passed to your jobs

        // Instanciate your class, and return the instance

        return new $className();
    }
}

And make it visible by the worker. (you can include it in the file referenced by APP_INCLUDE).

If present, the worker will use that class to instantiate the job class. Take a look at CakeResque bootstrap for an usage example.

Failed job logging

Although php-resque already log failed jobs, it just save them in a list. It’s not searchable.

Php-resque-ex uses a different approach, and create a new entry by failure. That way, you can search a failed job by its ID. Failed job log is kept for 2 weeks.

Custom redis database and namespace

You can tell each of your worker to use a different Redis database or namespace. Use the REDIS_DATABASE and REDIS_NAMESPACE environment variable.

Command Line Interface

Php-resque-ex is shipped with Fresque, a command line tool to manage workers.

Installation

Clone the git repo

$ git clone git://github.com/kamisama/php-resque-ex.git

cd into the folder you just cloned

$ cd ./php-resque-ex

Download Composer

$ curl -s https://getcomposer.org/installer | php

Install dependencies

$ php composer.phar install

You can then point your application to php-resque-ex instead of php-resque.

Or you can rename the folder to php-resque, and overwrite the existing one.

Refer to php-resque-ex website for up to date documentation.