PHP client for Tarantool

A pure PHP client for Tarantool 1.7.1 and later, including the 2.x and 3.x series.

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.

Installation

This release requires PHP 8.2 or newer and rybakit/msgpack 0.11.2 or newer.

The recommended way to install the library is through Composer:

composer require tarantool/client

To use the Decimal type added in Tarantool 2.3, install the decimal extension. To improve performance when working with the UUID type, available since Tarantool 2.4, you can also 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 connects to 127.0.0.1 on port 3301 using the default stream connection options. It also selects the best available MessagePack package automatically. You can configure the client in several ways, as described below.

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 to 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 response 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 an unsuccessful request. If set to 0, the client does not retry after the initial unsuccessful attempt.

Custom build

For more extensive customization, 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 transforms a request into a response. Once you have created a handler object, you can use it to send 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 recommended way to extend the client with custom functionality. The library includes middleware for common use cases, such as authentication and logging. See the full list in src/Middleware. Usage is straightforward:

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

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

You can also add multiple middleware components to the client. They execute 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)
);

The order in which you add middleware matters. The same middleware, placed in a different order, can produce 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.

Select

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

$space = $client->getSpace('example');
$result1 = $space->select(Criteria::key([1]));
$result2 = $space->select(Criteria::index('secondary')
    ->andKey(['bar'])
    ->andLimit(2)
    ->andOffset(1)
);

printf("Result 1: %s\n", json_encode($result1));
printf("Result 2: %s\n", json_encode($result2));

Output

Result 1: [[1,"foo"]]
Result 2: [[3,"bar"],[4,"bar"]]

Insert

Fixtures

local space = box.schema.space.create('example')
space:create_index('primary', {type = 'tree', parts = {1, 'unsigned'}})

Code

$space = $client->getSpace('example');
$result = $space->insert([1, 'foo', 'bar']);

printf("Result: %s\n", json_encode($result));

Output

Result: [[1,"foo","bar"]]

Space data

tarantool> box.space.example:select()
---
- - [1, 'foo', 'bar']
...

Update

Fixtures

local space = box.schema.space.create('example')
space:create_index('primary', {type = 'tree', parts = {1, 'unsigned'}})
space:format({
    {name = 'id', type = 'unsigned'}, 
    {name = 'num', type = 'unsigned'}, 
    {name = 'name', type = 'string'}
})

space:insert({1, 10, 'foo'})
space:insert({2, 20, 'bar'})
space:insert({3, 30, 'baz'})

Code

$space = $client->getSpace('example');
$result = $space->update([2], Operations::add(1, 5)->andSet(2, 'BAR'));

// Since Tarantool 2.3 you can refer to tuple fields by name:
// $result = $space->update([2], Operations::add('num', 5)->andSet('name', 'BAR'));

printf("Result: %s\n", json_encode($result));

Output

Result: [[2,25,"BAR"]]

Space data

tarantool> box.space.example:select()
---
- - [1, 10, 'foo']
  - [2, 25, 'BAR']
  - [3, 30, 'baz']
...

Upsert

Fixtures

local space = box.schema.space.create('example')
space:create_index('primary', {type = 'tree', parts = {1, 'unsigned'}}) 
space:format({
    {name = 'id', type = 'unsigned'}, 
    {name = 'name1', type = 'string'}, 
    {name = 'name2', type = 'string'}
})

Code

$space = $client->getSpace('example');
$space->upsert([1, 'foo', 'bar'], Operations::set(1, 'baz'));
$space->upsert([1, 'foo', 'bar'], Operations::set(2, 'qux'));

// Since Tarantool 2.3 you can refer to tuple fields by name:
// $space->upsert([1, 'foo', 'bar'], Operations::set('name1', 'baz'));
// $space->upsert([1, 'foo', 'bar'], Operations::set('name2', 'qux'));

Space data

tarantool> box.space.example:select()
---
- - [1, 'foo', 'qux']
...

Replace

Fixtures

local space = box.schema.space.create('example')
space:create_index('primary', {type = 'tree', parts = {1, 'unsigned'}})
space:insert({1, 'foo'})
space:insert({2, 'bar'})

Code

$space = $client->getSpace('example');
$result1 = $space->replace([2, 'BAR']);
$result2 = $space->replace([3, 'BAZ']);

printf("Result 1: %s\n", json_encode($result1));
printf("Result 2: %s\n", json_encode($result2));

Output

Result 1: [[2,"BAR"]]
Result 2: [[3,"BAZ"]]

Space data

tarantool> box.space.example:select()
---
- - [1, 'foo']
  - [2, 'BAR']
  - [3, 'BAZ']
...

Delete

Fixtures

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

Code

$space = $client->getSpace('example');
$result1 = $space->delete([2]);
$result2 = $space->delete(['baz'], 'secondary');

printf("Result 1: %s\n", json_encode($result1));
printf("Result 2: %s\n", json_encode($result2));

Output

Result 1: [[2,"bar"]]
Result 2: [[3,"baz"]]

Space data

tarantool> box.space.example:select()
---
- - [1, 'foo']
  - [4, 'qux']
...

Call

Fixtures

function func_42()
    return 42
end

Code

$result1 = $client->call('func_42');
$result2 = $client->call('math.min', 5, 3, 8);

printf("Result 1: %s\n", json_encode($result1));
printf("Result 2: %s\n", json_encode($result2));

Output

Result 1: [42]
Result 2: [3]

Evaluate

Code

$result1 = $client->evaluate('function func_42() return 42 end');
$result2 = $client->evaluate('return func_42()');
$result3 = $client->evaluate('return math.min(...)', 5, 3, 8);

printf("Result 1: %s\n", json_encode($result1));
printf("Result 2: %s\n", json_encode($result2));
printf("Result 3: %s\n", json_encode($result3));

Output

Result 1: []
Result 2: [42]
Result 3: [3]

SQL protocol

The following are examples of SQL protocol requests. For more detailed information and examples, please see the official documentation. SQL is supported starting with Tarantool 2.0.

Execute

Code

$client->execute('CREATE TABLE users ("id" INTEGER PRIMARY KEY AUTOINCREMENT, "email" VARCHAR(255))');

$result1 = $client->executeUpdate('CREATE UNIQUE INDEX email ON users ("email")');

$result2 = $client->executeUpdate('
    INSERT INTO users VALUES (null, :email1), (null, :email2)
',
    [':email1' => 'foo@example.com'],
    [':email2' => 'bar@example.com']
);

$result3 = $client->executeQuery('SELECT * FROM users WHERE "email" = ?', 'foo@example.com');
$result4 = $client->executeQuery('SELECT * FROM users WHERE "id" IN (?, ?)', 1, 2);

printf("Result 1: %s\n", json_encode([$result1->count(), $result1->getAutoincrementIds()]));
printf("Result 2: %s\n", json_encode([$result2->count(), $result2->getAutoincrementIds()]));
printf("Result 3: %s\n", json_encode([$result3->count(), $result3[0]]));
printf("Result 4: %s\n", json_encode(iterator_to_array($result4)));

Output

Result 1: [1,[]]
Result 2: [2,[1,2]]
Result 3: [1,{"id":1,"email":"foo@example.com"}]
Result 4: [{"id":1,"email":"foo@example.com"},{"id":2,"email":"bar@example.com"}]

If you need to execute a dynamic SQL statement and do not know its type, use the generic execute() method. It returns a Response object whose body contains either an array of result-set rows or an array with information about the changed rows:

$response = $client->execute('<any-type-of-sql-statement>');
$resultSet = $response->tryGetBodyField(Keys::DATA);

if ($resultSet === null) {
    $sqlInfo = $response->getBodyField(Keys::SQL_INFO);
    $affectedCount = $sqlInfo[Keys::SQL_INFO_ROW_COUNT];
}

Prepare

Note that the prepare request is supported only as of Tarantool 2.3.2.

Code

$client->execute('CREATE TABLE users ("id" INTEGER PRIMARY KEY AUTOINCREMENT, "name" VARCHAR(50))');

$stmt = $client->prepare('INSERT INTO users VALUES(null, ?)');
for ($i = 1; $i <= 100; ++$i) {
    $stmt->execute("name_$i");
    // You can also use executeSelect() and executeUpdate(), e.g.:
    // $lastInsertIds = $stmt->executeUpdate("name_$i")->getAutoincrementIds();
}
$stmt->close();

// Note the SEQSCAN keyword in the query. It is available as of Tarantool 2.11.
// If you are using an older version of Tarantool, omit this keyword.
$result = $client->executeQuery('SELECT COUNT("id") AS "cnt" FROM SEQSCAN users');

printf("Result: %s\n", json_encode($result[0]));

Output

Result: {"cnt":100}

User-defined types

To store complex structures inside a tuple you may want to use objects:

$space->insert([42, Money::EUR(500)]);
[[$id, $money]] = $space->select(Criteria::key([42]));

You can do this by extending the MessagePack type system with your own types. Write a MessagePack extension that converts your objects to and from MessagePack structures (see the msgpack.php README for details). Once you have implemented the extension, register it with the packer object:

$packer = PurePacker::fromExtensions(new MoneyExtension());
$client = new Client(new DefaultHandler($connection, $packer));

A working example of using the user-defined types can be found in the examples folder.

Tests

To run unit tests:

vendor/bin/phpunit --testsuite unit

To run integration tests:

vendor/bin/phpunit --testsuite integration

Make sure to start client.lua first.

To run all tests:

vendor/bin/phpunit

If you already have Docker installed, you can run the tests in a Docker container. First, build the Docker image:

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

The command above builds an image named client with the PHP 8.3 runtime. You may change the default runtime by defining the PHP_IMAGE environment variable:

PHP_IMAGE='php:8.2-cli' ./dockerfile.sh | docker build -t client -

See a list of various images here.

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/client.lua:/client.lua \
    tarantool/tarantool:3 tarantool /client.lua

And then run both unit and integration tests:

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

Benchmarks

The benchmarks can be found in the dedicated repository.

License

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

Name		Name	Last commit message	Last commit date
.github		.github
examples		examples
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.php-cs-fixer.dist.php		.php-cs-fixer.dist.php
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
dockerfile.sh		dockerfile.sh
phpunit.xml.dist		phpunit.xml.dist
psalm.xml		psalm.xml

Navigation Menu

Uh oh!

Repository files navigation

PHP client for Tarantool

Features

Table of contents

Installation

Creating a client

DSN string

Array of options

Custom build

Handlers

Middleware

Data manipulation

Binary protocol

SQL protocol

User-defined types

Tests

Benchmarks

License

About

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

PHP client for Tarantool

Features

Table of contents

Installation

Creating a client

DSN string

Array of options

Custom build

Handlers

Middleware

Data manipulation

Binary protocol

SQL protocol

User-defined types

Tests

Benchmarks

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages