tarantool queue php

dev-master 2018-03-13 10:27 UTC


Compatible with php7.

Tarantool is a NoSQL database running in a Lua application server. It integrates Lua modules, called LuaRocks. This package provides PHP bindings for Tarantool Queue LuaRock.


The recommended way to install the library is through Composer:

$ composer require klevialent/tarantool-queue-php

QueueProcessController compatible only with yii2, and if you want to use it:

$ composer require yiisoft/yii2

Before start

In order to use queue, you first need to make sure that your Tarantool instance is configured, up and running. The minimal required configuration might look like this:

-- queues.lua

box.cfg {listen=3301}

queue = require('queue')

queue.create_tube('foobar', 'fifo', { if_not_exists=true })

You can read more about the box configuration in the official Tarantool documentation. For more information about the queue configuration check out queue's README.

To start the instance you need to copy (or symlink) queues.lua file into the /etc/tarantool/instances.enabled directory and run the following command:

$ sudo tarantoolctl start queues

Working with queue

See example-yii or read more.

$queue = Yii::$app->queue->foobar;


Implement method process() of WorkerInterface and run it as demon.
If you use yii2

//add to config
    'controllerMap' => [
        'queue-process' => WebDevTeam\TarantoolQueuePhp\QueueProcessController::className(),

//console command
php yii queue-process foobar

Data types

Under the hood Tarantool uses MessagePack binary format to serialize/deserialize data being stored in a queue. This means that it's safe to use such data types as null, bool, int, float, string, binary string and array without any manual pre- or post-processing:

$queue->put(['foo' => ['bar' => ['baz' => null]]]);


Task::getState() // States::READY, States::TAKEN, States::DONE, States::BURY or States::DELAYED

And some sugar methods:


Producer API

As you've already seen, to insert a task into a queue you need to call put() method, which accepts two arguments: the data you want to process and optional array of task options, which this particular queue supports. For example, fifottl queue (which we defined earlier in our Lua config file), supports delay, ttl, ttr, pri and temporary options:

$queue->put('foo', ['delay' => 30]);
$queue->put('bar', ['ttl' => 5]);
$queue->put('baz', ['ttr' => 10, 'pri' => 42]);

See the full list of available options here.

Consumer API

To reserve a task for execution, call take() method. It accepts an optional timeout parameter. If a timeout value is supplied the call will wait timeout seconds until a READY task appears in the queue. The method returns either a Task object or null:

$task = $queue->take();
// wait 2 seconds
$task = $queue->take(2);
// wait 100 milliseconds
$task = $queue->take(.1);

After successful execution, a task can be marked as acknowledged (that will also delete the task from a queue):

$data = $task->getData();

// process $data

$task = $queue->ack($task->getId());

Or put back into the queue in case it cannot be executed:

$task = $queue->release($task->getId());

// for ttl-like queues you can specify a delay
$task = $queue->release($task->getId(), ['delay' => 30]);

To look at a task without changing its state, use:

$task = $queue->peek($task->getId());

To bury (disable) a task:

$task = $queue->bury($task->getId());

To reset buried task(s) back to READY state:

$count = $queue->kick(3); // kick 3 buried tasks

A task (in any state) can be deleted permanently with delete():

$task = $queue->delete($task->getId());

To delete all tasks in a queue:


For a detailed API documentation, please read the section "Using the queue module" of the queue's README.


The stats() method provides access to the statistical information accumulated since a queue was created:

$stats = $queue->stats();

The result of this call might look like this:

    'tasks' => [
        'taken'   => 1,
        'buried'  => 1,
        'ready'   => 1,
        'done'    => 0,
        'delayed' => 0,
        'total'   => 3,
    'calls' => [
        'bury' => 1,
        'put'  => 3,
        'take' => 1,

In addition, you can specify a key to return only a subset of the array:

$calls = $queue->stats('calls');
$total = $queue->stats('tasks.total');