Download the PHP package tarantool/client without Composer
On this page you can find all versions of the php package tarantool/client. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package client
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:
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:
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:
Some examples:
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:
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:
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:
The library ships with two handlers:
DefaultHandleris used for handling low-level communication with a Tarantool serverMiddlewareHandleris 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:
You may also assign multiple middleware to the client (they will be executed in FIFO order):
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:
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
$client3behaves like$client2in this case. This is because specifying some options (via array or DSN string) may implicitly register middleware. Thus, theusername/passwordoptions will be turned intoAuthenticationMiddlewareunder the hood, making the two configurations identical.
To make sure your middleware runs first, use the withPrependedMiddleware() method:
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* *Code* *Output*
Insert
*Fixtures* *Code* *Output* *Space data*
Update
*Fixtures* *Code* *Output* *Space data*
Upsert
*Fixtures* *Code* *Space data*
Replace
*Fixtures* *Code* *Output* *Space data*
Delete
*Fixtures* *Code* *Output* *Space data*
Call
*Fixtures* *Code* *Output*
Evaluate
*Code* *Output*
SQL protocol
The following are examples of SQL protocol requests. For more detailed information and examples please see the official documentation. Note that SQL is supported only as of Tarantool 2.0.
Execute
*Code* *Output* If you need to execute a dynamic SQL statement whose type you don't know, you can use the generic method `execute()`. This method returns a Response object with the body containing either an array of result set rows or an array with information about the changed rows:
Prepare
*Note that the `prepare` request is supported only as of Tarantool 2.3.2.* *Code* *Output*
User-defined types
To store complex structures inside a tuple you may want to use objects:
This can be achieved by extending the MessagePack type system with your own types. To do this, you need to write a MessagePack extension that converts your objects into MessagePack structures and back (for more details, read the msgpack.php's README). Once you have implemented your extension, you should register it with the packer object:
A working example of using the user-defined types can be found in the examples folder.
Tests
To run unit tests:
To run integration tests:
Make sure to start client.lua first.
To run all tests:
If you already have Docker installed, you can run the tests in a docker container. First, create a container:
The command above will create a container named client with PHP 8.2 runtime.
You may change the default runtime by defining the PHP_IMAGE environment variable:
See a list of various images here.
Then run a Tarantool instance (needed for integration tests):
And then run both unit and integration tests:
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.
