PHP client for Tarantool

A pure PHP client for Tarantool 1.7.1 or above.

Features

• Written in pure PHP, no extensions are required
• Supports Unix domain sockets
• Supports SQL protocol
• Supports user-defined types (decimals and UUIDs are included)
• Highly customizable
• Thoroughly tested
• Being used in a number of projects, including Queue, Mapper, Web Admin and others.

Table of contents

• Installation
• Creating a client
• Handlers
• Middleware
• Data manipulation
  • Binary protocol
  • SQL protocol
  • User-defined types
• Tests
• Benchmarks
• License

Installation

The recommended way to install the library is through Composer:

composer require tarantool/client

In order to use the Decimal type that was added in Tarantool 2.3, you additionally need to install the decimal extension. Also, to improve performance when working with the UUID type, which is available since Tarantool 2.4, it is recommended to additionally install the uuid extension.

Creating a client

The easiest way to create a client is by using the default configuration:

use Tarantool\Client\Client;

$client = Client::fromDefaults();

The client will be configured to connect to 127.0.0.1 on port 3301 with the default stream connection options. Also, the best available msgpack package will be chosen automatically. A custom configuration can be accomplished by one of several methods listed.

DSN string

The client supports the following Data Source Name formats:

tcp://[[username[:password]@]host[:port][/?option1=value1&optionN=valueN]
unix://[[username[:password]@]path[/?option1=value1&optionN=valueN]

Some examples:

use Tarantool\Client\Client;

$client = Client::fromDsn('tcp://127.0.0.1');
$client = Client::fromDsn('tcp://[fe80::1]:3301');
$client = Client::fromDsn('tcp://user:pass@example.com:3301');
$client = Client::fromDsn('tcp://user@example.com/?connect_timeout=5.0&max_retries=3');
$client = Client::fromDsn('unix:///var/run/tarantool/my_instance.sock');
$client = Client::fromDsn('unix://user:pass@/var/run/tarantool/my_instance.sock?max_retries=3');

If the username, password, path or options include special characters such as @, :, / or %, they must be encoded according to RFC 3986 (for example, with the rawurlencode() function).

Array of options

It is also possible to create the client from an array of configuration options:

use Tarantool\Client\Client;

$client = Client::fromOptions([
    'uri' => 'tcp://127.0.0.1:3301',
    'username' => '<username>',
    'password' => '<password>',
    ...
);

The following options are available:

Name | Type | Default | Description --- | :---: | :---: | --- uri | string | 'tcp://127.0.0.1:3301' | The connection uri that is used to create a StreamConnection object. connect_timeout | float | 5.0 | The number of seconds that the client waits for a connect to a Tarantool server before throwing a ConnectionFailed exception. socket_timeout | float | 5.0 | The number of seconds that the client waits for a respond from a Tarantool server before throwing a CommunicationFailed exception. tcp_nodelay | boolean | true | Whether the Nagle algorithm is disabled on a TCP connection. persistent | boolean | false | Whether to use a persistent connection. username | string | | The username for the user being authenticated. password | string | '' | The password for the user being authenticated. If the username is not set, this option will be ignored. max_retries | integer | 0 | The number of times the client retries unsuccessful request. If set to 0, the client does not try to resend the request after the initial unsuccessful attempt.

Custom build

For more deep customisation, you can build a client from the ground up:

use MessagePack\BufferUnpacker;
use MessagePack\Packer;
use Tarantool\Client\Client;
use Tarantool\Client\Connection\StreamConnection;
use Tarantool\Client\Handler\DefaultHandler;
use Tarantool\Client\Handler\MiddlewareHandler;
use Tarantool\Client\Middleware\AuthenticationMiddleware;
use Tarantool\Client\Middleware\RetryMiddleware;
use Tarantool\Client\Packer\PurePacker;

$connection = StreamConnection::createTcp('tcp://127.0.0.1:3301', [
    'socket_timeout' => 5.0,
    'connect_timeout' => 5.0,
    // ...
]);

$pureMsgpackPacker = new Packer();
$pureMsgpackUnpacker = new BufferUnpacker();
$packer = new PurePacker($pureMsgpackPacker, $pureMsgpackUnpacker);

$handler = new DefaultHandler($connection, $packer);
$handler = MiddlewareHandler::append($handler, [
    RetryMiddleware::exponential(3),
    new AuthenticationMiddleware('<username>', '<password>'),
    // ...
]);

$client = new Client($handler);

Handlers

A handler is a function which transforms a request into a response. Once you have created a handler object, you can make requests to Tarantool, for example:

use Tarantool\Client\Keys;
use Tarantool\Client\Request\CallRequest;

...

$request = new CallRequest('box.stat');
$response = $handler->handle($request);
$data = $response->getBodyField(Keys::DATA);

The library ships with two handlers:

• DefaultHandler is used for handling low-level communication with a Tarantool server
• MiddlewareHandler is used as an extension point for an underlying handler via middleware

Middleware

Middleware is the suggested way to extend the client with custom functionality. There are several middleware classes implemented to address the common use cases, like authentification, logging and more. The usage is straightforward:

use Tarantool\Client\Client;
use Tarantool\Client\Middleware\AuthenticationMiddleware;

$client = Client::fromDefaults()->withMiddleware(
    new AuthenticationMiddleware('<username>', '<password>')
);

You may also assign multiple middleware to the client (they will be executed in FIFO order):

use Tarantool\Client\Client;
use Tarantool\Client\Middleware\FirewallMiddleware;
use Tarantool\Client\Middleware\LoggingMiddleware;
use Tarantool\Client\Middleware\RetryMiddleware;

...

$client = Client::fromDefaults()->withMiddleware(
    FirewallMiddleware::allowReadOnly(),
    RetryMiddleware::linear(),
    new LoggingMiddleware($logger)
);

Please be aware that the order in which you add the middleware does matter. The same middleware, placed in different order, can give very different or sometimes unexpected behavior. To illustrate, consider the following configurations:

$client1 = Client::fromDefaults()->withMiddleware(
    RetryMiddleware::linear(),
    new AuthenticationMiddleware('<username>', '<password>') 
);

$client2 = Client::fromDefaults()->withMiddleware(
    new AuthenticationMiddleware('<username>', '<password>'), 
    RetryMiddleware::linear()
);

$client3 = Client::fromOptions([
    'username' => '<username>',
    'password' => '<password>',
])->withMiddleware(RetryMiddleware::linear());

In this example, $client1 will retry an unsuccessful operation and in case of connection problems may initiate reconnection with follow-up re-authentication. However, $client2 and $client3 will perform reconnection without doing any re-authentication.

You may wonder why $client3 behaves like $client2 in this case. This is because specifying some options (via array or DSN string) may implicitly register middleware. Thus, the username/password options will be turned into AuthenticationMiddleware under the hood, making the two configurations identical.

To make sure your middleware runs first, use the withPrependedMiddleware() method:

$client = $client->withPrependedMiddleware($myMiddleware);

Data manipulation

Binary protocol

The following are examples of binary protocol requests. For more detailed information and examples please see the official documentation.

<details> <summary><strong>Select</strong></summary><br />

Fixtures

local space = box.schema.space.create('example')
space:create_index('primary', {type = 'tree', parts = {1, 'unsigned'}})
space:create_index('secondary', {type = 'tree', unique = false, parts = {2, 'str'}})
space:insert({1, 'foo'})
space:insert({2, 'bar'})
space:insert({3, 'bar'})
space:insert({4, 'bar'})
space:insert({5, 'baz'})

Code

``