PHPackages                             tarantool/queue - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. tarantool/queue

ActiveLibrary[Queues & Workers](/categories/queues)

tarantool/queue
===============

PHP bindings for Tarantool Queue.

v0.10.0(3y ago)64136.2k↓37%7[2 issues](https://github.com/tarantool-php/queue/issues)4MITPHPPHP ^7.2.5|^8

Since Jun 24Pushed 1y ago5 watchersCompare

[ Source](https://github.com/tarantool-php/queue)[ Packagist](https://packagist.org/packages/tarantool/queue)[ GitHub Sponsors](https://github.com/rybakit)[ RSS](/packages/tarantool-queue/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (13)Used By (4)

Tarantool Queue
===============

[](#tarantool-queue)

[![Quality Assurance](https://github.com/tarantool-php/queue/workflows/QA/badge.svg)](https://github.com/tarantool-php/queue/actions?query=workflow%3AQA)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/9a7185e5ecef313012497ef9b7d6c71417c046ed027b95220fd090689b0f84f4/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f746172616e746f6f6c2d7068702f71756575652f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/d7acb3586b641ddb53a182650aa743f121edd8eb934ff99c9d174803254437a9/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f746172616e746f6f6c2d7068702f71756575652f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)[![Mentioned in Awesome PHP](https://camo.githubusercontent.com/1667baa3145a7b9b2a0ae17d8c7b09b4d471f79aa02b0615ab07d64d9988a198/68747470733a2f2f617765736f6d652e72652f6d656e74696f6e65642d62616467652e737667)](https://github.com/ziadoz/awesome-php)[![Telegram](https://camo.githubusercontent.com/fcbb762172f6027f3e2f84b45d2f561a6c730200c819552f3cf384015c3c782f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54656c656772616d2d6a6f696e253230636861742d626c75652e737667)](https://t.me/tarantool_php)

[Tarantool](https://www.tarantool.io/en/developers/) is a NoSQL database running in a Lua application server. It integrates Lua modules, called [LuaRocks](https://luarocks.org/). This package provides PHP bindings for [Tarantool Queue LuaRock](https://github.com/tarantool/queue/).

Table of contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Before start](#before-start)
- [Working with queue](#working-with-queue)
    - [Data types](#data-types)
    - [Tasks](#tasks)
    - [Producer API](#producer-api)
    - [Consumer API](#consumer-api)
    - [Statistics](#statistics)
    - [Custom methods](#custom-methods)
- [Testing](#testing)
- [License](#license)

Installation
------------

[](#installation)

The recommended way to install the library is through [Composer](http://getcomposer.org):

```
composer require tarantool/queue
```

Before start
------------

[](#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', 'fifottl', {if_not_exists = true})
```

> *You can read more about the box configuration in the official Tarantool [documentation](http://tarantool.org/doc/book/configuration/index.html#initialization-file). More information on queue configuration can be found [here](https://github.com/tarantool/queue/blob/master/README.md).*

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
------------------

[](#working-with-queue)

Once you have your instance running, you can start by creating a queue object with the queue (tube) name you defined in the Lua script:

```
use Tarantool\Queue\Queue;

...

$queue = new Queue($client, 'foobar');
```

where `$client` is an instance of `Tarantool\Client\Client` from the [tarantool/client](https://github.com/tarantool-php/client) package.

### Data types

[](#data-types)

Under the hood Tarantool uses [MessagePack](http://msgpack.org/) binary format to serialize/deserialize data being stored in a queue. It can handle most of the PHP data types (except resources and closures) without any manual pre- or post-processing:

```
$queue->put('foo');
$queue->put(true);
$queue->put(42);
$queue->put(4.2);
$queue->put(['foo' => ['bar' => ['baz' => null]]]);
$queue->put(new MyObject());
```

> *To learn more about object serialization, please follow this [link](https://github.com/tarantool-php/client#user-defined-types).*

### Tasks

[](#tasks)

Most of the [Queue API](src/Queue.php) methods return a [Task](src/Task.php) object containing the following getters:

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

And some sugar methods:

```
Task::isReady()
Task::isTaken()
Task::isDone()
Task::isBuried()
Task::isDelayed()
```

### Producer API

[](#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](#before-start) in our Lua config file), supports `delay`, `ttl`, `ttr` and `pri` options:

```
use Tarantool\Queue\Options;

$queue->put('foo', [Options::DELAY => 30.0]);
$queue->put('bar', [Options::TTL => 5.0]);
$queue->put('baz', [Options::TTR => 10.0, Options::PRI => 42]);
```

> *See the full list of available options [here](https://github.com/tarantool/queue#queue-types).*

### Consumer API

[](#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](#tasks) object or `null`:

```
$taskOrNull = $queue->take();

// wait 2 seconds
$taskOrNull = $queue->take(2.0);

// wait 100 milliseconds
$taskOrNull = $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 queues you can specify a delay
$task = $queue->release($task->getId(), [Options::DELAY => 30.0]);
```

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
```

To increase TTR and/or TTL of a running task (only for \*ttl queues):

```
$taskOrNull = $queue->touch($takenTask->getId(), 5.0); // increase ttr/ttl to 5 seconds
```

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

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

To delete all tasks in a queue:

```
$queue->truncate();
```

> *For a detailed API documentation, please read the section "[Using the queue module](https://github.com/tarantool/queue#using-the-queue-module)" of the queue README.*

### Statistics

[](#statistics)

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');
```

### Custom methods

[](#custom-methods)

Thanks to flexible nature of the [queue](https://github.com/tarantool/queue/) Lua module, you can easily create your own queue drivers or extend existing ones with an additional functionality. For example, suppose you added the `put_many` method to your `foobar` queue, which inserts multiple tasks atomically:

```
-- queues.lua

...

queue.tube.foobar.put_many = function(self, items)
    local put = {}

    box.begin()
    for k, item in pairs(items) do
        put[k] = tube:put(unpack(item))
    end
    box.commit()

    return put
end
```

To invoke this method from php, use `Queue::call()`:

```
$result = $queue->call('put_many', [
    'foo' => ['foo', [Options::DELAY => 30.0]],
    'bar' => ['bar'],
]);
```

Testing
-------

[](#testing)

The easiest way to run tests is with Docker. First, build an image using the [dockerfile.sh](dockerfile.sh) generator:

```
./dockerfile.sh | docker build -t queue -
```

Then run a Tarantool instance (needed for integration tests):

```
docker network create tarantool-php
docker run -d --net=tarantool-php -p 3301:3301 --name=tarantool \
    -v $(pwd)/tests/Integration/queues.lua:/queues.lua \
    tarantool/tarantool:2 tarantool /queues.lua
```

And then run both unit and integration tests:

```
docker run --rm --net=tarantool-php -v $(pwd):/queue -w /queue queue
```

The library uses [PHPUnit](https://phpunit.de/) under the hood, and if needed, you can pass additional arguments and options to the `phpunit` command. For example, to run only unit tests, execute:

```
docker run --rm --net=tarantool-php -v $(pwd):/queue -w /queue queue \
    vendor/bin/phpunit --testsuite=unit
```

License
-------

[](#license)

The library is released under the MIT License. See the bundled [LICENSE](LICENSE) file for details.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance33

Infrequent updates — may be unmaintained

Popularity44

Moderate usage in the ecosystem

Community22

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 93.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~239 days

Recently: every ~420 days

Total

12

Last Release

1343d ago

PHP version history (5 changes)v0.1.0PHP >=5.4.0

v0.3.0PHP ^5.4|^7.0

v0.7.0PHP ^7.1

v0.9.0PHP ^7.1|^8

v0.10.0PHP ^7.2.5|^8

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/533861?v=4)[Eugene Leonovich](/maintainers/rybakit)[@rybakit](https://github.com/rybakit)

---

Top Contributors

[![rybakit](https://avatars.githubusercontent.com/u/533861?v=4)](https://github.com/rybakit "rybakit (62 commits)")[![ylobankov](https://avatars.githubusercontent.com/u/3645987?v=4)](https://github.com/ylobankov "ylobankov (2 commits)")[![0x501D](https://avatars.githubusercontent.com/u/5861368?v=4)](https://github.com/0x501D "0x501D (1 commits)")[![Buristan](https://avatars.githubusercontent.com/u/37304959?v=4)](https://github.com/Buristan "Buristan (1 commits)")

---

Tags

nosqlphpqueuetarantoolqueuejobschedulenosqltaskworkerprioritytarantoolttldelayedttr

###  Code Quality

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tarantool-queue/health.svg)

```
[![Health](https://phpackages.com/badges/tarantool-queue/health.svg)](https://phpackages.com/packages/tarantool-queue)
```

###  Alternatives

[clue/mq-react

Mini Queue, the lightweight in-memory message queue to concurrently do many (but not too many) things at once, built on top of ReactPHP

144691.7k4](/packages/clue-mq-react)[rybakit/phive-queue

$queue->push('I can be popped off after', '10 minutes');

16441.5k1](/packages/rybakit-phive-queue)[iron-io/iron_worker

Client library for IronWorker (multi-language worker platform that runs tasks in the background, in parallel, and at scale.)

57208.5k1](/packages/iron-io-iron-worker)[orisai/scheduler

Cron job scheduler - with locks, parallelism and more

4037.1k4](/packages/orisai-scheduler)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)