PHP driver for Tarantool 1.6 ============================

PECL PHP driver for Tarantool.

If you're looking for 1.5 version, check out branch 'stable'.

Build

To build Tarantool PHP extenstion PHP-devel package is required. The package should contain phpize utility.

$ phpize
$ ./configure
$ make
$ make install

Test

To run tests Tarantool server and PHP/PECL package are requred.

$ ./test-run.py

It'll automaticly find and start Tarantool and, then, run phpunit.phar based tests. If Tarantool doesn't defined in PATH variable, you may define it in TARANTOOL_BOX_PATH enviroment variable.

$ TARANTOOL_BOX_PATH=/path/to/tarantool/bin/tarantool ./test-run.py

Installing from PEAR

Tarantool-PHP has its own PEAR repository. You may install it from PEAR with just a few commands:

pecl channel-discover tarantool.github.io/tarantool-php/pecl
pecl install Tarantool-PHP/Tarantool-beta

Building RPM/DEB/PECL Packages

For building packages - please, read README.PACK.md

IDE autocompletion

Stubs can be found at tarantool/tarantool-php-stubs. Place it into project library path in your IDE.

API and Configuration

Configuration file

• tarantool.persistent - Enable persistent connections (don't close connections between sessions) (defaults: True, can't be changed in runtime)
• tarantool.timeout - Connection timeout (defaults: 10 seconds, can be changed in runtime)
• tarantool.retry_count - Amount of attempts to connect (defaults: 1, can be changed in runtime)
• tarantool.retry_sleep - Sleep between connecting retries (defaults: 0.1 second, can be changed in runtime)
• tarantool.request_timeout - Read/write timeout for requests (defaults: 10 second, can be changed in runtime)

Classes and Methods

Usage

1. Predefined Constants
2. Class Tarantool

• Tarantool::__construct

3. Manipulation connection

• Tarantool::connect
• Tarantool::disconnect
• Tarantool::flushSchema
• Tarantool::ping

4. Database queries

• Tarantool::select
• Tarantool::insert, replace
• Tarantool::call
• Tarantool::evaluate
• Tarantool::delete
• Tarantool::update
• Tarantool::upsert

Predefined Constants

Description: Available Tarantool Constants

• Tarantool::ITERATOR_EQ - Equality iterator (ALL)
• Tarantool::ITERATOR_REQ - Reverse equality iterator
• Tarantool::ITERATOR_ALL - Get all rows
• Tarantool::ITERATOR_LT - Less then iterator
• Tarantool::ITERATOR_LE - Less and equal iterator
• Tarantool::ITERATOR_GE - Greater and equal iterator
• Tarantool::ITERATOR_GT - Gtreater then iterator
• Tarantool::ITERATOR_BITS_ALL_SET - check if all given bits are set (BITSET only)
• Tarantool::ITERATOR_BITS_ANY_SET - check if any given bits are set (BITSET only)
• Tarantool::ITERATOR_BITS_ALL_NOT_SET - check if all given bits are not set (BITSET only)
• Tarantool::ITERATOR_OVERLAPS - find dots in the n-dimension cube (RTREE only)
• Tarantool::ITERATOR_NEIGHBOR - find nearest dots (RTREE only)

Class Tarantool

Tarantool {
    public       Tarantool::__construct ( [ string $host = 'localhost' [, int $port = 3301 [, string $user = "guest" [, string $password = NULL [, string $persistent_id = NULL ] ] ] ] ] )
    public bool  Tarantool::connect ( void )
    public bool  Tarantool::disconnect ( void )
    public bool  Tarantool::flushSchema ( void )
    public bool  Tarantool::ping ( void )
    public array Tarantool::select (mixed $space [, mixed $key = array() [, mixed $index = 0 [, int $limit = PHP_INT_MAX [, int $offset = 0 [, $iterator = Tarantool::ITERATOR_EQ ] ] ] ] ] )
    public array Tarantool::insert (mixed $space, array $tuple)
    public array Tarantool::replace (mixed $space, array $tuple)
    public array Tarantool::call (string $procedure [, mixed args [, array $opts ] ] )
    public array Tarantool::evaluate (string $expression [, mixed args] )
    public array Tarantool::delete (mixed $space, mixed $key [, mixed $index] )
    public array Tarantool::update (mixed $space, mixed $key, array $ops [, number $index] )
    public array Tarantool::upsert (mixed $space, mixed $key, array $ops [, number $index] )
}

Tarantool::__construct

public Tarantool::__construct ( [ string $host = 'localhost' [, int $port = 3301 [, string $user = "guest" [, string $password = NULL [, string $persistent_id = NULL ] ] ] ] ] )

Description: Creates a Tarantool client

Parameters

• host: string, default is 'localhost'
• port: number, default is 3301
• user: string, default is 'guest'
• password: string
• persistent_id: string (set it, and connection will be persistent, if persistent in config isn't set)

Return Value

Tarantool class instance

Example

$tnt = new Tarantool(); // -> new Tarantool('localhost', 3301);
$tnt = new Tarantool('tarantool.org'); // -> new Tarantool('tarantool.org', 3301);
$tnt = new Tarantool('localhost', 16847);

Manipulation connection

Tarantool::connect

public bool Tarantool::connect ( void )

Description: Explicit connect to Tarantool Server. If not used, then connection will be opened on demand.

Return Value

BOOL: True on success Raises Exception if can't connect to Tarantool.

Tarantool::disconnect

public bool Tarantool::disconnect ( void )

Description: Explicitly close connection to Tarantool Server. If you're using persistent connections, then it'll be saved to connection pool.

Return Value

BOOL: True

Tarantool::flushSchema

public bool Tarantool::flushSchema ( void )

Description: Remove space/index schema from client.

Return Value

BOOL: True

Tarantool::ping

public bool Tarantool::ping ( void )

Description: Ping Tarantool server.

Return Value

BOOL: True

Throws Exception on error.

Database queries

Tarantool::select

public array Tarantool::select(mixed $space [, mixed $key = array() [, mixed $index = 0 [, int $limit = PHP_INT_MAX [, int $offset = 0 [, $iterator = Tarantool::ITERATOR_EQ ] ] ] ] ] )

Description: Execute select query from Tarantool server.

Parameters

• space: String/Number, Space id to select from (mandatory)
• key: String/Number or Array, key to select (Array() by default, selects everything from space)
• index: String/Number, Index id to select from (0 by default)
• limit: Number, limit number of rows to return from select (INT_MAX by default)
• offset: Number, offset to select from (0 by default)
• iterator: Constant, iterator type. See Predefined Constants for more information (Tarantool::ITERATOR_EQ by default). You can also use strings 'eq', 'req', 'all', 'lt', 'le', 'ge', 'gt', 'bits_all_set', 'bits_any_set', 'bits_all_not_set', 'overlaps', 'neighbor', 'bits_all_set', 'bits_any_set', 'bits_all_not_set' (in both lowercase/uppercase) instead of constants

Return Value

Array of arrays: in case of success - list of tuples that satisfy your request, or empty array, if nothing was found.

BOOL: False and raises Exception in case of error.

Example

// Select everything from space 'test'
$tnt->select("test");
// Selects from space 'test' by PK with id == 1
$tnt->select("test", 1);
// The same as previous
$tnt->select("test", array(1));
// Selects from space 'test' by secondary key from index 'isec' and == {1, 'hello'}
$tnt->select("test", array(1, "hello"), "isec");
// Selects second hundred of rows from space test
$tnt->select("test", null, null, 100, 100);
// Selects second hundred of rows from space test in reverse equality order
// It meanse: select penultimate hundred
$tnt->select("test", null, null, 100, 100, Tarantool::ITERATOR_REQ);

Tarantool::insert, Tarantool::replace

public array Tarantool::insert(mixed $space, array $tuple)
public array Tarantool::replace(mixed $space, array $tuple)

Description: Insert (if not exists query with same PK) or Replace tuple.

Parameters

• space: String/Number, Space id to select from (mandatory)
• tuple: Array, Tuple to Insert/Replace (mandatory)

Return Value

Array in case of success - tuple that was inserted into Tarantool.

BOOL: False and raises Exception in case of error.

Example

// It'll be processed OK, since no tuples with PK == 1 are in space 'test'
$tnt->insert("test", array(1, 2, "smth"));
// We've just inserted tuple with PK == 1, so it'll fail
// error will be ER_TUPLE_FOUND
$tnt->insert("test", array(1, 3, "smth completely different"));
// But it won't be a problem for replace
$tnt->replace("test", array(1, 3, "smth completely different"));

Tarantool::call

public array Tarantool::call(string $procedure [, mixed args [, array $opts]])

Description: Call stored procedure

Parameters

• procedure: String, procedure to call (mandatory)
• args: Any value to pass to procedure as arguments (empty by default)
• opts: Array, options

Options

• call_16
  If true - call_16 mode of "call" will be used (returned data converted to tuples).
  If false - call_17 mode of "call" will be used (returned data has an arbitrary structure). Since tarantool 1.7.2.
  Default - call_16 mode.

  array(
    "call_16" => <bool>
  ),
  

Return Value

BOOL: False and raises Exception in case of error.

call_16 mode (default):

Array of arrays in case of success - tuples that were returned by stored procedure.

call_17 mode:

Any value, that was returned by stored procedure.

Example

$tnt->call("test_2");
$tnt->call("test_3", array(3, 4), array('call_16' => false));

Tarantool::evaluate

public array Tarantool::evaluate(string $expression [, mixed args])

Description: Evaluate given lua code (demands current user to have 'execute' rights for 'universe' in Tarantool)

Parameters

• expression: String, Lua code to evaluate (mandatory)
• args: Any value to pass to procedure as arguments (empty by default)

Return Value

Any value, that was returned from evaluated code.

BOOL: False and raises Exception in case of error.

Example

$tnt->eval("return test_2()");
$tnt->eval("return test_3(...)", array(3, 4));
$tnt->evaluate("return test_3(...)", array(3, 4));

Tarantool::delete

public array Tarantool::delete(mixed $space, mixed $key [, mixed $index])

Description: Delete record with given key.

Parameters

• space: String/Number, Space id to delete from (mandatory)
• key: String/Number or Array, key to delete row with (mandatory)
• index: String/Number, Index id to delete from (0 by default)

Return Value

Array in case of success - tuple that was deleted by query.

BOOL: False and raises Exception in case of error.

Example

// Following code will delete all tuples from space `test`
$tuples = $tnt->select("test");
foreach($tuples as $value) {
    $tnt->delete("test", array($value[0]));
}

Tarantool::update

public array Tarantool::update(mixed $space, mixed $key, array $ops [, number $index] )

Description: Update record with given key (update in Tarantool is apply multiple given operations to tuple)

Parameters

• space: String/Number, Space id to select from (mandatory)
• key: Array/Scalar, Key to match tuple with (mandatory)
• ops: Array of Arrays, Operations to execute if tuple was found

Operations

<serializable> - any simple type which converts to MsgPack (scalar/array).

• Splice operation - take field'th field, replace length bytes from offset byte with 'list':

  array(
    "field" => <number>,
    "op"    => ":",
    "offset"=> <number>,
    "length"=> <number>,
    "list"  => <string>
  ),
  

• Numeric operations:

  array(
    "field" => <number>,
    "op" => ("+"|"-"|"&"|"^"|"|"),
    "arg" => <number>
  ),
  

  • "+" for addition
  • "-" for substraction
  • "&" for bitwise AND
  • "^" for bitwise XOR
  • "|" for bitwise OR
• Delete arg fields from 'field':

  array(
    "field" => <number>,
    "op" => "#",
    "arg" => <number>
  )
  

• Replace/Insert before operations:

  array(
    "field" => <number>,
    "op"    => ("="|"!"),
    "arg"   => <serializable>
  )
  

  • "=" replace field'th field with 'arg'
  • "=" insert 'arg' before field'th field

array(
  array(
    "field" => <number>,
    "op"    => ":",
    "offset"=> <number>,
    "length"=> <number>,
    "list"  => <string>
  ),
  array(
    "field" => <number>,
    "op" => ("+"|"-"|"&"|"^"|"|"),
    "arg" => <number>
  ),
  array(
    "field" => <number>,
    "op" => "#",
    "arg" => <number>
  ),
  array(
    "field" => <number>,
    "op"    => ("="|"!"),
    "arg"   => <serializable>
  )
)

Return Value

Array in case of success - tuple after it was updated.

BOOL: False and raises Exception in case of error.

Example

$tnt->update("test", 1, array(
  array(
    "field" => 1,
    "op" => "+",
    "arg" => 16
  ),
  array(
    "field" => 3,
    "op" => "=",
    "arg" => 98
  ),
  array(
    "field" => 4,
    "op" => "=",
    "arg" => 0x11111,
  ),
));
$tnt->update("test", 1, array(
  array(
    "field" => 3,
    "op" => "-",
    "arg" => 10
  ),
  array(
    "field" => 4,
    "op" => "&",
    "arg" => 0x10101,
  )
));
$tnt->update("test", 1, array(
  array(
    "field" => 4,
    "op" => "^",
    "arg" => 0x11100,
  )
));
$tnt->update("test", 1, array(
  array(
    "field" => 4,
    "op" => "|",
    "arg" => 0x00010,
  )
));
$tnt->update("test", 1, array(
  array(
    "field" => 2,
    "op" => ":",
    "offset" => 2,
    "length" => 2,
    "list" => "rrance and phillipe show"
  )
));

Tarantool::upsert

public array Tarantool::upsert(mixed $space, array $tuple, array $ops [, number $index] )

Description: Update or Insert command (If tuple with PK == PK('tuple') exists, then it'll update this tuple with 'ops', otherwise 'tuple' will be inserted)

Parameters

• space: String/Number, Space id to select from (mandatory)
• tuple: Array, Tuple to Insert (mandatory)
• ops: Array of Arrays, Operations to execute if tuple was found. Operations are described in update section.

Return Value

Nothing. In simple cases - it mustn't throw errors and returns nothing, but sometimes it'll, check out documentation

BOOL: False and raises Exception in case of error.

Example

$tnt->upsert("test", array(124, 10, "new tuple"), array(
  array(
    "field" => 1,
    "op" => "+",
    "arg" => 10
  )
));

Deprecated

• Global constants, e.g. TARANTOOL_ITER_<name>
• Tarantool::authenticate method
• configuration parameter: tarantool.con_per_host