diff --git a/components/cache/adapters/redis_adapter.rst b/components/cache/adapters/redis_adapter.rst index 0845b3bcb96..8e6436fcd0c 100644 --- a/components/cache/adapters/redis_adapter.rst +++ b/components/cache/adapters/redis_adapter.rst @@ -67,12 +67,18 @@ replaced by ``rediss`` (the second ``s`` means "secure"). .. note:: - A `Data Source Name (DSN)`_ for this adapter must use the following format. + A `Data Source Name (DSN)`_ for this adapter must use either one of the following formats. .. code-block:: text redis[s]://[pass@][ip|host|socket[:port]][/db-index] + .. code-block:: text + + redis[s]:[[user]:pass@]?[ip|host|socket[:port]][¶ms] + + Values for placeholders ``[user]``, ``[:port]``, ``[/db-index]`` and ``[¶ms]`` are optional. + Below are common examples of valid DSNs showing a combination of available values:: use Symfony\Component\Cache\Adapter\RedisAdapter; @@ -89,20 +95,35 @@ Below are common examples of valid DSNs showing a combination of available value // socket "/var/run/redis.sock" and auth "bad-pass" RedisAdapter::createConnection('redis://bad-pass@/var/run/redis.sock'); - // a single DSN can define multiple servers using the following syntax: - // host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':' + // host "redis1" (docker container) with alternate DSN syntax and selecting database index "3" + RedisAdapter::createConnection('redis:?host[redis1:6379]&dbindex=3'); + + // providing credentials with alternate DSN syntax + RedisAdapter::createConnection('redis:default:verysecurepassword@?host[redis1:6379]&dbindex=3'); + + // a single DSN can also define multiple servers RedisAdapter::createConnection( 'redis:?host[localhost]&host[localhost:6379]&host[/var/run/redis.sock:]&auth=my-password&redis_cluster=1' ); `Redis Sentinel`_, which provides high availability for Redis, is also supported -when using the Predis library. Use the ``redis_sentinel`` parameter to set the -name of your service group:: +when using the PHP Redis Extension v5.2+ or the Predis library. Use the ``redis_sentinel`` +parameter to set the name of your service group:: RedisAdapter::createConnection( 'redis:?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster' ); + // providing credentials + RedisAdapter::createConnection( + 'redis:default:verysecurepassword@?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster' + ); + + // providing credentials and selecting database index "3" + RedisAdapter::createConnection( + 'redis:default:verysecurepassword@?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster&dbindex=3' + ); + .. versionadded:: 4.2 The option to define multiple servers in a single DSN was introduced in Symfony 4.2. @@ -132,13 +153,19 @@ array of ``key => value`` pairs representing option names and their respective v // associative array of configuration options [ - 'lazy' => false, + 'class' => null, 'persistent' => 0, 'persistent_id' => null, - 'tcp_keepalive' => 0, 'timeout' => 30, 'read_timeout' => 0, 'retry_interval' => 0, + 'tcp_keepalive' => 0, + 'lazy' => null, + 'redis_cluster' => false, + 'redis_sentinel' => null, + 'dbindex' => 0, + 'failover' => 'none', + 'ssl' => null, ] ); @@ -146,15 +173,11 @@ array of ``key => value`` pairs representing option names and their respective v Available Options ~~~~~~~~~~~~~~~~~ -``class`` (type: ``string``) +``class`` (type: ``string``, default: ``null``) Specifies the connection library to return, either ``\Redis`` or ``\Predis\Client``. If none is specified, it will return ``\Redis`` if the ``redis`` extension is - available, and ``\Predis\Client`` otherwise. - -``lazy`` (type: ``bool``, default: ``false``) - Enables or disables lazy connections to the backend. It's ``false`` by - default when using this as a stand-alone component and ``true`` by default - when using it inside a Symfony application. + available, and ``\Predis\Client`` otherwise. Explicitly set this to ``\Predis\Client`` for Sentinel if you are + running into issues when retrieving master information. ``persistent`` (type: ``int``, default: ``0``) Enables or disables use of persistent connections. A value of ``0`` disables persistent @@ -163,6 +186,10 @@ Available Options ``persistent_id`` (type: ``string|null``, default: ``null``) Specifies the persistent id string to use for a persistent connection. +``timeout`` (type: ``int``, default: ``30``) + Specifies the time (in seconds) used to connect to a Redis server before the + connection attempt times out. + ``read_timeout`` (type: ``int``, default: ``0``) Specifies the time (in seconds) used when performing read operations on the underlying network resource before the operation times out. @@ -175,9 +202,28 @@ Available Options Specifies the `TCP-keepalive`_ timeout (in seconds) of the connection. This requires phpredis v4 or higher and a TCP-keepalive enabled server. -``timeout`` (type: ``int``, default: ``30``) - Specifies the time (in seconds) used to connect to a Redis server before the - connection attempt times out. +``lazy`` (type: ``bool``, default: ``null``) + Enables or disables lazy connections to the backend. It's ``false`` by + default when using this as a stand-alone component and ``true`` by default + when using it inside a Symfony application. + +``redis_cluster`` (type: ``bool``, default: ``false``) + Enables or disables redis cluster. The actual value passed is irrelevant as long as it passes loose comparison + checks: `redis_cluster=1` will suffice. + +``redis_sentinel`` (type: ``string``, default: ``null``) + Specifies the master name connected to the sentinels. + +``dbindex`` (type: ``int``, default: ``0``) + Specifies the database index to select. + +``failover`` (type: ``string``, default: ``none``) + Specifies failover for cluster implementations. For ``\RedisCluster`` valid options are ``none`` (default), + ``error``, ``distribute`` or ``slaves``. For ``\Predis\ClientInterface`` valid options are ``slaves`` + or ``distribute``. + +``ssl`` (type: ``bool``, default: ``null``) + SSL context options. See `php.net/context.ssl`_ for more information. .. note:: @@ -225,3 +271,4 @@ Read more about this topic in the offical `Redis LRU Cache Documentation`_. .. _`TCP-keepalive`: https://redis.io/topics/clients#tcp-keepalive .. _`Redis Sentinel`: https://redis.io/topics/sentinel .. _`Redis LRU Cache Documentation`: https://redis.io/topics/lru-cache +.. _`php.net/context.ssl`: https://php.net/context.ssl