minor #9774 [Messenger] Document middleware factories (ogizanagi, jav…

…iereguiluz)

This PR was merged into the 4.1 branch.

Discussion
----------

[Messenger] Document middleware factories

<!--

If your pull request fixes a BUG, use the oldest maintained branch that contains
the bug (see https://symfony.com/roadmap for the list of maintained branches).

If your pull request documents a NEW FEATURE, use the same Symfony branch where
the feature was introduced (and `master` for features of unreleased versions).

-->

Refs:

- Symfony PR: symfony/symfony#27128
- DoctrineBundle PR: doctrine/DoctrineBundle#817

Commits
-------

c5ef7c8 Reowrd to restore the original meaning
a87f21b Minor rewords
2880027 [Messenger] Document middleware factories

messenger.rst

@@ -273,6 +273,116 @@ you can disable them like this:
                 messenger.bus.default:
                     default_middleware: false
 
+Using Middleware Factories
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some third-party bundles and libraries provide configurable middleware via
+factories. Using them requires a two-step configuration based on Symfony's
+:doc:`dependency injection </service_container>` features:
+
+.. code-block:: yaml
+
+    services:
+
+        # Step 1: a factory class is registered as a service with the required
+        # dependencies to instantiate a middleware
+        doctrine.orm.messenger.middleware_factory.transaction:
+            class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory
+            arguments: ['@doctrine']
+
+        # Step 2: an abstract definition that will call the factory with default
+        # arguments or the one provided in the middleware config
+        messenger.middleware.doctrine_transaction_middleware:
+            class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware
+            factory: ['@doctrine.orm.messenger.middleware_factory.transaction', 'createMiddleware']
+            abstract: true
+            # the default arguments to use when none provided from config. Example:
+            # middleware:
+            #     - doctrine_transaction_middleware: ~
+            arguments: ['default']
+
+The "default" value in this example is the name of the entity manager to use,
+which is the argument expected by the
+``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method.
+
+Then you can reference and configure the
+``messenger.middleware.doctrine_transaction_middleware`` service as a middleware:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                buses:
+                    command_bus:
+                        middleware:
+                            # Using defaults:
+                            - doctrine_transaction_middleware
+                            # Using another entity manager:
+                            - doctrine_transaction_middleware: ['custom']
+
+    .. code-block:: xml
+
+        <!-- config/packages/messenger.xml -->
+        <container xmlns="http://symfony.com/schema/dic/symfony"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:messenger>
+                    <framework:bus name="command_bus">
+                        <!-- Using defaults: -->
+                        <framework:middleware id="doctrine_transaction_middleware" />
+                        <!-- Using another entity manager -->
+                        <framework:middleware id="doctrine_transaction_middleware">
+                            <framework:argument>custom</framework:argument>
+                        </framework:middleware>
+                    </framework:bus>
+                </framework:messenger>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/messenger.php
+        $container->loadFromExtension('framework', array(
+            'messenger' => array(
+                'buses' => array(
+                    'command_bus' => array(
+                        'middleware' => array(
+                            // Using defaults:
+                            'doctrine_transaction_middleware',
+                            // Using another entity manager
+                            array('id' => 'doctrine_transaction_middleware', 'arguments' => array('custom')),
+                        ),
+                    ),
+                ),
+            ),
+        ));
+
+.. note::
+
+    The ``doctrine_transaction_middleware`` shortcut is a convention. The real
+    service id is prefixed with the ``messenger.middleware.`` namespace.
+
+.. note::
+
+    Middleware factories only allow scalar and array arguments in config (no
+    references to other services). For most advanced use-cases, register a
+    concrete definition of the middleware manually and use its id.
+
+.. tip::
+
+    The ``doctrine_transaction_middleware`` is a built-in middleware wired
+    automatically when the DoctrineBundle and the Messenger component are
+    installed and enabled.
+
 Your own Transport
 ------------------