client.rst

The Predis\Client class

The Client class is the main class users interact with in Predis. The first thing you'll do to start communicating with Redis is instantiate a Client.

Constructing a Client

The Client constructor takes two arguments. The first ($parameters) is a set of information about the Redis connection you'd like to make. The second ($options) is a set of options to configure the client.

Connection Parameters

These parameters are used to control the behaviour of the underlying connection to Redis. They can be specified using a URI string:

$client = new Predis\Client('tcp://127.0.0.1:6379?database=2')

Or, using an associative array:

$client = new Predis\Client(array(
    'scheme'   => 'tcp',
    'host'     => '127.0.0.1',
    'port'     => 6379,
    'database' => 3
));

By default, Predis supports a lengthy list of connection parameters.

Note

Since the client can use different connection backends, actual support for certain parameters depends on the value of scheme and the connection backends registered using the connections client option.

parameter	description	default	supported by
scheme	Instructs the client how to connect to Redis. Supported values are: tcp, unix, http. Certain values such as http change the underlying connection backend.	tcp	Predis\Connection\StreamConnection Predis\Connection\PhpiredisConnection Predis\Connection\WebdisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
host	IP address or hostname of the server. Ignored when using the unix scheme.	127.0.0.1	Predis\Connection\StreamConnection Predis\Connection\PhpiredisConnection Predis\Connection\WebdisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
port	TCP port the server listens on. Ignored when using the unix scheme.	6379	Predis\Connection\StreamConnection Predis\Connection\PhpiredisConnection Predis\Connection\WebdisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
path	Path of the UNIX domain socket the server is listening on, used only in combination with the unix scheme. Example: /tmp/redis.sock.	not set	Predis\Connection\StreamConnection Predis\Connection\PhpiredisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
database	Redis database to select when connecting. Its effect is the same of using SELECT.	not set	Predis\Connection\StreamConnection Predis\Connection\PhpiredisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
timeout	Timeout to perform the connection to Redis. Its value is expressed in seconds as a float allowing sub-second resolution.	5.0	Predis\Connection\StreamConnection Predis\Connection\PhpiredisConnection Predis\Connection\WebdisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
read_write_timeout	Timeout for read and write operations. Its value is expressed in seconds as a float allowing sub-second resolution.	platform dependent	Predis\Connection\StreamConnection Predis\Connection\PhpiredisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
async_connect	Tells the client to perform the connection asynchronously without waiting for it to be fully estabilished.	not set (false)	Predis\Connection\StreamConnection
------------------	---------------------------------------------	---------	-----------------------------------------
persistent	The underlying socket is left intact after a GC collection or when the script terminates (only when using FastCGI or php-fpm).	not set (false)	Predis\Connection\StreamConnection
------------------	---------------------------------------------	---------	-----------------------------------------
iterable_multibulk	Multi-bulk replies are returned as PHP iterable objects, making them streamable.	false	Predis\Connection\StreamConnection
------------------	---------------------------------------------	---------	-----------------------------------------
alias	String used to identify a connection by name. This is useful with clustering and replication.	not set	Backend independent.
------------------	---------------------------------------------	---------	-----------------------------------------
weight	This is only used with clustering and determines the proportion of the load the corresponding server will bear relative to other nodes in the cluster.	not set	Backend independent.
------------------	---------------------------------------------	---------	-----------------------------------------
user	Username for HTTP authentication (Webdis).	not set	Predis\Connection\WebdisConnection
------------------	---------------------------------------------	---------	-----------------------------------------
pass	Password for HTTP authentication (Webdis).	not set	Predis\Connection\WebdisConnection

Users can also specify their own parameters, they will simply be ignored by the client but can be used later to pass additional information for custom purposes.

Client Options

Several behaviours of Client can be controlled via client options with values that vary depending on the nature of each option: some of them accept primitive types while others can also take instances of classes implementing some specific interfaces defined by Predis, which can be useful to completely override the standard ones used by `Client`:

$client = new Predis\Client($parameters, array(
    'prefix'      => 'predis:'
    'profile'     => '2.6',
    'connections' => array(
        'tcp'  => 'Predis\Connection\PhpiredisConnection',
        'unix' => 'Predis\Connection\PhpiredisConnection',
    ),
));

To achieve an even higher level of customizability, certain options also accept callables acting as initializers that can be leveraged to gain full control over the initialization of option values (e.g. instances of classes) before returning them to `Client`:

$client = new Predis\Client('tcp://127.0.0.1', array(
    'prefix'  => 'predis:',
    'profile' => function ($options, $option) {
        // Callable initializers have access to the whole set of options
        // (1st argument) and to the current option instance (2nd argument).

        return new Predis\Profile\ServerVersion26();
    },
));

Users can also specify their own custom options to pass additional information. Just like standard options, they are accessible from callable initializers:

$client = new Predis\Client('tcp://127.0.0.1', array(
     // 'commands' is a custom option, actually unknown to Predis.
    'commands' => array(
        'set' => Predis\Command\StringSet,
        'get' => Predis\Command\StringGet,
    ),
    'profile'     => function ($options, $option) {
        $profile = $option->getDefault($options);

        if (is_array($options->commands)) {
            foreach ($options->commands as $command => $class) {
                $profile->defineCommand($command, $class);
            }
        }

        return $profile
    },
));

This is the full list of client options supported by `Client`:

option	description	default
exceptions	Changes how Client treats error replies: when true, it throws Predis\ServerException. when false, it returns Predis\ResponseError.	true
--------------	------------------------------------------------------	------------------------------------------------
prefix	When set, the passed string is transparently applied as a prefix to each key present in command arguments. Note Keys are prefixed using rules defined by each command in order to be able to support even complex cases such as SORT, EVAL and EVALSHA.	not set
--------------	------------------------------------------------------	------------------------------------------------
profile	Changes the Redis version Client is expected to connect to, among a list of server profiles predefined by Predis. Supported versions are: 1.2, 2.0, 2.2, 2.4, 2.6, dev (unstable branch in the Redis repository). This option accepts also the fully-qualified name of a Predis\Profile\ServerProfileInterface or its instance passed either directly or returned by a callable initializer.	2.6
--------------	------------------------------------------------------	------------------------------------------------
connections	Overrides connection backends by scheme using a named array, with keys being the connection schemes subject to change and values being the fully-qualified name of classes implementing Predis\Connection\SingleConnectionInterface. This option accepts also the fully-qualified name of a Predis\Connection\ConnectionFactoryInterface or its instance passed either directly or returned by a callable initializer.	tcp: Predis\Connection\StreamConnection unix: Predis\Connection\StreamConnection http: Predis\Connection\WebdisConnection
--------------	------------------------------------------------------	------------------------------------------------
cluster	Changes how Client handles clustering: predis indicates the use of client-side sharding. redis indicates the use redis cluster. This option accepts also the fully-qualified name of a Predis\Connection\ClusterConnectionInterface or its instance passed either directly or returned by a callable initializer.	predis
--------------	------------------------------------------------------	------------------------------------------------
replication	When true, the array of connection parameters is used in a master and slaves replication setup instead of treating the servers as a cluster of nodes. This option accepts also the fully-qualified name of a Predis\Connection\ReplicationConnectionInterface or its instance passed either directly or returned by a callable initializer.	not set