predis/doc/client.rst

The `Predis\\Client` class
--------------------------

.. php:namespace:: Predis

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.

.. php:class:: Client

   .. php:method:: __construct($parameters = null, $options = null)

      Creates a new `Client` instance.

      :param $parameters: Connection parameters
      :param $options:    Client options


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

.. _SELECT: http://redis.io/commands/select
.. _AUTH: http://redis.io/commands/auth
.. _Multi-bulk replies: http://redis.io/topics/protocol#multi-bulk-reply
.. _Webdis: http://webd.is/

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();
       },
   ));

.. note::
   When using callables, the configuration of the returned value must be fully
   handled by the user's code since Predis will not attempt to use its standard
   configuration path for that option.

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`_:           true

                - when ``true``, it throws `Predis\\ServerException`.
                - when ``false``, it returns `Predis\\ResponseError`.
--------------  ------------------------------------------------------  ------------------------------------------------
prefix          When set, the passed string is transparently applied    not set
                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`_.
--------------  ------------------------------------------------------  ------------------------------------------------
profile         Changes the Redis version `Client` is expected to       2.6
                connect to, among a list of :doc:`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.

                .. note::
                   In the latter case, Predis will not automatically
                   apply the specified key prefix to the profile so
                   it must be manually set by the user's code.
--------------  ------------------------------------------------------  ------------------------------------------------
connections     Overrides :doc:`connection backends` by scheme using    - tcp: `Predis\\Connection\\StreamConnection`
                a named array, with keys being the connection schemes   - unix: `Predis\\Connection\\StreamConnection`
                subject to change and values being the fully-qualified  - http: `Predis\\Connection\\WebdisConnection`
                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.
--------------  ------------------------------------------------------  ------------------------------------------------
cluster         Changes how `Client` handles :doc:`clustering`:         predis

                - ``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.
--------------  ------------------------------------------------------  ------------------------------------------------
replication     When ``true``, the array of connection parameters is    not set
                used in a master and slaves :doc:`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.
==============  ======================================================  ================================================

.. _error replies: http://redis.io/topics/protocol#status-reply
.. _redis cluster: http://redis.io/topics/cluster-spec
.. _SORT: http://redis.io/commands/eval
.. _EVAL: http://redis.io/commands/eval
.. _EVALSHA: http://redis.io/commands/evalsha