Add message envelope in the documentation

Author: sroze

components/messenger.rst

@@ -86,6 +86,46 @@ that will do the required processing for your message::
        }
     }
 
+Envelope
+--------
+
+The notion of an envelope is a concept that helps us to add some context around the
+messages. An envelope is a message and a set of items. On a user perspective, this
+allows to set some configuration around the message. For example the serialization
+groups used when the message goes through the transport layer::
+
+    use Symfony\Component\Messenger\Envelope;
+    use Symfony\Component\Messenger\Transport\Serialization\SerializerConfiguration;
+
+    $bus->dispatch(
+        (new Envelope($message))->with(new SerializerConfiguration([
+            'groups' => ['my_serialization_groups'],
+        ]))
+    );
+
+Instead of dealing directly with the messages in the handlers and middleware you
+can receive the envelope by implementing the ``EnvelopeAwareInterface`` marker
+interface on your middleware or handler like this::
+
+    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
+
+            return $next(
+                $message->with(new AnotherEnvelopeItem(/* ... */))
+            );
+        }
+    }
+
+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``
+interface.
+
 Transports
 ----------
 
@@ -106,6 +146,7 @@ First, create your sender::
 
     use App\Message\ImportantAction;
     use Symfony\Component\Messenger\Transport\SenderInterface;
+    use Symfony\Component\Messenger\Envelope;
 
     class ImportantActionToEmailSender implements SenderInterface
     {
@@ -118,10 +159,12 @@ First, create your sender::
            $this->toEmail = $toEmail;
        }
 
-       public function send($message)
+       public function send(Envelope $envelope)
        {
+           $message = $envelope->getMessage();
+
            if (!$message instanceof ImportantAction) {
-               throw new \InvalidArgumentException(sprintf('Producer only supports "%s" messages.', ImportantAction::class));
+               throw new \InvalidArgumentException(sprintf('This transport only supports "%s" messages.', ImportantAction::class));
            }
 
            $this->mailer->send(
@@ -156,6 +199,7 @@ First, create your receiver::
     use App\Message\NewOrder;
     use Symfony\Component\Messenger\Transport\ReceiverInterface;
     use Symfony\Component\Serializer\SerializerInterface;
+    use Symfony\Component\Messenger\Envelope;
 
     class NewOrdersFromCsvFile implements ReceiverInterface
     {
@@ -173,7 +217,9 @@ First, create your receiver::
            $ordersFromCsv = $this->serializer->deserialize(file_get_contents($this->filePath), 'csv');
 
            foreach ($ordersFromCsv as $orderFromCsv) {
-               $handler(new NewOrder($orderFromCsv['id'], $orderFromCsv['account_id'], $orderFromCsv['amount']));
+               $order = new NewOrder($orderFromCsv['id'], $orderFromCsv['account_id'], $orderFromCsv['amount']);
+
+               $handler(new Envelope($order));
            }
        }
 
@@ -188,6 +234,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 wrap the received messages into ``ReceivedMessage`` objects and the
-``SendMessageMiddleware`` middleware will know it should not route these
-messages again to a transport.
+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.