[Messenger] Describe the doctrine tranport

Author: vincenttouzet

messenger.rst

@@ -936,4 +936,13 @@ will give you access to the following services:
 #. ``messenger.sender.yours``: the sender;
 #. ``messenger.receiver.yours``: the receiver.
 
+Learn More
+----------
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    messenger/*
+
 .. _`enqueue's transport`: https://github.com/php-enqueue/messenger-adapter

messenger/doctrine-transport.rst

@@ -0,0 +1,106 @@
+.. index::
+   single: Messenger; Use doctrine as a transport
+
+Use Doctrine as transport
+=========================
+
+The Messenger component comes with a Doctrine transport. This transport let doctrine handle the storage of your messages. To use this transport you need to define the transport as the following :
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                transports:
+                    doctrine: "doctrine://default"
+
+    .. code-block:: xml
+
+        <!-- config/packages/messenger.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:messenger>
+                    <framework:transport name="doctrine" dsn="doctrine://default" />
+                </framework:messenger>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/messenger.php
+        $container->loadFromExtension('framework', array(
+            'messenger' => array(
+                'transports' => array(
+                    'doctrine' => 'doctrine://default',
+                ),
+            ),
+        ));
+
+The format of the DSN is `doctrine://<connection_name>`. The connection name is the name you used in the doctrine configuration. If you only use one connection then use `default`.
+
+Customize table name
+--------------------
+
+By default the transport will create a table named `messenger_messages` but you can configure it per transport:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                transports:
+                    doctrine:
+                        dsn: "doctrine://default"
+                        options: {table_name: "custom_table_name_for_messages"}
+
+    .. code-block:: xml
+
+        <!-- config/packages/messenger.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:messenger>
+                    <framework:transport name="doctrine" dsn="doctrine://default">
+                        <framework:option table_name="custom_table_name_for_messages" />
+                    </framework:transport>
+                </framework:messenger>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/messenger.php
+        $container->loadFromExtension('framework', array(
+            'messenger' => array(
+                'transports' => array(
+                    'doctrine' => array(
+                        'dsn' => 'doctrine://default',
+                        'options' => array('table_name' => 'custom_table_name_for_messages'),
+                    ),
+                ),
+            ),
+        ));
+
+Working with multiple connections
+---------------------------------
+
+If you have multiple Doctrine connections defined you can choose the desired one. If you have a connection named `legacy` the you must use the following DSN : `doctrine://legacy`.