Finish the documentation about the custom adapter

symfony · javiereguiluz · Apr 16, 2018 · Mar 14, 2018 · Mar 18, 2018 · Mar 23, 2018
commit bcfae23b07559cd61bd40929f472c78e9594e70f
diff --git a/components/messenger.rst b/components/messenger.rst
@@ -136,16 +136,16 @@ First, create your sender::
 Your own receiver
 -----------------
 
-A consumer is responsible for receiving messages from a source and dispatching
+A receiver is responsible for receiving messages from a source and dispatching
 them to the application.
 
-Let's say you already proceed some "orders" on your application using a
+Let's say you already processed some "orders" in your application using a
 ``NewOrder`` message. Now you want to integrate with a 3rd party or a legacy
 application but you can't use an API and need to use a shared CSV file with new
 orders.
 
 You will read this CSV file and dispatch a ``NewOrder`` message. All you need to
-do is your custom CSV consumer and Symfony will do the rest.
+do is to write your custom CSV receiver and Symfony will do the rest.
 
 First, create your receiver::
 
@@ -179,9 +179,8 @@ First, create your receiver::
 Same bus received and sender
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To allow us to receive and send messages on the same bus and prevent a loop, the
-message bus is equipped with the ``WrapIntoReceivedMessage`` received. It will
-wrap the received messages into ``ReceivedMessage`` objects and the
-``SendMessageMiddleware`` middleware will know it should not send these messages.
-
-.. _`PHP Enqueue bridge`: https://github.com/sroze/enqueue-bridge
+To allow us to receive and send messages on the same bus and prevent an infinite
+loop, the message bus is equipped with the :code:`WrapIntoReceivedMessage` middleware.
+It will wrap the received messages into :code:`ReceivedMessage` objects and the
+:code:`SendMessageMiddleware` middleware will know it should not route these
+messages again to an adapter.
diff --git a/messenger.rst b/messenger.rst
@@ -61,7 +61,7 @@ Once you've created your handler, you need to register it:
 .. code-block:: xml
 
     <service id="App\MessageHandler\MyMessageHandler">
-       <tag name="message_handler" />
+       <tag name="messenger.message_handler" />
     </service>
 
 .. note::
@@ -78,7 +78,7 @@ most of the AMQP brokers such as RabbitMQ.
 
 .. note::
 
-    If you need more message brokers, you should have a look to Enqueue's adapter
+    If you need more message brokers, you should have a look to `Enqueue's adapter`_
     which supports things like Kafka, Amazon SQS or Google Pub/Sub.
 
 An adapter is registered using a "DSN", which is a string that represents the
@@ -176,7 +176,47 @@ Learn how to build your own adapters within the Component's documentation. Once
 you have built your classes, you can register your adapter factory to be able to
 use it via a DSN in the Symfony application.
 
+Create your adapter Factory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+You need to give FrameworkBundle the opportunity to create your adapter from a
+DSN. You will need an adapter factory::
+
+    use Symfony\Component\Messenger\Adapter\Factory\AdapterInterface;
+    use Symfony\Component\Messenger\Adapter\Factory\AdapterFactoryInterface;
+
+    class YourAdapterFactory implements AdapterFactoryInterface
+    {
+        public function create(string $dsn): AdapterInterface
+        {
+            return new YourAdapter(/* ... */);
+        }
+
+        public function supports(string $dsn): bool
+        {
+            return 0 === strpos($dsn, 'my-adapter://');
+        }
+    }
+
+The :code:`YourAdaper` class need to implements the :code:`AdapterInterface`. It
+will like the following example::
+
+    use Symfony\Component\Messenger\Adapter\Factory\AdapterInterface;
+    use Symfony\Component\Messenger\Transport\ReceiverInterface;
+    use Symfony\Component\Messenger\Transport\SenderInterface;
+
+    class YourAdapter implements AdapterInterface
+    {
+        public function receiver(): ReceiverInterface
+        {
+            return new YourReceiver(/* ... */);
+        }
+
+        public function sender(): SenderInterface
+        {
+            return new YourSender(/* ... */);
+        }
+    }
 
 Register your factory
 ~~~~~~~~~~~~~~~~~~~~~
@@ -186,3 +226,24 @@ Register your factory
     <service id="Your\Adapter\Factory">
        <tag name="messenger.adapter_factory" />
     </service>
+
+Use your adapter
+~~~~~~~~~~~~~~~~
+
+Within the :code:`framework.messenger.adapters.*` configuration, create your
+named adapter using your own DSN:
+
+.. code-block:: yaml
+
+    framework:
+        messenger:
+            adapters:
+                yours: 'my-adapter://...'
+
+This will give you access to the following services:
+
+1. :code:`messenger.yours_adapter`: the instance of your adapter.
+2. :code:`messenger.yours_receiver` and :code:`messenger.yours_sender`, the
+   receiver and sender created by the adapter.
+
+.. _`PHP Enqueue bridge`: https://github.com/sroze/enqueue-bridge