..index::

single: Messenger; Record messages

single: Messenger; Record messages; Transaction messages

Events Recorder: Handle Events After CommandHandler Is Done

Transactional Messages: Handle Events After CommandHandler Is Done

a ``User`` object, stores thatobject to a database and dispatches a ``UserCreated`` event.

Any errors or exceptions thatoccur during this process can have unintended consequences,

There are many subscribers to the ``UserCreated`` event, one subscriber may send

- If using the ``DoctrineTransactionMiddleware`` and a dispatched message to the same bus

and an exception is thrown, then any database transactions in the original handler will

be rolled back.

- If the message is dispatched to a different bus, then the dispatched message can still

be handled even if the original handler encounters an exception.

An Example ``SignUpUser`` Process

Let's take the example of an application with both a *command* and an *event* bus. The application

dispatches a command named ``SignUpUser`` to the command bus. The command is handled by the

``SignUpUserHandler`` which creates a ``User`` object, stores that object to a database and

dispatches a ``UserSignedUp`` event to the event bus.

There are many subscribers to the ``UserSignedUp`` event, one subscriber may send

a welcome email to the new user. We are using the ``DoctrineTransactionMiddleware``

to wrap all database queries in one database transaction.

**Problem:** If an exception is thrown when sending the welcome email, then the user

**Problem 1:** If an exception is thrown when sending the welcome email, then the user

will not be created because the ``DoctrineTransactionMiddleware`` will rollback the

Doctrine transaction, in which the user has been created.

**Solution:** The solution is to not dispatch the ``UserCreated`` event in the

``CreateUserHandler`` but to just "record" the events. The recorded events will

be dispatched after ``DoctrineTransactionMiddleware`` has committed the transaction.

**Problem 2:** If an exception is thrown when saving the user to the database, the welcome

email is still sent.

``HandleMessageInNewTransaction`` Middleware

For many applications, the desired behavior is to have any messages dispatched by the handler

to `only` be handled after the handler finishes. This can be by using the

``HandleMessageInNewTransaction`` middleware and adding a ``Transaction`` stamp to

`the message Envelope</components/messenger#adding-metadata-to-messages-envelopes>`_.

This middleware enables us to add messages to a separate transaction that will only be

dispatched *after* the current message handler finishes.

To enable this, you simply just add the ``messenger.middleware.handles_recorded_messages``

Referencing the above example, this means that the ``UserSignedUp`` event would not be handled

until *after* the ``SignUpUserHandler`` had completed and the new ``User`` was persisted to the

database. If the ``SignUpUserHandler`` encounters an exception, the ``UserSignedUp`` event will

never be handled and if an exception is thrown while sending the welcome email, the Doctrine

transaction will not be rolled back.

To enable this, you need to add the ``handle_message_in_new_transaction``

middleware. Make sure it is registered before ``DoctrineTransactionMiddleware``

in the middleware chain.

**Note:** The ``handle_message_in_new_transaction`` middleware must be loaded for *all* of the

buses. For the example, the middleware must be loaded for both the command and event buses.

..configuration-block::

..code-block::yaml

..code-block::php