Update the envelope update

Author: sroze

components/messenger.rst

@@ -104,27 +104,45 @@ in an ``Envelope`` and add some ``SerializerConfiguration``::
         ]))
     );
 
-Instead of dealing directly with the message in the handlers or middleware, you
-can receive the envelope by implementing the ``EnvelopeAwareInterface`` marker,
-like this::
+At the moment, the Symfony Messenger has the following built-in envelopes:
 
+1. :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\SerializerConfiguration`,
+   to configure the serialization groups used by the transport.
+2. :class:`Symfony\\Component\\Messenger\\Middleware\\Configuration\\ValidationConfiguration`,
+   to configure the validation groups used when the validation middleware is enabled.
+3. :class:`Symfony\\Component\\Messenger\\Asynchronous\\Transport\\ReceivedMessage`,
+   an internal item that marks the message as received from a transport.
+
+Instead of dealing directly with the messages in the middleware you can receive the
+envelope by implementing the :class:`Symfony\\Component\\Messenger\\EnvelopeAwareInterface`
+marker, like this::
+
+    use Symfony\Component\Messenger\Asynchronous\Transport\ReceivedMessage;
     use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
     use Symfony\Component\Messenger\EnvelopeAwareInterface;
 
     class MyOwnMiddleware implements MiddlewareInterface, EnvelopeAwareInterface
     {
         public function handle($message, callable $next)
         {
-            // $message here is an `Envelope` object
+            // $message here is an `Envelope` object, because this middleware
+            // implements the EnvelopeAwareInterface interface. Otherwise,
+            // it would be the "original" message.
+
+            if (null !== $message->get(ReceivedMessage::class)) {
+                // Message just has been received...
+
+                // You could for example add another item.
+                $message = $message->with(new AnotherEnvelopeItem(/* ... */));
+            }
 
-            return $next(
-                $message->with(new AnotherEnvelopeItem(/* ... */))
-            );
+            return $next($message);
         }
     }
 
 The above example will forward the message to the next middleware with an additional
-envelope item. You can create your own items by implementing the ``EnvelopeItemInterface``
+envelope item if the message has just been received (i.e. has the `ReceivedMessage` item).
+You can create your own items by implementing the :class:`Symfony\\Component\\Messenger\\EnvelopeAwareInterface`
 interface.
 
 Transports
@@ -234,7 +252,6 @@ Receiver and Sender on the same bus
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To allow us to receive and send messages on the same bus and prevent an infinite
-loop, the message bus is equipped with the ``WrapIntoReceivedMessage`` middleware.
-It will add a ``ReceivedMessage`` configuration to the message envelopes and the
-``SendMessageMiddleware`` middleware will know it should not route these messages
-again to a transport.
+loop, the message bus will add a :class:`Symfony\\Component\\Messenger\\Asynchronous\\Transport\\ReceivedMessage`
+envelope item to the message envelopes and the :class:`Symfony\\Component\\Messenger\\Asynchronous\\Middleware\\SendMessageMiddleware`
+middleware will know it should not route these messages again to a transport.