8000 Merge branch '4.1' · symfony/symfony-docs@436cbd0 · GitHub
[go: up one dir, main page]

Skip to content

Commit 436cbd0

Browse files
committed
Merge branch '4.1'
* 4.1: Enhance messenger doc
2 parents 013b69c + 2191d35 commit 436cbd0

File tree

2 files changed

+41
-12
lines changed

2 files changed

+41
-12
lines changed

components/messenger.rst

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -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

4769
Bus
4870
---
@@ -53,9 +75,9 @@ middleware stack. The component comes with a set of middleware that you can use.
5375
When using the message bus with Symfony's FrameworkBundle, the following middleware
5476
are 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` (logs the processing of your messages)
79+
#. :class:`Symfony\\Component\\Messenger\\Asynchronous\\Middleware\\SendMessageMiddleware` (enables asynchronous processing)
80+
#. :class:`Symfony\\Component\\Messenger\\Middleware\\HandleMessageMiddleware` (calls the registered handler(s))
5981

6082
Example::
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

79101
Handlers
80102
--------
@@ -156,6 +178,12 @@ The above example will forward the message to the next middleware with an additi
156178
stamp *if* the message has just been received (i.e. has the `ReceivedStamp` stamp).
157179
You can create your own items by implementing :class:`Symfony\\Component\\Messenger\\Stamp\\StampInterface`.
158180

181+
.. note::
182+
183+
Any envelope item must be php serializable if going through transport using
184+
the :class:`Symfony\\Component\\Messenger\\Transport\\Serialization\\Serializer`
185+
base serializer.
186+
159187
Transports
160188
----------
161189

@@ -165,7 +193,8 @@ transport will be responsible for communicating with your message broker or 3rd
165193
Your own Sender
166194
~~~~~~~~~~~~~~~
167< 8000 code>195

168-
Using the ``SenderInterface``, you can create your own message sender.
196+
Using the :class:`Symfony\\Component\\Messenger\\Transport\\SenderInterface`,
197+
you can create your own message sender.
169198
Imagine that you already have an ``ImportantAction`` message going through the
170199
message bus and being handled by a handler. Now, you also want to send this
171200
message as an email.

messenger.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -658,8 +658,8 @@ within the buses to add some extra capabilities like this:
658658
),
659659
));
660660
661-
Note that if the service is abstract, a different instance of service will be
662-
created per bus.
661+
Note that if the service is abstract, a different instance of the service will
662+
be created per bus.
663663

664664
Using Middleware Factories
665665
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -683,9 +683,9 @@ This middleware can be configured to define the entity manager to use:
683683
command_bus:
684684
middleware:
685685
# Using the default configured entity manager name
686-
- doctrine_transaction_middleware
686+
- doctrine_transaction
687687
# Using another entity manager
688-
- doctrine_transaction_middleware: ['custom']
688+
- doctrine_transaction: ['custom']
689689
690690
.. code-block:: xml
691691
@@ -705,7 +705,7 @@ This middleware can be configured to define the entity manager to use:
705705
<!-- Using the default configured entity manager name -->
706706
<framework:middleware id="doctrine_transaction_middleware" />
707707
<!-- Using another entity manager -->
708-
<framework:middleware id="doctrine_transaction_middleware">
708+
<framework:middleware id="doctrine_transaction">
709709
<framework:argument>custom</framework:argument>
710710
</framework:middleware>
711711
</framework:bus>
@@ -722,9 +722,9 @@ This middleware can be configured to define the entity manager to use:
722722
'command_bus' => array(
723723
'middleware' => array(
724724
// Using the default configured entity manager name
725-
'doctrine_transaction_middleware',
725+
'doctrine_transaction',
726726
// Using another entity manager
727-
array('id' => 'doctrine_transaction_middleware', 'arguments' => array('custom')),
727+
array('id' => 'doctrine_transaction', 'arguments' => array('custom')),
728728
),
729729
),
730730
),

0 commit comments

Comments
 (0)
0