From da034d20758f48a666d5c329b717fdc17a744c3f Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Sun, 17 Sep 2017 15:13:23 +0200 Subject: [PATCH 1/9] Docs for referencing tagged services in config --- service_container/tags.rst | 89 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/service_container/tags.rst b/service_container/tags.rst index cc8d14ae512..f629965d0e2 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -405,3 +405,92 @@ The double loop may be confusing. This is because a service can have more than one tag. You tag a service twice or more with the ``app.mail_transport`` tag. The second foreach loop iterates over the ``app.mail_transport`` tags set for the current service and gives you the attributes. + +Reference tagged services +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case your tag doesn't require any further additional attributes writing compiler +passes per tag might become tedious. A way to overcome this is is to make your compiler +pass more generic. The downside of this approach is you have to write and maintain +additional code, considering you want to reuse it over multiple projects. + +ThereBecause this task is so generic and common to do, Symfony provides a way to achieve this +directly in your service container confguration. This enables to inject services tagged +with e.g. `app.handler` into another service that collects all handlers. + +.. configuration-block:: + + .. code-block:: yaml + + services: + App\Handler\One: + tags: [app.handler] + + App\Handler\Two: + tags: [app.handler] + + App\HandlerCollection: + arguments: [!tagged app.handler] + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + .. code-block:: php + + use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument; + + $container->register(\App\Handler\One::class) + ->addTag('app.handler'); + + $container->register(\App\Handler\One::class) + ->addTag('app.handler'); + + $container->register(\App\HandlerCollection::class) + ->addArgument(new TaggedIteratorArgument('app.handler')); + +After compilation the `HandlerCollection` service is able to iterate over your application handlers. + + .. code-block:: php + + class HandlerCollection + { + public function __construct(iterable $handlers) + { + } + } + +.. tip:: + + The collected services can be prioritized using the `priority` attribute. + + .. code-block:: yaml + + services: + App\Handler\One: + tags: + - { name: app.handler, priority: 20 } + +.. versionadded:: 3.4 + + Support for the tagged service notation in YAML, XML and PHP was introduced + in Symfony 3.4. From 61c74da6e5cca4b6602101c5bb9791d2b1f0ed8d Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Tue, 3 Oct 2017 20:56:05 +0200 Subject: [PATCH 2/9] Update tags.rst --- service_container/tags.rst | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index f629965d0e2..ae19f32a830 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -406,17 +406,21 @@ than one tag. You tag a service twice or more with the ``app.mail_transport`` tag. The second foreach loop iterates over the ``app.mail_transport`` tags set for the current service and gives you the attributes. -Reference tagged services +Reference Tagged Services ~~~~~~~~~~~~~~~~~~~~~~~~~ -In case your tag doesn't require any further additional attributes writing compiler -passes per tag might become tedious. A way to overcome this is is to make your compiler -pass more generic. The downside of this approach is you have to write and maintain -additional code, considering you want to reuse it over multiple projects. +.. versionadded:: 3.4 + + Support for the tagged service notation in YAML, XML and PHP was introduced + in Symfony 3.4. -ThereBecause this task is so generic and common to do, Symfony provides a way to achieve this -directly in your service container confguration. This enables to inject services tagged -with e.g. `app.handler` into another service that collects all handlers. +If you use tags to inject a list of services as an argument, writing a compiler +pass is a bit tedious. As this is a very common case, Symfony provides a way to +inject all services tagged with a specific tag. + +The downside of this feature is that you can't have any custom attributes. In the +example below, all services tagged with app.handler are passed in an array as the +first constructor argument to the ``App\HandlerCollection`` service: .. configuration-block:: @@ -430,6 +434,7 @@ with e.g. `app.handler` into another service that collects all handlers. tags: [app.handler] App\HandlerCollection: + # inject all services tagged with app.handler as first argument arguments: [!tagged app.handler] .. code-block:: xml @@ -450,6 +455,7 @@ with e.g. `app.handler` into another service that collects all handlers. + @@ -466,18 +472,19 @@ with e.g. `app.handler` into another service that collects all handlers. ->addTag('app.handler'); $container->register(\App\HandlerCollection::class) + // inject all services tagged with app.handler as first argument ->addArgument(new TaggedIteratorArgument('app.handler')); After compilation the `HandlerCollection` service is able to iterate over your application handlers. - .. code-block:: php +.. code-block:: php - class HandlerCollection + class HandlerCollection + { + public function __construct(iterable $handlers) { - public function __construct(iterable $handlers) - { - } } + } .. tip:: @@ -489,8 +496,3 @@ After compilation the `HandlerCollection` service is able to iterate over your a App\Handler\One: tags: - { name: app.handler, priority: 20 } - -.. versionadded:: 3.4 - - Support for the tagged service notation in YAML, XML and PHP was introduced - in Symfony 3.4. From 71158f8d709c9c2ff7ccc00e8fd1037d3a17c86a Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Tue, 3 Oct 2017 21:08:49 +0200 Subject: [PATCH 3/9] Update tags.rst --- service_container/tags.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index ae19f32a830..d47c97f3485 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -419,8 +419,8 @@ pass is a bit tedious. As this is a very common case, Symfony provides a way to inject all services tagged with a specific tag. The downside of this feature is that you can't have any custom attributes. In the -example below, all services tagged with app.handler are passed in an array as the -first constructor argument to the ``App\HandlerCollection`` service: +example below, all services tagged with ``app.handler`` are passed as first +constructor argument to the ``App\HandlerCollection`` service: .. configuration-block:: From 0aaf48b0511157d63b3e2b1252f6de04940c9737 Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Tue, 3 Oct 2017 21:11:42 +0200 Subject: [PATCH 4/9] Update tags.rst --- service_container/tags.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index d47c97f3485..7b261c3a4ea 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -468,14 +468,14 @@ constructor argument to the ``App\HandlerCollection`` service: $container->register(\App\Handler\One::class) ->addTag('app.handler'); - $container->register(\App\Handler\One::class) + $container->register(\App\Handler\Two::class) ->addTag('app.handler'); $container->register(\App\HandlerCollection::class) // inject all services tagged with app.handler as first argument ->addArgument(new TaggedIteratorArgument('app.handler')); -After compilation the `HandlerCollection` service is able to iterate over your application handlers. +After compilation the ``HandlerCollection`` service is able to iterate over your application handlers. .. code-block:: php From 000b80104ee33517b38aa53bc823a699bd3c1327 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 4 Oct 2017 12:39:13 +0200 Subject: [PATCH 5/9] Minor reword and fixes --- service_container/tags.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index 7b261c3a4ea..d4cb3ea0d49 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -410,17 +410,16 @@ Reference Tagged Services ~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 3.4 - Support for the tagged service notation in YAML, XML and PHP was introduced in Symfony 3.4. -If you use tags to inject a list of services as an argument, writing a compiler -pass is a bit tedious. As this is a very common case, Symfony provides a way to -inject all services tagged with a specific tag. +Symfony provides a shortcut to inject all services tagged with a specific tag, +which is a common need in some applications, so you don't have to write a +compiler pass just for that. The only downside of this feature is that you can't +have any custom attributes. -The downside of this feature is that you can't have any custom attributes. In the -example below, all services tagged with ``app.handler`` are passed as first -constructor argument to the ``App\HandlerCollection`` service: +In the following example, all services tagged with ``app.handler`` are passed as +first constructor argument to the ``App\HandlerCollection`` service: .. configuration-block:: @@ -475,7 +474,8 @@ constructor argument to the ``App\HandlerCollection`` service: // inject all services tagged with app.handler as first argument ->addArgument(new TaggedIteratorArgument('app.handler')); -After compilation the ``HandlerCollection`` service is able to iterate over your application handlers. +After compilation the ``HandlerCollection`` service is able to iterate over your +application handlers. .. code-block:: php @@ -488,7 +488,7 @@ After compilation the ``HandlerCollection`` service is able to iterate over your .. tip:: - The collected services can be prioritized using the `priority` attribute. + The collected services can be prioritized using the ``priority`` attribute. .. code-block:: yaml From a2fd23f2eacaf13b490ee7884717b24cbd31b621 Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Thu, 5 Oct 2017 21:11:20 +0200 Subject: [PATCH 6/9] Update tags.rst --- service_container/tags.rst | 47 ++++++++++++++++++++++++++++++-------- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index d4cb3ea0d49..3a88c6377e1 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -425,6 +425,7 @@ first constructor argument to the ``App\HandlerCollection`` service: .. code-block:: yaml + # app/config/services.yml services: App\Handler\One: tags: [app.handler] @@ -438,6 +439,7 @@ first constructor argument to the ``App\HandlerCollection`` service: .. code-block:: xml + register(\App\Handler\One::class) + $container->register(App\Handler\One::class) ->addTag('app.handler'); - $container->register(\App\Handler\Two::class) + $container->register(App\Handler\Two::class) ->addTag('app.handler'); - $container->register(\App\HandlerCollection::class) + $container->register(App\HandlerCollection::class) // inject all services tagged with app.handler as first argument ->addArgument(new TaggedIteratorArgument('app.handler')); @@ -488,11 +491,37 @@ application handlers. .. tip:: - The collected services can be prioritized using the ``priority`` attribute. + The collected services can be prioritized using the ``priority`` attribute: - .. code-block:: yaml + + .. configuration-block:: - services: - App\Handler\One: - tags: - - { name: app.handler, priority: 20 } + .. code-block:: yaml + + # app/config/services.yml + services: + App\Handler\One: + tags: + - { name: app.handler, priority: 20 } + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/services.php + $container->register(App\Handler\One::class) + ->addTag('app.handler', array('priority' => 20)); From 564b5ea523d6d6a69f082937fdbb45851aa95057 Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Thu, 5 Oct 2017 21:12:01 +0200 Subject: [PATCH 7/9] Update tags.rst --- service_container/tags.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index 3a88c6377e1..541c12ac48e 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -493,7 +493,6 @@ application handlers. The collected services can be prioritized using the ``priority`` attribute: - .. configuration-block:: .. code-block:: yaml From 2e5c87f0e64a6c588251e0479fff3ea4e25e4d48 Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Thu, 5 Oct 2017 21:23:15 +0200 Subject: [PATCH 8/9] Update tags.rst --- service_container/tags.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index 541c12ac48e..a4fa422ba2d 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -415,8 +415,7 @@ Reference Tagged Services Symfony provides a shortcut to inject all services tagged with a specific tag, which is a common need in some applications, so you don't have to write a -compiler pass just for that. The only downside of this feature is that you can't -have any custom attributes. +compiler pass just for that. In the following example, all services tagged with ``app.handler`` are passed as first constructor argument to the ``App\HandlerCollection`` service: @@ -524,3 +523,6 @@ application handlers. // app/config/services.php $container->register(App\Handler\One::class) ->addTag('app.handler', array('priority' => 20)); + + Note that any other custom attributes will be ignored by this feature. + From ed70659207f4cf7181e47ad6d31d7efa798afcba Mon Sep 17 00:00:00 2001 From: Roland Franssen Date: Fri, 6 Oct 2017 11:38:07 +0200 Subject: [PATCH 9/9] Update tags.rst --- service_container/tags.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/service_container/tags.rst b/service_container/tags.rst index a4fa422ba2d..ea4dbe151b3 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -426,13 +426,13 @@ first constructor argument to the ``App\HandlerCollection`` service: # app/config/services.yml services: - App\Handler\One: + AppBundle\Handler\One: tags: [app.handler] - App\Handler\Two: + AppBundle\Handler\Two: tags: [app.handler] - App\HandlerCollection: + AppBundle\HandlerCollection: # inject all services tagged with app.handler as first argument arguments: [!tagged app.handler] @@ -446,15 +446,15 @@ first constructor argument to the ``App\HandlerCollection`` service: http://symfony.com/schema/dic/services/services-1.0.xsd"> - + - + - + @@ -466,13 +466,13 @@ first constructor argument to the ``App\HandlerCollection`` service: // app/config/services.php use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument; - $container->register(App\Handler\One::class) + $container->register(AppBundle\Handler\One::class) ->addTag('app.handler'); - $container->register(App\Handler\Two::class) + $container->register(AppBundle\Handler\Two::class) ->addTag('app.handler'); - $container->register(App\HandlerCollection::class) + $container->register(AppBundle\HandlerCollection::class) // inject all services tagged with app.handler as first argument ->addArgument(new TaggedIteratorArgument('app.handler')); @@ -481,6 +481,9 @@ application handlers. .. code-block:: php + // src/AppBundle/HandlerCollection.php + namespace AppBundle; + class HandlerCollection { public function __construct(iterable $handlers) @@ -498,7 +501,7 @@ application handlers. # app/config/services.yml services: - App\Handler\One: + AppBundle\Handler\One: tags: - { name: app.handler, priority: 20 } @@ -512,7 +515,7 @@ application handlers. http://symfony.com/schema/dic/services/services-1.0.xsd"> - + @@ -521,8 +524,7 @@ application handlers. .. code-block:: php // app/config/services.php - $container->register(App\Handler\One::class) + $container->register(AppBundle\Handler\One::class) ->addTag('app.handler', array('priority' => 20)); Note that any other custom attributes will be ignored by this feature. -