1<a href="http://tarantool.org"> 2 <img src="https://avatars2.githubusercontent.com/u/2344919?v=2&s=250" align="right"> 3</a> 4<a href="https://travis-ci.org/tarantool/tarantool-php"> 5 <img src="https://travis-ci.org/tarantool/tarantool-php.png?branch=master" align="right"> 6</a> 7PHP driver for Tarantool 1.6 8============================ 9 10PECL PHP driver for Tarantool. 11 12If you're looking for 1.5 version, check out branch 'stable'. 13 14 15## Build 16 17To build Tarantool PHP extenstion PHP-devel package is required. The 18package should contain phpize utility. 19 20```sh 21$ phpize 22$ ./configure 23$ make 24$ make install 25``` 26 27## Test 28 29To run tests Tarantool server and PHP/PECL package are requred. 30 31```sh 32$ ./test-run.py 33``` 34 35It'll automaticly find and start Tarantool and, then, run `phpunit.phar` based tests. 36If Tarantool doesn't defined in `PATH` variable, you may define it in `TARANTOOL_BOX_PATH` enviroment variable. 37 38```sh 39$ TARANTOOL_BOX_PATH=/path/to/tarantool/bin/tarantool ./test-run.py 40``` 41 42 43## Installing from PEAR 44 45Tarantool-PHP has its own [PEAR repository](https://tarantool.github.io/tarantool-php). 46You may install it from PEAR with just a few commands: 47 48``` 49pecl channel-discover tarantool.github.io/tarantool-php/pecl 50pecl install Tarantool-PHP/Tarantool-beta 51``` 52 53 54## Building RPM/DEB/PECL Packages 55 56For building packages - please, read `README.PACK.md` 57 58 59## IDE autocompletion 60 61Stubs can be found at [tarantool/tarantool-php-stubs](https://github.com/tarantool/tarantool-php-stubs). 62Place it into project library path in your IDE. 63 64# API and Configuration 65 66## Configuration file 67 68* `tarantool.persistent` - Enable persistent connections (don't close connections between sessions) (defaults: True, **can't be changed in runtime**) 69* `tarantool.timeout` - Connection timeout (defaults: 10 seconds, can be changed in runtime) 70* `tarantool.retry_count` - Count of retries for connecting (defaults: 1, can be changed in runtime) 71* `tarantool.retry_sleep` - Sleep between connecting retries (defaults: 0.1 second, can be changed in runtime) 72* `tarantool.request_timeout` - Read/write timeout for requests (defaults: 10 second, can be changed in runtime) 73 74# Classes and Methods 75 76## Usage 77 781. [Predefined Constants](#predefined-constants) 792. [Class Tarantool](#class-tarantool) 80 * [Tarantool::__construct](#tarantool__construct) 813. [Manipulation connection](#manipulation-connection) 82 * [Tarantool::connect](#tarantoolconnect) 83 * [Tarantool::disconnect](#tarantooldisconnect) 84 * [Tarantool::flushSchema](#tarantoolflushschema) 85 * [Tarantool::ping](#tarantoolping) 864. [Database queries](#database-queries) 87 * [Tarantool::select](tarantool#select) 88 * [Tarantool::insert, replace](#tarantoolinsert-tarantoolreplace) 89 * [Tarantool::call](#tarantoolcall) 90 * [Tarantool::evaluate](#tarantoolevaluate) 91 * [Tarantool::delete](#tarantooldelete) 92 * [Tarantool::update](#tarantoolupdate) 93 * [Tarantool::upsert](#tarantoolupsert) 94 95### Predefined Constants 96 97_**Description**_: Available Tarantool Constants 98 99* `Tarantool::ITERATOR_EQ` - Equality iterator (ALL) 100* `Tarantool::ITERATOR_REQ` - Reverse equality iterator 101* `Tarantool::ITERATOR_ALL` - Get all rows 102* `Tarantool::ITERATOR_LT` - Less then iterator 103* `Tarantool::ITERATOR_LE` - Less and equal iterator 104* `Tarantool::ITERATOR_GE` - Greater and equal iterator 105* `Tarantool::ITERATOR_GT` - Gtreater then iterator 106* `Tarantool::ITERATOR_BITS_ALL_SET` - check if all given bits are set (BITSET only) 107* `Tarantool::ITERATOR_BITS_ANY_SET` - check if any given bits are set (BITSET only) 108* `Tarantool::ITERATOR_BITS_ALL_NOT_SET` - check if all given bits are not set 109 (BITSET only) 110* `Tarantool::ITERATOR_OVERLAPS` - find dots in the n-dimension cube (RTREE only) 111* `Tarantool::ITERATOR_NEIGHBOR` - find nearest dots (RTREE only) 112 113### Class Tarantool 114 115``` php 116Tarantool { 117 public Tarantool::__construct ( [ string $host = 'localhost' [, int $port = 3301 [, string $user = "guest" [, string $password = NULL [, string $persistent_id = NULL ] ] ] ] ] ) 118 public bool Tarantool::connect ( void ) 119 public bool Tarantool::disconnect ( void ) 120 public bool Tarantool::flushSchema ( void ) 121 public bool Tarantool::ping ( void ) 122 public array Tarantool::select (mixed $space [, mixed $key = array() [, mixed $index = 0 [, int $limit = PHP_INT_MAX [, int $offset = 0 [, $iterator = Tarantool::ITERATOR_EQ ] ] ] ] ] ) 123 public array Tarantool::insert (mixed $space, array $tuple) 124 public array Tarantool::replace (mixed $space, array $tuple) 125 public array Tarantool::call (string $procedure [, mixed args] ) 126 public array Tarantool::evaluate (string $expression [, mixed args] ) 127 public array Tarantool::delete (mixed $space, mixed $key [, mixed $index] ) 128 public array Tarantool::update (mixed $space, mixed $key, array $ops [, number $index] ) 129 public array Tarantool::upsert (mixed $space, mixed $key, array $ops [, number $index] ) 130} 131``` 132 133#### Tarantool::__construct 134 135``` 136public Tarantool::__construct ( [ string $host = 'localhost' [, int $port = 3301 [, string $user = "guest" [, string $password = NULL [, string $persistent_id = NULL ] ] ] ] ] ) 137``` 138 139_**Description**_: Creates a Tarantool client 140 141_**Parameters**_ 142 143* `host`: string, default is `'localhost'` 144* `port`: number, default is `3301` 145* `user`: string, default is `'guest'` 146* `password`: string 147* `persistent_id`: string (set it, and connection will be persistent, if 148 `persistent` in config isn't set) 149 150_**Return Value**_ 151 152Tarantool class instance 153 154##### *Example* 155 156``` php 157$tnt = new Tarantool(); // -> new Tarantool('localhost', 3301); 158$tnt = new Tarantool('tarantool.org'); // -> new Tarantool('tarantool.org', 3301); 159$tnt = new Tarantool('localhost', 16847); 160``` 161 162## Manipulation connection 163 164### Tarantool::connect 165 166``` php 167public bool Tarantool::connect ( void ) 168``` 169 170_**Description**_: Explicit connect to Tarantool Server. If not used, then connection 171will be opened on demand. 172 173_**Return Value**_ 174 175**BOOL**: True on success 176Raises `Exception` if can't connect to Tarantool. 177 178### Tarantool::disconnect 179 180``` php 181public bool Tarantool::disconnect ( void ) 182``` 183 184_**Description**_: Explicitly close connection to Tarantool Server. If you're 185using persistent connections, then it'll be saved to connection pool. 186 187_**Return Value**_ 188 189**BOOL**: True 190 191### Tarantool::flushSchema 192 193``` php 194public bool Tarantool::flushSchema ( void ) 195``` 196 197_**Description**_: Remove space/index schema from client. 198 199_**Return Value**_ 200 201**BOOL**: True 202 203### Tarantool::ping 204 205``` php 206public bool Tarantool::ping ( void ) 207``` 208 209_**Description**_: Ping Tarantool server. 210 211_**Return Value**_ 212 213**BOOL**: True 214 215Throws `Exception` on error. 216 217## Database queries 218 219### Tarantool::select 220 221``` php 222public array Tarantool::select(mixed $space [, mixed $key = array() [, mixed $index = 0 [, int $limit = PHP_INT_MAX [, int $offset = 0 [, $iterator = Tarantool::ITERATOR_EQ ] ] ] ] ] ) 223``` 224 225_**Description**_: Execute select query from Tarantool server. 226 227_**Parameters**_ 228 229* `space`: String/Number, Space id to select from (mandatory) 230* `key`: String/Number or Array, key to select (`Array()` by default, selects 231 everything from space) 232* `index`: String/Number, Index id to select from (0 by default) 233* `limit`: Number, limit number of rows to return from select (INT_MAX by default) 234* `offset`: Number, offset to select from (0 by default) 235* `iterator`: Constant, iterator type. See [Predefined Constants](#predefined-constants) 236 for more information (`Tarantool::ITERATOR_EQ` by default). You can also use 237 strings `'eq'`, `'req'`, `'all'`, `'lt'`, `'le'`, `'ge'`, `'gt'`, 238 `'bits_all_set'`, `'bits_any_set'`, `'bits_all_not_set'`, `'overlaps'`, 239 `'neighbor'`, `'bits_all_set'`, `'bits_any_set'`, `'bits_all_not_set'` (in 240 both lowercase/uppercase) instead of constants 241 242_**Return Value**_ 243 244**Array of arrays**: in case of success - list of tuples that satisfy your 245request, or empty array, if nothing was found. 246 247**BOOL**: False and raises `Exception` in case of error. 248 249#### Example 250 251``` php 252// Select everything from space 'test' 253$tnt->select("test"); 254// Selects from space 'test' by PK with id == 1 255$tnt->select("test", 1); 256// The same as previous 257$tnt->select("test", array(1)); 258// Selects from space 'test' by secondary key from index 'isec' and == {1, 'hello'} 259$tnt->select("test", array(1, "hello"), "isec"); 260// Selects second hundred of rows from space test 261$tnt->select("test", null, null, 100, 100); 262// Selects second hundred of rows from space test in reverse equality order 263// It meanse: select penultimate hundred 264$tnt->select("test", null, null, 100, 100, Tarantool::ITERATOR_REQ); 265``` 266 267### Tarantool::insert, Tarantool::replace 268 269``` php 270public array Tarantool::insert(mixed $space, array $tuple) 271public array Tarantool::replace(mixed $space, array $tuple) 272``` 273 274_**Description**_: Insert (if not exists query with same PK) or Replace tuple. 275 276_**Parameters**_ 277 278* `space`: String/Number, Space id to select from (mandatory) 279* `tuple`: Array, Tuple to Insert/Replace (mandatory) 280 281_**Return Value**_ 282 283**Array** in case of success - tuple that was inserted into Tarantool. 284 285**BOOL**: False and raises `Exception` in case of error. 286 287#### Example 288 289``` php 290// It'll be processed OK, since no tuples with PK == 1 are in space 'test' 291$tnt->insert("test", array(1, 2, "smth")); 292// We've just inserted tuple with PK == 1, so it'll fail 293// error will be ER_TUPLE_FOUND 294$tnt->insert("test", array(1, 3, "smth completely different")); 295// But it won't be a problem for replace 296$tnt->replace("test", array(1, 3, "smth completely different")); 297``` 298 299### Tarantool::call 300 301``` php 302public array Tarantool::call(string $procedure [, mixed args]) 303``` 304 305_**Description**_: Call stored procedure 306 307_**Parameters**_ 308* `procedure`: String, procedure to call (mandatory) 309* `args`: Any value to pass to procdure as arguments (empty by default) 310 311_**Return Value**_ 312 313**Array of arrays** in case of success - tuples that were returned by stored 314 procedure. 315 316**BOOL**: False and raises `Exception` in case of error. 317 318#### Example 319 320``` php 321$tnt->call("test_2"); 322$tnt->call("test_3", array(3, 4)); 323``` 324 325### Tarantool::evaluate 326 327``` php 328public array Tarantool::evaluate(string $expression [, mixed args]) 329``` 330 331_**Description**_: Evaluate given lua code (demands current user to have 332`'execute'` rights for `'universe'` in Tarantool) 333 334_**Parameters**_ 335* `expression`: String, Lua code to evaluate (mandatory) 336* `args`: Any value to pass to procdure as arguments (empty by default) 337 338_**Return Value**_ 339 340**Any value**, that was returned from evaluated code. 341 342**BOOL**: False and raises `Exception` in case of error. 343 344#### Example 345 346``` php 347$tnt->eval("return test_2()"); 348$tnt->eval("return test_3(...)", array(3, 4)); 349$tnt->evaluate("return test_3(...)", array(3, 4)); 350``` 351 352### Tarantool::delete 353 354``` php 355public array Tarantool::delete(mixed $space, mixed $key [, mixed $index]) 356``` 357 358_**Description**_: Delete record with given key. 359 360_**Parameters**_ 361* `space`: String/Number, Space id to delete from (mandatory) 362* `key`: String/Number or Array, key to delete row with (mandatory) 363* `index`: String/Number, Index id to delete from (0 by default) 364 365_**Return Value**_ 366 367**Array** in case of success - tuple that was deleted by query. 368 369**BOOL**: False and raises `Exception` in case of error. 370 371#### Example 372 373``` php 374// Following code will delete all tuples from space `test` 375$tuples = $tnt->select("test"); 376foreach($tuples as $value) { 377 $tnt->delete("test", array($value[0])); 378} 379``` 380 381### Tarantool::update 382 383``` php 384public array Tarantool::update(mixed $space, mixed $key, array $ops [, number $index] ) 385``` 386 387_**Description**_: Update record with given key (update in Tarantool is 388apply multiple given operations to tuple) 389 390_**Parameters**_ 391 392* `space`: String/Number, Space id to select from (mandatory) 393* `key`: Array/Scalar, Key to match tuple with (mandatory) 394* `ops`: Array of Arrays, Operations to execute if tuple was found 395 396_**Operations**_ 397 398`<serializable>` - any simple type which converts to MsgPack (scalar/array). 399 400* Splice operation - take `field`'th field, replace `length` bytes from `offset` 401 byte with 'list': 402 ``` 403 array( 404 "field" => <number>, 405 "op" => ":", 406 "offset"=> <number>, 407 "length"=> <number>, 408 "list" => <string> 409 ), 410 ``` 411* Numeric operations: 412 ``` 413 array( 414 "field" => <number>, 415 "op" => ("+"|"-"|"&"|"^"|"|"), 416 "arg" => <number> 417 ), 418 ``` 419 - "+" for addition 420 - "-" for substraction 421 - "&" for bitwise AND 422 - "^" for bitwise XOR 423 - "|" for bitwise OR 424* Delete `arg` fields from 'field': 425 ``` 426 array( 427 "field" => <number>, 428 "op" => "#", 429 "arg" => <number> 430 ) 431 ``` 432* Replace/Insert before operations: 433 ``` 434 array( 435 "field" => <number>, 436 "op" => ("="|"!"), 437 "arg" => <serializable> 438 ) 439 ``` 440 - "=" replace `field`'th field with 'arg' 441 - "=" insert 'arg' before `field`'th field 442 443``` 444array( 445 array( 446 "field" => <number>, 447 "op" => ":", 448 "offset"=> <number>, 449 "length"=> <number>, 450 "list" => <string> 451 ), 452 array( 453 "field" => <number>, 454 "op" => ("+"|"-"|"&"|"^"|"|"), 455 "arg" => <number> 456 ), 457 array( 458 "field" => <number>, 459 "op" => "#", 460 "arg" => <number> 461 ), 462 array( 463 "field" => <number>, 464 "op" => ("="|"!"), 465 "arg" => <serializable> 466 ) 467) 468``` 469 470 471_**Return Value**_ 472 473**Array** in case of success - tuple after it was updated. 474 475**BOOL**: False and raises `Exception` in case of error. 476 477#### Example 478 479``` php 480$tnt->update("test", 1, array( 481 array( 482 "field" => 1, 483 "op" => "+", 484 "arg" => 16 485 ), 486 array( 487 "field" => 3, 488 "op" => "=", 489 "arg" => 98 490 ), 491 array( 492 "field" => 4, 493 "op" => "=", 494 "arg" => 0x11111, 495 ), 496)); 497$tnt->update("test", 1, array( 498 array( 499 "field" => 3, 500 "op" => "-", 501 "arg" => 10 502 ), 503 array( 504 "field" => 4, 505 "op" => "&", 506 "arg" => 0x10101, 507 ) 508)); 509$tnt->update("test", 1, array( 510 array( 511 "field" => 4, 512 "op" => "^", 513 "arg" => 0x11100, 514 ) 515)); 516$tnt->update("test", 1, array( 517 array( 518 "field" => 4, 519 "op" => "|", 520 "arg" => 0x00010, 521 ) 522)); 523$tnt->update("test", 1, array( 524 array( 525 "field" => 2, 526 "op" => ":", 527 "offset" => 2, 528 "length" => 2, 529 "list" => "rrance and phillipe show" 530 ) 531)); 532``` 533 534### Tarantool::upsert 535 536``` php 537public array Tarantool::upsert(mixed $space, array $tuple, array $ops [, number $index] ) 538``` 539 540_**Description**_: Update or Insert command (If tuple with PK == PK('tuple') exists, 541then it'll update this tuple with 'ops', otherwise 'tuple' will be inserted) 542 543_**Parameters**_ 544 545* `space`: String/Number, Space id to select from (mandatory) 546* `tuple`: Array, Tuple to Insert (mandatory) 547* `ops`: Array of Arrays, Operations to execute if tuple was found. Operations 548 are described in update section. 549 550_**Return Value**_ 551 552Nothing. In simple cases - it mustn't throw errors and returns nothing, but 553sometimes it'll, check out [documentation](http://tarantool.org/doc/book/box/box_space.html?highlight=upsert#lua-function.space_object.upsert) 554 555**BOOL**: False and raises `Exception` in case of error. 556 557#### Example 558 559``` php 560$tnt->upsert("test", array(124, 10, "new tuple"), array( 561 array( 562 "field" => 1, 563 "op" => "+", 564 "arg" => 10 565 ) 566)); 567``` 568 569 570## Deprecated 571 572* Global constants, e.g. `TARANTOOL_ITER_<name>` 573* `Tarantool::authenticate` method 574* configuration parameter: `tarantool.con_per_host` 575
