Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

[doc] Describe available client options. #97

Merged
merged 3 commits into from

1 participant

@nrk
Owner

It took me a while to find a decent and concise form to describe each client option since they are inherently more complex than connection parameters due to the multitude of different values they accept, but I think (hope?) I finally reached an acceptable result.

Since most client options are strictly related to macro-arguments that will be covered through the rest of the documentation (e.g. clustering, replication, etc), I placed various cross references to other documents. Each specific document should include a section about its corresponding client option with a more extensive description focusing on some configuration scenarios or possible side effects.

Thoughts?

added some commits
@nrk [doc] Describe available client options. 36671ad
@nrk [doc] Fix code snippet used for client options. e4295ad
@nrk [doc] Add note about client options values returned by callables.
Predis will not attempt to use its standard configuration path for
options when using callables as initializers, this makes sense and
it is an intended behavior to give users more flexibility over the
configuration of the client but it can be confusing and unexpected
in certain cases such as with the combination of server profile and
key prefix.
5034bb9
@nrk nrk merged commit d16bc2d into documentation
@nrk nrk deleted the doc-client-options branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Dec 18, 2012
Commits on Dec 19, 2012
Commits on Jan 12, 2013
  1. [doc] Add note about client options values returned by callables.

    authored
    Predis will not attempt to use its standard configuration path for
    options when using callables as initializers, this makes sense and
    it is an intended behavior to give users more flexibility over the
    configuration of the client but it can be confusing and unexpected
    in certain cases such as with the combination of server profile and
    key prefix.
This page is out of date. Refresh to see the latest.
Showing with 129 additions and 0 deletions.
  1. +129 −0 doc/client.rst
View
129 doc/client.rst
@@ -112,7 +112,136 @@ pass Password for HTTP authentication (`Webdis`_). not set `P
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
Something went wrong with that request. Please try again.