search

tarantool / tarantool-php

PECL PHP driver for Tarantool
http://tarantool.org/
Other
86 stars 24 forks source link
driver php tarantool

readme

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

Classes and Methods

Usage

  1. Predefined Constants
  2. Class Tarantool
  3. Manipulation connection
  4. Database queries

Predefined Constants

Description: Available Tarantool Constants

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

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

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

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

Options

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

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

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

Operations

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

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

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