feature #11341 Add documentation for the Redis transport (alexander-schranz)

This PR was submitted for the master branch but it was squashed and merged into the 4.3 branch instead (closes #11341).

Discussion
----------

Add documentation for the Redis transport

This will add documentation how to configure and using the redis transport with the messenger component.

symfony/symfony#30917

#EUFOSSA

Commits
-------

c22fade Add documentation for the Redis transport

Author: wouterj

messenger.rst

@@ -135,8 +135,12 @@ Transports
 By default, messages are processed as soon as they are dispatched. If you prefer
 to process messages asynchronously, you must configure a transport. These
 transports communicate with your application via queuing systems or third parties.
-The built-in AMQP transport allows you to communicate with most of the AMQP
-brokers such as RabbitMQ.
+
+There are the following built-in transports:
+
+ - AMQP
+ - Doctrine
+ - Redis
 
 .. note::
 
@@ -155,7 +159,7 @@ the messenger component, the following configuration should have been created:
         framework:
             messenger:
                 transports:
-                    amqp: "%env(MESSENGER_TRANSPORT_DSN)%"
+                    your_transport: "%env(MESSENGER_TRANSPORT_DSN)%"
 
     .. code-block:: xml
 
@@ -171,7 +175,7 @@ the messenger component, the following configuration should have been created:
 
             <framework:config>
                 <framework:messenger>
-                    <framework:transport name="amqp" dsn="%env(MESSENGER_TRANSPORT_DSN)%"/>
+                    <framework:transport name="your_transport" dsn="%env(MESSENGER_TRANSPORT_DSN)%"/>
                 </framework:messenger>
             </framework:config>
         </container>
@@ -182,33 +186,63 @@ the messenger component, the following configuration should have been created:
         $container->loadFromExtension('framework', [
             'messenger' => [
                 'transports' => [
-                    'amqp' => '%env(MESSENGER_TRANSPORT_DSN)%',
+                    'your_transport' => '%env(MESSENGER_TRANSPORT_DSN)%',
                 ],
             ],
         ]);
 
+This will also configure the following services for you:
+
+#. A ``messenger.sender.your_transport`` sender to be used when routing messages;
+#. A ``messenger.receiver.your_transport`` receiver to be used when consuming messages.
+
+Now define the ``MESSENGER_TRANSPORT_DSN`` in the ``.env`` file.
+See examples beneath how to configure the DSN for different transports.
+
+Amqp
+~~~~
+
 .. code-block:: bash
 
     # .env
-    ###> symfony/messenger ###
     MESSENGER_TRANSPORT_DSN=amqp://guest:guest@localhost:5672/%2f/messages
-    ###< symfony/messenger ###
 
 This is enough to allow you to route your message to the ``amqp`` transport.
-This will also configure the following services for you:
-
-#. A ``messenger.sender.amqp`` sender to be used when routing messages;
-#. A ``messenger.receiver.amqp`` receiver to be used when consuming messages.
 
 .. note::
 
     In order to use Symfony's built-in AMQP transport, you will need the AMQP
-    PHP extension and the Serializer Component. Ensure that they are installed with:
+    PHP extension and the Serializer component. Ensure that they are installed with:
 
     .. code-block:: terminal
 
         $ composer require symfony/amqp-pack
 
+Redis
+~~~~~
+
+The Redis transport will use `streams`_ to queue messages.
+
+.. code-block:: bash
+
+    # .env
+    MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages
+
+This is enough to allow you to route your message to the Redis transport.
+
+If you have multiple systems to receive the same messages you could use different groups
+to achieve this:
+
+.. code-block:: bash
+
+    # .env
+    MESSENGER_TRANSPORT_DSN=redis://localhost:6379/messages/group1/consumer1
+
+.. note::
+
+    In order to use Symfony's built-in Redis transport, you will need the Redis
+    PHP extension (^4.2), a running Redis server (^5.0) and the Serializer component.
+
 Routing
 -------
 
@@ -225,7 +259,7 @@ configuration:
         framework:
             messenger:
                 routing:
-                    'My\Message\Message':  amqp # The name of the defined transport
+                    'My\Message\Message':  your_transport # The name of the defined transport
 
     .. code-block:: xml
 
@@ -242,7 +276,7 @@ configuration:
             <framework:config>
                 <framework:messenger>
                     <framework:routing message-class="My\Message\Message">
-                        <framework:sender service="amqp"/>
+                        <framework:sender service="your_transport"/>
                     </framework:routing>
                 </framework:messenger>
             </framework:config>
@@ -254,7 +288,7 @@ configuration:
         $container->loadFromExtension('framework', [
             'messenger' => [
                 'routing' => [
-                    'My\Message\Message' => 'amqp',
+                    'My\Message\Message' => 'your_transport',
                 ],
             ],
         ]);
@@ -274,7 +308,7 @@ instead of a class name:
             messenger:
                 routing:
                     'My\Message\MessageAboutDoingOperationalWork': another_transport
-                    '*': amqp
+                    '*': your_transport
 
     .. code-block:: xml
 
@@ -294,7 +328,7 @@ instead of a class name:
                         <framework:sender service="another_transport"/>
                     </framework:routing>
                     <framework:routing message-class="*">
-                        <framework:sender service="amqp"/>
+                        <framework:sender service="your_transport"/>
                     </framework:routing>
                 </framework:messenger>
             </framework:config>
@@ -307,7 +341,7 @@ instead of a class name:
             'messenger' => [
                 'routing' => [
                     'My\Message\Message' => 'another_transport',
-                    '*' => 'amqp',
+                    '*' => 'your_transport',
                 ],
             ],
         ]);
@@ -322,7 +356,7 @@ A class of messages can also be routed to multiple senders by specifying a list:
         framework:
             messenger:
                 routing:
-                    'My\Message\ToBeSentToTwoSenders': [amqp, audit]
+                    'My\Message\ToBeSentToTwoSenders': [your_transport, audit]
 
     .. code-block:: xml
 
@@ -339,7 +373,7 @@ A class of messages can also be routed to multiple senders by specifying a list:
             <framework:config>
                 <framework:messenger>
                     <framework:routing message-class="My\Message\ToBeSentToTwoSenders">
-                        <framework:sender service="amqp"/>
+                        <framework:sender service="your_transport"/>
                         <framework:sender service="audit"/>
                     </framework:routing>
                 </framework:messenger>
@@ -352,7 +386,7 @@ A class of messages can also be routed to multiple senders by specifying a list:
         $container->loadFromExtension('framework', [
             'messenger' => [
                 'routing' => [
-                    'My\Message\ToBeSentToTwoSenders' => ['amqp', 'audit'],
+                    'My\Message\ToBeSentToTwoSenders' => ['your_transport', 'audit'],
                 ],
             ],
         ]);
@@ -369,7 +403,7 @@ while still having them passed to their respective handler:
             messenger:
                 routing:
                     'My\Message\ThatIsGoingToBeSentAndHandledLocally':
-                         senders: [amqp]
+                         senders: [your_transport]
                          send_and_handle: true
 
     .. code-block:: xml
@@ -387,7 +421,7 @@ while still having them passed to their respective handler:
             <framework:config>
                 <framework:messenger>
                     <framework:routing message-class="My\Message\ThatIsGoingToBeSentAndHandledLocally" send-and-handle="true">
-                        <framework:sender service="amqp"/>
+                        <framework:sender service="your_transport"/>
                     </framework:routing>
                 </framework:messenger>
             </framework:config>
@@ -400,7 +434,7 @@ while still having them passed to their respective handler:
             'messenger' => [
                 'routing' => [
                     'My\Message\ThatIsGoingToBeSentAndHandledLocally' => [
-                        'senders' => ['amqp'],
+                        'senders' => ['your_transport'],
                         'send_and_handle' => true,
                     ],
                 ],
@@ -415,7 +449,7 @@ most of the cases. To do so, use the ``messenger:consume`` command like this:
 
 .. code-block:: terminal
 
-    $ php bin/console messenger:consume amqp
+    $ php bin/console messenger:consume your_transport
 
 The first argument is the receiver's service name. It might have been created by
 your ``transports`` configuration or it can be your own receiver.
@@ -835,3 +869,4 @@ Learn more
     /messenger/*
 
 .. _`enqueue's transport`: https://github.com/php-enqueue/messenger-adapter
+.. _`streams`: https://redis.io/topics/streams-intro