|
4 | 4 | Transactional Messages: Handle New Messages After Handling is Done |
5 | 5 | ================================================================== |
6 | 6 |
|
7 | | -A message handler can ``dispatch`` new messages during execution, to either the same or |
8 | | -a different bus (if the application has `multiple buses</messenger/multiple_buses>`_). |
9 | | -Any errors or exceptions that occur during this process can have unintended consequences, |
10 | | -such as: |
11 | | - |
12 | | -- If using the ``DoctrineTransactionMiddleware`` and a dispatched message throws an exception, |
13 | | - then any database transactions in the original handler will be rolled back. |
14 | | -- If the message is dispatched to a different bus, then the dispatched message will |
15 | | - be handled even if some code later in the current handler throws an exception. |
| 7 | +A message handler can ``dispatch`` new messages during execution, to either the |
| 8 | +same or a different bus (if the application has |
| 9 | +`multiple buses</messenger/multiple_buses>`_). Any errors or exceptions that |
| 10 | +occur during this process can have unintended consequences, such as: |
| 11 | + |
| 12 | +- If using the ``DoctrineTransactionMiddleware`` and a dispatched message throws |
| 13 | + an exception, then any database transactions in the original handler will be |
| 14 | + rolled back. |
| 15 | +- If the message is dispatched to a different bus, then the dispatched message |
| 16 | + will be handled even if some code later in the current handler throws an |
| 17 | + exception. |
16 | 18 |
|
17 | 19 | An Example ``RegisterUser`` Process |
18 | 20 | ----------------------------------- |
19 | 21 |
|
20 | | -Let's take the example of an application with both a *command* and an *event* bus. The application |
21 | | -dispatches a command named ``RegisterUser`` to the command bus. The command is handled by the |
22 | | -``RegisterUserHandler`` which creates a ``User`` object, stores that object to a database and |
23 | | -dispatches a ``UserRegistered`` message to the event bus. |
| 22 | +Let's take the example of an application with both a *command* and an *event* |
| 23 | +bus. The application dispatches a command named ``RegisterUser`` to the command |
| 24 | +bus. The command is handled by the ``RegisterUserHandler`` which creates a |
| 25 | +``User`` object, stores that object to a database and dispatches a |
| 26 | +``UserRegistered`` message to the event bus. |
24 | 27 |
|
25 | 28 | There are many handlers to the ``UserRegistered`` message, one handler may send |
26 | 29 | a welcome email to the new user. We are using the ``DoctrineTransactionMiddleware`` |
27 | 30 | to wrap all database queries in one database transaction. |
28 | 31 |
|
29 | | -**Problem 1:** If an exception is thrown when sending the welcome email, then the user |
30 | | -will not be created because the ``DoctrineTransactionMiddleware`` will rollback the |
31 | | -Doctrine transaction, in which the user has been created. |
| 32 | +**Problem 1:** If an exception is thrown when sending the welcome email, then |
| 33 | +the userwill not be created because the ``DoctrineTransactionMiddleware`` will |
| 34 | +rollback theDoctrine transaction, in which the user has been created. |
32 | 35 |
|
33 | | -**Problem 2:** If an exception is thrown when saving the user to the database, the welcome |
34 | | -email is still sent because it is handled asynchronously. |
| 36 | +**Problem 2:** If an exception is thrown when saving the user to the database, |
| 37 | +the welcomeemail is still sent because it is handled asynchronously. |
35 | 38 |
|
36 | 39 | DispatchAfterCurrentBusMiddleware Middleware |
37 | 40 | -------------------------------------------- |
38 | 41 |
|
39 | | -For many applications, the desired behavior is to *only* handle messages that are |
40 | | -dispatched by a handler once that handler has fully finished. This can be by using the |
41 | | -``DispatchAfterCurrentBusMiddleware`` middleware and adding a ``DispatchAfterCurrentBusStamp`` |
42 | | -stamp to `the message Envelope</components/messenger#adding-metadata-to-messages-envelopes>`_. |
43 | | - |
44 | | -..code-block::php |
| 42 | +For many applications, the desired behavior is to *only* handle messages that |
| 43 | +are dispatched by a handler once that handler has fully finished. This can be by |
| 44 | +using the ``DispatchAfterCurrentBusMiddleware`` and adding a |
| 45 | +``DispatchAfterCurrentBusStamp`` stamp to |
| 46 | +`the message Envelope</components/messenger#adding-metadata-to-messages-envelopes>`_:: |
45 | 47 |
|
46 | 48 | namespace App\Messenger\CommandHandler; |
47 | 49 |
|
@@ -111,20 +113,23 @@ stamp to `the message Envelope </components/messenger#adding-metadata-to-message |
111 | 113 | } |
112 | 114 | } |
113 | 115 |
|
114 | | -This means that the ``UserRegistered`` message would not be handled |
115 | | -until *after* the ``RegisterUserHandler`` had completed and the new ``User`` was persisted to the |
116 | | -database. If the ``RegisterUserHandler`` encounters an exception, the ``UserRegistered`` event will |
117 | | -never be handled. And if an exception is thrown while sending the welcome email, the Doctrine |
118 | | -transaction will not be rolled back. |
| 116 | +This means that the ``UserRegistered`` message would not be handled until |
| 117 | +*after* the ``RegisterUserHandler`` had completed and the new ``User`` was |
| 118 | +persisted to the database. If the ``RegisterUserHandler`` encounters an |
| 119 | +exception, the ``UserRegistered`` event will never be handled. And if an |
| 120 | +exception is thrown while sending the welcome email, the Doctrine transaction |
| 121 | +will not be rolled back. |
119 | 122 |
|
120 | 123 | ..note:: |
121 | 124 |
|
122 | | - If ``WhenUserRegisteredThenSendWelcomeEmail`` throws an exception, that exception |
123 | | - will be wrapped into a ``DelayedMessageHandlingException``. Using ``DelayedMessageHandlingException::getExceptions`` |
124 | | - will give you all exceptions that are thrown while handing a message with the ``DispatchAfterCurrentBusStamp``. |
| 125 | + If ``WhenUserRegisteredThenSendWelcomeEmail`` throws an exception, that |
| 126 | + exception will be wrapped into a ``DelayedMessageHandlingException``. Using |
| 127 | + ``DelayedMessageHandlingException::getExceptions`` will give you all |
| 128 | + exceptions that are thrown while handing a message with the |
| 129 | + ``DispatchAfterCurrentBusStamp``. |
125 | 130 |
|
126 | | -The``dispatch_after_current_bus`` middleware is enabled by default. If you're |
| 131 | +The ``dispatch_after_current_bus`` middleware is enabled by default. If you're |
127 | 132 | configuring your middleware manually, be sure to register |
128 | 133 | ``dispatch_after_current_bus`` before ``doctrine_transaction`` in the middleware |
129 | | -chain. Also, the ``dispatch_after_current_bus`` middleware must be loaded for *all* of |
130 | | -the buses being used. |
| 134 | +chain. Also, the ``dispatch_after_current_bus`` middleware must be loaded for |
| 135 | +*all* ofthe buses being used. |