Extending the queue

Queues can be used to process items in the background, outside of a web request. Multiple tasks can be logged in a queue and processed over time. Each queue is checked and processed every 10 minutes.

Custom queue handlers can be configured and run by the Jadu Central queue master to process jobs stored in the JaduQueueJobs database table.

Creating your own queue and handler

To add a custom queue and handler, first create the Handler class and extend Jadu's QueueJobHandler. The only method that will be used on the handler is run() which will be called for each queue job.

Example handler:

class MyQueueJobHandler extends QueueJobHandler
{
    public function run($params = [])
    {
        // do something with the data passed in $params
    }
}

Now we have a handler, we need to add a migration to create a database entry defining the new queue.

The migration will need to add a record to the JaduQueues database table including the following:

Column	Description
name	Name of the queue. This should be unique for the site.
status	Status of the queue, defaults to 0
scheduler	The method used to identify the next job to be processed. All queues use "first in, first out", indicated by the value fifo. This is currently the only supported option.

Example migration:

namespace DoctrineMigrations;

use Doctrine\Migrations\AbstractMigration;
use Doctrine\DBAL\Schema\Schema;

class Version20200527123456 extends AbstractMigration
{
    public function up(Schema $schema)
    {
        $sql = <<<SQL
            INSERT INTO JaduQueues (
                name, status, scheduler
            ) VALUES (
                'my.queue', '0', 'fifo'
            )
        SQL;

        $this->addSql($sql);
    }

    public function down(Schema $schema)
    {
        $this->addSql("DELETE FROM JaduQueues WHERE name = 'my.queue'");
    }
}

Next create queue.xml in path/to/jadu/config if it does not already exist. An empty queue.xml should contain the following:

<?xml version="1.0" encoding="utf-8" ?>
<system xmlns:config="http://www.jadu.co.uk/schema/config">
    <driver>jadu</driver>
    <handlers config:type="array">
    </handlers>
</system>

To register your handler, add a new item element to queue.xml.

Attribute	Description
class	The handler's class name.
handler	A unique name for the handler
count	Determines the number of items processed per queue run.

<handlers config:type="array">
    <item
        class="MyQueueJobHandler"
        handler="my.task"
        count="2"
    >my.queue</item>
</handlers>

The element's value (my.queue in the example above) is the name of the queue that the handler will work for. This must match the queue name in the database entry for the queue.

Adding a job to the queue

To add a job to our new queue, we must first retrieve the queue from the database:

$queue = Jadu_Service_Container::getInstance()->getQueue('my.queue');

Then add the job by calling the add() method, passing in any required data in an array. This same array will be passed to the job handler in $params when it is executed.

$queue->add([
    'foo' => 'bar',
    'bar' => 'baz',
    'baz' => 'foo',
]);

Troubleshooting

See our queue troubleshooting guide for more information on troubleshooting queues.