@@ -43,6 +43,23 @@ Concepts
4343
4444**Handler **:
4545 Responsible for handling messages using the business logic applicable to the messages.
46+ Handlers are called by the ``HandleMessageMiddleware `` middleware.
47+
48+ **Middleware **:
49+ Man-in-the-middle classes, allowing to spy the message and its wrapper (the envelope).
50+ Middleware have many usages: log messages, validate messages, start a transaction, ...
51+ It can also tweak the envelope, by adding items to it, or even completely replace it
52+ or the message inside.
53+
54+ **Envelope **
55+ Messenger specific concept, it gives full flexibility inside the message bus,
56+ by wrapping the messages into it, allowing to add useful information inside
57+ through *envelope items *.
58+
59+ **Envelope items **
60+ Piece of information you need to attach to your message: serializer context
61+ to use for transport, markers identifying a received message or any sort of
62+ metadata your middleware or transport layer may use.
4663
4764Bus
4865---
@@ -53,9 +70,9 @@ middleware stack. The component comes with a set of middleware that you can use.
5370When using the message bus with Symfony's FrameworkBundle, the following middleware
5471are configured for you:
5572
56- #.`` LoggingMiddleware ` ` (logs the processing of your messages)
57- #.`` SendMessageMiddleware ` ` (enables asynchronous processing)
58- #.`` HandleMessageMiddleware `` (calls the registered handler)
73+ #.:class: ` Symfony \\ Component \\ Messenger \\ Middleware \\ LoggingMiddleware
74+ #.:class: ` Symfony \\ Component \\ Messenger \\ Asynchronous \\ Middleware \\ SendMessageMiddleware
75+ #.:class: ` Symfony \\ Component \\ Messenger \\ Middleware \\ HandleMessageMiddleware(s) )
5976
6077Example::
6178
@@ -74,7 +91,7 @@ Example::
7491
7592..note ::
7693
77- Every middleware needs to implement the`` MiddlewareInterface ` `.
94+ Every middleware needs to implement the:class: ` Symfony \\ Component \\ Messenger \\ Middleware \\ MiddlewareInterface
7895
7996Handlers
8097--------
@@ -112,7 +129,7 @@ the ``SerializerConfiguration`` envelope::
112129 ]))
113130 );
114131
115- At the moment, the Symfony Messenger has the following built-inenvelopes :
132+ At the moment, the Symfony Messenger has the following built-inenvelope items :
116133
117134#.:class: `Symfony\\ Component\\ Messenger\\ Transport\\ Serialization\\ SerializerConfiguration `,
118135 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
151168envelope item *if * the message has just been received (i.e. has the `ReceivedMessage ` item).
152169You can create your own items by implementing:class: `Symfony\\ Component\\ Messenger\\ EnvelopeAwareInterface `.
153170
171+ ..note ::
172+
173+ Any envelope item must be php serializable if going through transport using
174+ the:class: `Symfony\\ Component\\ Messenger\\ Transport\\ Serialization\\ Serializer `
175+ base serializer.
176+
154177Transports
155178----------
156179
@@ -160,7 +183,8 @@ transport will be responsible for communicating with your message broker or 3rd
160183Your own Sender
161184~~~~~~~~~~~~~~~
162185
163- Using the ``SenderInterface ``, you can create your own message sender.
186+ Using the:class: `Symfony\\ Component\\ Messenger\\ Transport\\ SenderInterface `,
187+ you can create your own message sender.
164188Imagine that you already have an ``ImportantAction `` message going through the
165189message bus and being handled by a handler. Now, you also want to send this
166190message as an email.