Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tarantool-php/queue

PHP bindings for Tarantool Queue.
https://github.com/tarantool-php/queue

nosql php queue tarantool

Last synced: 30 days ago
JSON representation

PHP bindings for Tarantool Queue.

Lists

README 

        
# 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://scrutinizer-ci.com/g/tarantool-php/queue/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)

[![Code Coverage](https://scrutinizer-ci.com/g/tarantool-php/queue/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)

[![Mentioned in Awesome PHP](https://awesome.re/mentioned-badge.svg)](https://github.com/ziadoz/awesome-php)

[![Telegram](https://img.shields.io/badge/Telegram-join%20chat-blue.svg)](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



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



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



```bash

composer require tarantool/queue

```



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



```lua

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



```bash

sudo tarantoolctl start queues

```



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



```php

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



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:



```php

$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



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

containing the following getters:



```php

Task::getId()

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

Task::getData()

```



And some sugar methods:



```php

Task::isReady()

Task::isTaken()

Task::isDone()

Task::isBuried()

Task::isDelayed()

```



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



```php

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



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



```php

$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):



```php

$data = $task->getData();



// process $data



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

```



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



```php

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



```php

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

```



To bury (disable) a task:



```php

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

```



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



```php

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

```



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



```php

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

```



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



```php

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

```



To delete all tasks in a queue:



```php

$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



The `stats()` method provides access to the statistical information accumulated

since a queue was created:



```php

$stats = $queue->stats();

```



The result of this call might look like this:



```php

[

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



```php

$calls = $queue->stats('calls');

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

```



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



```lua

-- 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()`:



```php

$result = $queue->call('put_many', [

    'foo' => ['foo', [Options::DELAY => 30.0]],

    'bar' => ['bar'],

]);

```



## Testing



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



```bash

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

```



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



```bash

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:



```bash

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:



```bash

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

    vendor/bin/phpunit --testsuite=unit

```



## License



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