Docs for referencing tagged services in config #8404

ro0NL · 2017-09-17T13:14:08Z

Curious how it looks :) also a bit related to #8403

wouterj

Thanks for writing the docs @ro0NL! I've left some comments, can you have a look at them (feel free to change or comment on all my suggestions)

wouterj · 2017-09-19T11:28:37Z

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


"Reference Tagged Services" (title case uppercases almost every word, except when there are closed words)

wouterj · 2017-09-19T11:29:42Z

service_container/tags.rst

+
+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.


Inline code blocks should be surrounded by double backticks (single backticks are used for references)

wouterj · 2017-09-19T11:30:25Z

service_container/tags.rst

+                tags: [app.handler]
+
+            App\HandlerCollection:
+                arguments: [!tagged app.handler]


Let's put a comment here describing that this is passing all services tagged with app.handler as an array argument to this class. (Same for the other formats)

wouterj · 2017-09-19T11:30:58Z

service_container/tags.rst

+            public function __construct(iterable $handlers)
+            {
+            }
+        }


This block should be moved 4 spaces to the left (the .. code-block:: php part should be in column 0)

wouterj · 2017-09-19T11:31:27Z

service_container/tags.rst

+                    - { name: app.handler, priority: 20 }
+
+.. versionadded:: 3.4
+


This line should be removed (versionadded is a really strange directive). And let's move this to just below the section title

wouterj · 2017-09-19T11:35:19Z

service_container/tags.rst

+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.


I don't think we need so much information and we're kinda missing the complete feature here: Using tags to inject a list of services to another service. Tags can do non-injecting stuff as well. What about saying something like: (change at your free will 😄 )

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:

agree. this text is good as a blog post introducing this new feature as it explains the thought process. but it does not fit as a feature documention

This PR was merged into the 3.4 branch. Discussion ---------- [DI] Reference tagged services in config | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #12269 | License | MIT | Doc PR | symfony/symfony-docs#8404 This is a proof of concept to reference a sequence of tagged services. The problem bugs me for some time, and at first i thought the solution was to have some super generic compiler pass. If it could replace a lot of compilers in core.. perhaps worth it, but eventually each tag comes with it's own logic, including how to deal with tag attributes. However, writing the passes over and over again becomes tedious for the most basic usecase. So given the recent developments, this idea came to mind. ```yml services: a: class: stdClass properties: { a: true } tags: [foo] b: class: stdClass properties: { b: true } tags: [foo] c: class: stdClass properties: #stds: !tagged_services foo (see #22198) stds: !tagged_services foo ``` ``` dump(iterator_to_array($this->get('c')->stds)); ``` ``` array:2 [▼ 0 => {#5052 ▼ +"a": true } 1 => {#4667 ▼ +"b": true } ] ``` Given the _basic_ example at https://symfony.com/doc/current/service_container/tags.html, this could replace that. Any thoughts? Commits ------- 979e58f [DI] Reference tagged services in config

This PR was merged into the 3.4 branch. Discussion ---------- [DI] Reference tagged services in config | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #12269 | License | MIT | Doc PR | symfony/symfony-docs#8404 This is a proof of concept to reference a sequence of tagged services. The problem bugs me for some time, and at first i thought the solution was to have some super generic compiler pass. If it could replace a lot of compilers in core.. perhaps worth it, but eventually each tag comes with it's own logic, including how to deal with tag attributes. However, writing the passes over and over again becomes tedious for the most basic usecase. So given the recent developments, this idea came to mind. ```yml services: a: class: stdClass properties: { a: true } tags: [foo] b: class: stdClass properties: { b: true } tags: [foo] c: class: stdClass properties: #stds: !tagged_services foo (see #22198) stds: !tagged_services foo ``` ``` dump(iterator_to_array($this->get('c')->stds)); ``` ``` array:2 [▼ 0 => {#5052 ▼ +"a": true } 1 => {#4667 ▼ +"b": true } ] ``` Given the _basic_ example at https://symfony.com/doc/current/service_container/tags.html, this could replace that. Any thoughts? Commits ------- 979e58f [DI] Reference tagged services in config

ro0NL · 2017-10-03T19:12:44Z

ping @wouterj comments addressed :)

Tobion · 2017-10-04T09:57:12Z

IMO it should be mentioned the passed iterable is a generator that loads each service lazily when iterating.

wouterj

Looks good!

wouterj · 2017-10-04T10:18:48Z

service_container/tags.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.4
+


This empty line should be removed, otherwise the directive doesn't work (versionadded is weird)

wouterj · 2017-10-04T10:19:16Z

service_container/tags.rst

+
+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:


We'll have to look at platformsh, but I think we need a double \\ here.

javiereguiluz

I have a question about this phrase:

The only downside of this feature is that you can't
have any custom attributes.

Could you please explain a bit more what does it mean? Thanks!

ro0NL · 2017-10-04T11:11:10Z

Agree. You can have them, however you cant leverage them with this specific feature. That needs to be clarified yes.

Status: needs work

xabbuh · 2017-10-05T11:22:43Z

service_container/tags.rst

+
+   The collected services can be prioritized using the ``priority`` attribute.
+
+    .. code-block:: yaml


We are missing XML and PHP examples. :)

xabbuh · 2017-10-05T11:22:53Z

service_container/tags.rst

+
+.. tip::
+
+   The collected services can be prioritized using the ``priority`` attribute.


the sentence could end with a colon

xabbuh · 2017-10-05T11:23:18Z

service_container/tags.rst

+        $container->register(\App\Handler\Two::class)
+            ->addTag('app.handler');
+
+        $container->register(\App\HandlerCollection::class)


the leading backslash should be removed eveyrwhere

xabbuh · 2017-10-05T11:23:59Z

service_container/tags.rst

+
+    .. code-block:: yaml
+
+        services:


missing filename comment (same for the other formats):

# app/config/services.yml

ro0NL · 2017-10-05T19:24:27Z

Last commit 2e5c87f addresses @javiereguiluz comment.

xabbuh · 2017-10-06T08:24:46Z

service_container/tags.rst

+                ->addTag('app.handler', array('priority' => 20));
+
+    Note that any other custom attributes will be ignored by this feature.
+


trailing blank line should be removed

xabbuh · 2017-10-06T08:25:10Z

service_container/tags.rst

+
+        # app/config/services.yml
+        services:
+            App\Handler\One:


I think we should still use examples from the AppBundle namespace

That's right. We'll remove AppBundle in 4.0, but we must still use it in 3.4.

xabbuh · 2017-10-06T08:25:25Z

service_container/tags.rst

+
+.. code-block:: php
+
+    class HandlerCollection


missing namespace and filename comment

xabbuh

I just left a few minor comments, but apart from that this looks good to me.

xabbuh · 2017-10-13T07:01:21Z

Thank you @ro0NL.

…javiereguiluz) This PR was merged into the 3.4 branch. Discussion ---------- Docs for referencing tagged services in config See symfony/symfony#22200 Curious how it looks :) also a bit related to #8403 Commits ------- ed70659 Update tags.rst 2e5c87f Update tags.rst 564b5ea Update tags.rst a2fd23f Update tags.rst 000b801 Minor reword and fixes 0aaf48b Update tags.rst 71158f8 Update tags.rst 61c74da Update tags.rst da034d2 Docs for referencing tagged services in config

Docs for referencing tagged services in config

da034d2

carsonbot added the Status: Needs Review label Sep 17, 2017

ro0NL mentioned this pull request Sep 17, 2017

[DI] Reference tagged services in config symfony/symfony#22200

Merged

wouterj requested changes Sep 19, 2017

View reviewed changes

wouterj added Status: Needs Work and removed Status: Needs Review labels Sep 19, 2017

xabbuh mentioned this pull request Sep 28, 2017

Ability to reference tagged services #8436

Closed

Update tags.rst

61c74da

carsonbot added Status: Needs Review and removed Status: Needs Work labels Oct 3, 2017

ro0NL added 2 commits October 3, 2017 21:08

Update tags.rst

71158f8

Update tags.rst

0aaf48b

wouterj approved these changes Oct 4, 2017

View reviewed changes

Minor reword and fixes

000b801

javiereguiluz reviewed Oct 4, 2017

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels Oct 4, 2017

xabbuh reviewed Oct 5, 2017

View reviewed changes

Update tags.rst

a2fd23f

carsonbot added Status: Needs Review and removed Status: Needs Work labels Oct 5, 2017

ro0NL added 2 commits October 5, 2017 21:12

Update tags.rst

564b5ea

Update tags.rst

2e5c87f

xabbuh reviewed Oct 6, 2017

View reviewed changes

service_container/tags.rst Outdated

.. code-block:: php

class HandlerCollection

Copy link

Member

xabbuh Oct 6, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing namespace and filename comment

xabbuh approved these changes Oct 6, 2017

View reviewed changes

xabbuh added Status: Reviewed and removed Status: Needs Review labels Oct 6, 2017

xabbuh added this to the 3.4 milestone Oct 6, 2017

Update tags.rst

ed70659

xabbuh merged commit ed70659 into symfony:3.4 Oct 13, 2017

ro0NL deleted the patch-2 branch October 13, 2017 07:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs for referencing tagged services in config #8404

Docs for referencing tagged services in config #8404

ro0NL commented Sep 17, 2017

wouterj left a comment

wouterj Sep 19, 2017

wouterj Sep 19, 2017

wouterj Sep 19, 2017

wouterj Sep 19, 2017

wouterj Sep 19, 2017

wouterj Sep 19, 2017

Tobion Sep 29, 2017

ro0NL commented Oct 3, 2017

Tobion commented Oct 4, 2017 •

edited

Loading

wouterj left a comment

wouterj Oct 4, 2017

wouterj Oct 4, 2017

javiereguiluz left a comment

ro0NL commented Oct 4, 2017

xabbuh Oct 5, 2017

xabbuh Oct 5, 2017

xabbuh Oct 5, 2017

xabbuh Oct 5, 2017

ro0NL commented Oct 5, 2017

xabbuh Oct 6, 2017

xabbuh Oct 6, 2017

javiereguiluz Oct 6, 2017

xabbuh Oct 6, 2017

xabbuh left a comment

xabbuh commented Oct 13, 2017


		The collected services can be prioritized using the ``priority`` attribute.

		.. code-block:: yaml


		.. tip::

		The collected services can be prioritized using the ``priority`` attribute.

		->addTag('app.handler', array('priority' => 20));

		Note that any other custom attributes will be ignored by this feature.

Docs for referencing tagged services in config #8404

Docs for referencing tagged services in config #8404

Conversation

ro0NL commented Sep 17, 2017

wouterj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ro0NL commented Oct 3, 2017

Tobion commented Oct 4, 2017 • edited Loading

wouterj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

javiereguiluz left a comment

Choose a reason for hiding this comment

ro0NL commented Oct 4, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ro0NL commented Oct 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xabbuh left a comment

Choose a reason for hiding this comment

xabbuh commented Oct 13, 2017

Tobion commented Oct 4, 2017 •

edited

Loading