fixes #16310 unclear alternate DSN format

Author: ToshY

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]][&params]
+
+    Values for placeholders ``[user]``, ``[:port]``, ``[/db-index]`` and ``[&params]`` 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,29 +153,31 @@ 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,
         ]
 
     );
 
 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