From 288002748764707d27e3ca041390f780d86ca679 Mon Sep 17 00:00:00 2001 From: Maxime Steinhausser Date: Tue, 15 May 2018 10:10:10 +0200 Subject: [PATCH 1/3] [Messenger] Document middleware factories --- messenger.rst | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/messenger.rst b/messenger.rst index ed73d148ae2..fd3c826b75b 100644 --- a/messenger.rst +++ b/messenger.rst @@ -273,6 +273,114 @@ 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: + +.. 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 + + + + + + + + + + + + custom + + + + + + + .. 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 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 ------------------ From a87f21b604bf38a8688f0d3f5c4fc60634d915d3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 May 2018 17:25:02 +0200 Subject: [PATCH 2/3] Minor rewords --- messenger.rst | 56 ++++++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/messenger.rst b/messenger.rst index fd3c826b75b..352a5399285 100644 --- a/messenger.rst +++ b/messenger.rst @@ -276,37 +276,37 @@ you can disable them like this: 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: +Sometimes middleware are configurable using factories. There are two types of +factories and they are based on Symfony's :doc:`dependency injection ` +features: .. code-block:: yaml services: - # A factory class is registered as a service with required dependencies - # to instantiate a middleware: + # Type 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'] + 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: + # Type 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. - # i.e: - # middleware: - # - doctrine_transaction_middleware: ~ - arguments: ['default'] + 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 corresponds to the entity manager name to use, as expected by the -``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method as argument. +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: +Then you can reference and configure the +``messenger.middleware.doctrine_transaction_middleware`` service as a middleware: .. configuration-block:: @@ -368,18 +368,20 @@ service as a middleware: .. note:: -   The shorthand ``doctrine_transaction_middleware`` name can be used by convention, - as the service id is prefixed with the ``messenger.middleware.`` namespace. + 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 service reference). - For most advanced use-cases, register a concrete definition of the middleware yourself and use its id. + 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 an existing middleware wired - by the DoctrineBundle if installed and the Messenger component enabled. + 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 ------------------ From c5ef7c87df1bb7f60be8b0cfbde73317439853ba Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 24 May 2018 09:13:51 +0200 Subject: [PATCH 3/3] Reowrd to restore the original meaning --- messenger.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/messenger.rst b/messenger.rst index 352a5399285..5d6e4437a14 100644 --- a/messenger.rst +++ b/messenger.rst @@ -276,22 +276,22 @@ you can disable them like this: Using Middleware Factories ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sometimes middleware are configurable using factories. There are two types of -factories and they are based on Symfony's :doc:`dependency injection ` -features: +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 ` features: .. code-block:: yaml services: - # Type 1: a factory class is registered as a service with the required + # 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'] - # Type 2: an abstract definition that will call the factory with default arguments - # or the one provided in the middleware config + # 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']