[Messenger] Show how to configure a doctrine transaction middleware

[Nyholm]

This will fix #9651

This is a first draft. Please add a quick review and after that I'll add code blocks for PHP and XML.

I use the title "Working with doctrine" because I believe we should mention the DispatchAfterCurrentBusMiddleware on this page as well. (Code PR, Doc PR) and the "recording" from entities (Code PR)

[ogizanagi]

It looks great!...but we already mentioned the transaction middleware briefly in https://symfony.com/doc/current/messenger.html#using-middleware-factories where we explain middleware factories.
But having this dedicated docs really makes sense. However end-users should not have to deal with the factories themselves for this middleware as everything should be wired by the DoctrineBundle. So it could be actually simplified but doctrine/DoctrineBundle#817 isn't merged yet :'(

Users are supposed to be able to just use:

        framework:
            messenger:
                buses:
                    command_bus:
                        middleware:
                            # Using default entity manager
                            - doctrine_transaction_middleware
                            # Using "custom" entity manager
                            - doctrine_transaction_middleware: ['custom']

[Nyholm]

Oh, I've missed that entire page of documentation!

Okey, Lets wait for doctrine/DoctrineBundle#817

[Nyholm]

Now when the doctrine PR is merge, I will update these docs to the new config syntax, right?

[Nyholm]

This PR is updated.
Ping @sroze

[sroze]

Looks good to me (except these two changes) 👍

[Nyholm]

Thank you for the review. I've updated the RP

[weaverryan]

My instinct is that this should be included in the main doc, but we can figure that out later. I added one real question.

Also, correct me if I'm wrong, isn't this only relevant if you have multiple handlers that are doing flushes? So the transaction would roll back all of them (instead of some working and others not working)? I want it to be clear when a user should definitely use this versus when it won't make any difference for them.

[weaverryan]

are we purposely also including validation?

[ogizanagi]

That's a bit unrelated with the content of this doc indeed, but a good practice, as content of the command in a CQRS application are most of the input by users (on contrary of events which are mostly crafted by developers from already validated data).

[ogizanagi]

@weaverryan

Also, correct me if I'm wrong, isn't this only relevant if you have multiple handlers that are doing flushes?

No it's relevant even with a single command bus and single handler for the message, so you don't have to deal with flushing changes yourself, nor you can commit changes partially to the database if a command handler failed at some point, rollbacking any change.

[OskarStark]

Friendly ping @Nyholm 🎶 👋

Could you please find some time and finish this PR? Thank you 🙏

[javiereguiluz]

I'm closing this old pull request because we already mention the doctrine_transaction in the main Messenger article (see https://symfony.com/doc/current/messenger.html#middleware-for-doctrine) so this is probably no longer needed. Thanks.