[Messenger] Add more notes about base concepts, envelope items & class refs

ogizanagi · ogizanagi · commit bab948e5f1d7 · 2018-11-12T14:12:55.000+01:00
diff --git a/components/messenger.rst b/components/messenger.rst
@@ -43,6 +43,23 @@ Concepts
 
 **Handler**:
    Responsible for handling messages using the business logic applicable to the messages.
+   Handlers are called by the ``HandleMessageMiddleware`` middleware.
+
+**Middleware**:
+   Man-in-the-middle classes, allowing to spy the message and its wrapper (the envelope).
+   Middleware have many usages: log messages, validate messages, start a transaction, ...
+   It can also tweak the envelope, by adding items to it, or even completely replace it
+   or the message inside.
+
+**Envelope**
+   Messenger specific concept, it gives full flexibility inside the message bus,
+   by wrapping the messages into it, allowing to add useful information inside
+   through *envelope items*.
+
+**Envelope items**
+   Piece of information you need to attach to your message: serializer context
+   to use for transport, markers identifying a received message or any sort of
+   metadata your middleware or transport layer may use.
 
 Bus
 ---
@@ -53,9 +70,9 @@ middleware stack. The component comes with a set of middleware that you can use.
 When using the message bus with Symfony's FrameworkBundle, the following middleware
 are configured for you:
 
-#. ``LoggingMiddleware`` (logs the processing of your messages)
-#. ``SendMessageMiddleware`` (enables asynchronous processing)
-#. ``HandleMessageMiddleware`` (calls the registered handler)
+#. :class:`Symfony\\Component\\Messenger\\Middleware\\LoggingMiddleware` (logs the processing of your messages)
+#. :class:`Symfony\\Component\\Messenger\\Asynchronous\\Middleware\\SendMessageMiddleware` (enables asynchronous processing)
+#. :class:`Symfony\\Component\\Messenger\\Middleware\\HandleMessageMiddleware` (calls the registered handler(s))
 
 Example::
 
@@ -74,7 +91,7 @@ Example::
 
 .. note::
 
-    Every middleware needs to implement the ``MiddlewareInterface``.
+    Every middleware needs to implement the :class:`Symfony\\Component\\Messenger\\Middleware\\MiddlewareInterface`.
 
 Handlers
 --------
@@ -112,7 +129,7 @@ the ``SerializerConfiguration`` envelope::
         ]))
     );
 
-At the moment, the Symfony Messenger has the following built-in envelopes:
+At the moment, the Symfony Messenger has the following built-in envelope items:
 
 #. :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\SerializerConfiguration`,
    to configure the serialization groups used by the transport.
@@ -151,6 +168,12 @@ The above example will forward the message to the next middleware with an additi
 envelope item *if* the message has just been received (i.e. has the `ReceivedMessage` item).
 You can create your own items by implementing :class:`Symfony\\Component\\Messenger\\EnvelopeAwareInterface`.
 
+.. note::
+
+    Any envelope item must be php serializable if going through transport using
+    the :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\Serializer`
+    base serializer.
+
 Transports
 ----------
 
@@ -160,7 +183,8 @@ transport will be responsible for communicating with your message broker or 3rd
 Your own Sender
 ~~~~~~~~~~~~~~~
 
-Using the ``SenderInterface``, you can create your own message sender.
+Using the :class:`Symfony\\Component\\Messenger\\Transport\\SenderInterface`,
+you can create your own message sender.
 Imagine that you already have an ``ImportantAction`` message going through the
 message bus and being handled by a handler. Now, you also want to send this
 message as an email.
