[Messenger] Document middleware factories

ogizanagi · ogizanagi · commit 17dae2f1ebef · 2018-05-15T10:14:57.000+02:00
diff --git a/messenger.rst b/messenger.rst
@@ -273,6 +273,68 @@ you can disable them like this:
                 messenger.bus.default:
                     default_middleware: false
 
+Using middleware factories
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some third-parties may expose you configurable middleware by using factories.
+Such factories are actually relying on the Symfony DI capabilities and consist
+of this kind of two services:
+
+.. code-block:: yaml
+
+    services:
+
+        # A factory class is registered as a service with required dependencies
+        # to instantiate a middleware:
+        doctrine.orm.messenger.middleware_factory.transaction:
+          class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory
+          arguments: ['@doctrine']
+
+        # 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.
+          # i.e:
+          #   middleware:
+          #     - doctrine_transaction_middleware: ~
+          arguments: ['default']
+
+The "default" value in this example corresponds to the entity manager name to use, as expected by the
+``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method as argument.
+
+Then you can reference and configure the ``messenger.middleware.doctrine_transaction_middleware``
+service as a middleware:
+
+.. code-block:: yaml
+
+    framework:
+        messenger:
+            buses:
+                command_bus:
+                    middleware:
+                        # Using defaults:
+                        - doctrine_transaction_middleware
+                        # Using another entity manager:
+                        - doctrine_transaction_middleware: ['custom']
+
+.. note::
+
+    The shorthand ``doctrine_transaction_middleware`` name can be used by convention,
+    as the service id is prefixed with the ``messenger.middleware.`` namespace.
+
+.. note::
+
+    Middleware factories only allow scalar and array arguments in config (no service reference).
+    For most advanced use-cases, register a concrete definition of the middleware yourself and use its id.
+
+.. tip::
+
+    The ``doctrine_transaction_middleware`` is an existing middleware wired
+    by the DoctrineBundle if installed and the Messenger component enabled.
+
 Your own Transport
 ------------------
 
