@@ -43,6 +43,28 @@ 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+ Middleware can access the message and its wrapper (the envelope) while it is
50+ dispatched through the bus.
51+ Literally *"the software in the middle" *, those are not about core concerns
52+ (business logic) of an application. Instead, they are cross cutting concerns
53+ applicable throughout the application and affecting the entire message bus.
54+ For instance: logging, validating a message, starting a transaction, ...
55+ They are also responsible for calling the next middleware in the chain,
56+ which means they can tweak the envelope, by adding items to it or even
57+ replacing it, as well as interrupt the middleware chain.
58+
59+ **Envelope **
60+ Messenger specific concept, it gives full flexibility inside the message bus,
61+ by wrapping the messages into it, allowing to add useful information inside
62+ through *envelope items *.
63+
64+ **Envelope Items **
65+ Piece of information you need to attach to your message: serializer context
66+ to use for transport, markers identifying a received message or any sort of
67+ metadata your middleware or transport layer may use.
4668
4769Bus
4870---
@@ -53,9 +75,9 @@ middleware stack. The component comes with a set of middleware that you can use.
5375When using the message bus with Symfony's FrameworkBundle, the following middleware
5476are configured for you:
5577
56- #.`` LoggingMiddleware ` ` (logs the processing of your messages)
57- #.`` SendMessageMiddleware ` ` (enables asynchronous processing)
58- #.`` HandleMessageMiddleware `` (calls the registered handler)
78+ #.:class: ` Symfony \\ Component \\ Messenger \\ Middleware \\ LoggingMiddleware
79+ #.:class: ` Symfony \\ Component \\ Messenger \\ Asynchronous \\ Middleware \\ SendMessageMiddleware
80+ #.:class: ` Symfony \\ Component \\ Messenger \\ Middleware \\ HandleMessageMiddleware(s) )
5981
6082Example::
6183
@@ -74,7 +96,7 @@ Example::
7496
7597..note ::
7698
77- Every middleware needs to implement the`` MiddlewareInterface ` `.
99+ Every middleware needs to implement the:class: ` Symfony \\ Component \\ Messenger \\ Middleware \\ MiddlewareInterface
78100
79101Handlers
80102--------
@@ -112,7 +134,7 @@ the ``SerializerConfiguration`` envelope::
112134 ]))
113135 );
114136
115- At the moment, the Symfony Messenger has the following built-inenvelopes :
137+ At the moment, the Symfony Messenger has the following built-inenvelope items :
116138
117139#.:class: `Symfony\\ Component\\ Messenger\\ Transport\\ Serialization\\ SerializerConfiguration `,
118140 to configure the serialization groups used by the transport.
@@ -151,6 +173,12 @@ The above example will forward the message to the next middleware with an additi
151173envelope item *if * the message has just been received (i.e. has the `ReceivedMessage ` item).
152174You can create your own items by implementing:class: `Symfony\\ Component\\ Messenger\\ EnvelopeAwareInterface `.
153175
176+ ..note ::
177+
178+ Any envelope item must be php serializable if going through transport using
179+ the:class: `Symfony\\ Component\\ Messenger\\ Transport\\ Serialization\\ Serializer `
180+ base serializer.
181+
154182Transports
155183----------
156184
@@ -160,7 +188,8 @@ transport will be responsible for communicating with your message broker or 3rd
160188Your own Sender
161189~~~~~~~~~~~~~~~
162190
163- Using the ``SenderInterface ``, you can create your own message sender.
191+ Using the:class: `Symfony\\ Component\\ Messenger\\ Transport\\ SenderInterface `,
192+ you can create your own message sender.
164193Imagine that you already have an ``ImportantAction `` message going through the
165194message bus and being handled by a handler. Now, you also want to send this
166195message as an email.