Download the PHP package tarantool/queue without Composer

Tarantool Queue

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.

Table of contents

• Installation
• Before start
• Working with queue
  • Data types
  • Tasks
  • Producer API
  • Consumer API
  • Statistics
  • Custom methods
• Testing
• License

Installation

The recommended way to install the library is through Composer:

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:

You can read more about the box configuration in the official Tarantool documentation. More information on queue configuration can be found here.

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:

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:

where $client is an instance of Tarantool\Client\Client from the tarantool/client package.

Data types

Under the hood Tarantool uses MessagePack 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:

To learn more about object serialization, please follow this link.

Tasks

Most of the Task object containing the following getters:

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 and pri options:

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:

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

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

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

To bury (disable) a task:

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

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

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

To delete all tasks in a queue:

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

Statistics

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

The result of this call might look like this:

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

Custom methods

Thanks to flexible nature of the 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:

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

Testing

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

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

And then run both unit and integration tests:

The library uses PHPUnit 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:

License

The library is released under the MIT License. See the bundled LICENSE file for details.