Merge branch '4.1'

* 4.1:
  Enhance messenger doc

Author: xabbuh

components/messenger.rst

@@ -43,6 +43,28 @@ Concepts
 
 **Handler**:
    Responsible for handling messages using the business logic applicable to the messages.
+   Handlers are called by the ``HandleMessageMiddleware`` middleware.
+
+**Middleware**:
+   Middleware can access the message and its wrapper (the envelope) while it is
+   dispatched through the bus.
+   Literally *"the software in the middle"*, those are not about core concerns
+   (business logic) of an application. Instead, they are cross cutting concerns
+   applicable throughout the application and affecting the entire message bus.
+   For instance: logging, validating a message, starting a transaction, ...
+   They are also responsible for calling the next middleware in the chain,
+   which means they can tweak the envelope, by adding items to it or even
+   replacing it, as well as interrupt the middleware chain.
+
+**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 +75,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 +96,7 @@ Example::
 
 .. note::
 
-    Every middleware needs to implement the ``MiddlewareInterface``.
+    Every middleware needs to implement the :class:`Symfony\\Component\\Messenger\\Middleware\\MiddlewareInterface`.
 
 Handlers
 --------
@@ -156,6 +178,12 @@ The above example will forward the message to the next middleware with an additi
 stamp *if* the message has just been received (i.e. has the `ReceivedStamp` stamp).
 You can create your own items by implementing :class:`Symfony\\Component\\Messenger\\Stamp\\StampInterface`.
 
+.. note::
+
+    Any envelope item must be php serializable if going through transport using
+    the :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\Serializer`
+    base serializer.
+
 Transports
 ----------
 
@@ -165,7 +193,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.

messenger.rst

@@ -658,8 +658,8 @@ within the buses to add some extra capabilities like this:
             ),
         ));
 
-Note that if the service is abstract, a different instance of service will be
-created per bus.
+Note that if the service is abstract, a different instance of the service will
+be created per bus.
 
 Using Middleware Factories
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -683,9 +683,9 @@ This middleware can be configured to define the entity manager to use:
                     command_bus:
                         middleware:
                             # Using the default configured entity manager name
-                            - doctrine_transaction_middleware
+                            - doctrine_transaction
                             # Using another entity manager
-                            - doctrine_transaction_middleware: ['custom']
+                            - doctrine_transaction: ['custom']
 
     .. code-block:: xml
 
@@ -705,7 +705,7 @@ This middleware can be configured to define the entity manager to use:
                         <!-- Using the default configured entity manager name -->
                         <framework:middleware id="doctrine_transaction_middleware" />
                         <!-- Using another entity manager -->
-                        <framework:middleware id="doctrine_transaction_middleware">
+                        <framework:middleware id="doctrine_transaction">
                             <framework:argument>custom</framework:argument>
                         </framework:middleware>
                     </framework:bus>
@@ -722,9 +722,9 @@ This middleware can be configured to define the entity manager to use:
                     'command_bus' => array(
                         'middleware' => array(
                             // Using the default configured entity manager name
-                            'doctrine_transaction_middleware',
+                            'doctrine_transaction',
                             // Using another entity manager
-                            array('id' => 'doctrine_transaction_middleware', 'arguments' => array('custom')),
+                            array('id' => 'doctrine_transaction', 'arguments' => array('custom')),
                         ),
                     ),
                 ),