Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[DependencyInjection] Doc for #30257 Allow to choose an index for tagged collection #11009

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 4, 2020
Merged

[DependencyInjection] Doc for #30257 Allow to choose an index for tagged collection #11009

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 206 additions & 0 deletions service_container/tags.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -699,3 +699,209 @@ in the configuration of the collecting service:
)
;
};

Tagged Services Collection with Index
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to retrieve a specific service within the injected collection
you can use the ``index_by`` and ``default_index_method`` options of the argument
in combination with ``!tagged``.

In the following example, all services tagged with ``app.handler`` are passed as
first constructor argument to ``App\Handler\HandlerCollection``,
but we can now access a specific injected service:

.. configuration-block::

.. code-block:: yaml

# config/services.yaml
services:
App\Handler\One:
tags:
- { name: 'app.handler', key: 'handler_one' }

App\Handler\Two:
tags:
- { name: 'app.handler', key: 'handler_two' }

App\HandlerCollection:
# inject all services tagged with app.handler as first argument
arguments: [!tagged { tag: 'app.handler', index_by: 'key' }]

.. code-block:: xml

<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd">

<services>
<service id="App\Handler\One">
<tag name="app.handler" key="handler_one" />
</service>

<service id="App\Handler\Two">
<tag name="app.handler" key="handler_two" />
</service>

<service id="App\HandlerCollection">
<!-- inject all services tagged with app.handler as first argument -->
<argument type="tagged" tag="app.handler" index-by="key" />
</service>
</services>
</container>

.. code-block:: php

// config/services.php
use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;

$container->register(App\Handler\One::class)
->addTag('app.handler', ['key' => 'handler_one']);

$container->register(App\Handler\Two::class)
->addTag('app.handler', ['key' => 'handler_two']);

$container->register(App\Handler\HandlerCollection::class)
// inject all services tagged with app.handler as first argument
->addArgument(new TaggedIteratorArgument('app.handler', 'key'));

After compilation the ``HandlerCollection`` is able to iterate over your
application handlers. To retrieve a specific service by it's ``key`` attribute
from the iterator, we can use ``iterator_to_array`` and retrieve the ``handler_two``:
to get an array and then retrieve the ``handler_two`` handler::

// src/Handler/HandlerCollection.php
namespace App\Handler;

class HandlerCollection
{
public function __construct(iterable $handlers)
{
$handlers = iterator_to_array($handlers);

$handlerTwo = $handlers['handler_two']:
}
}

.. tip::

You can omit the ``index_attribute_name`` attribute, by implementing a static
Copy link
Member

Choose a reason for hiding this comment

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

What's this index_attribute_name ? It's the first time it's mentioned in the docs.

Copy link
Contributor

Choose a reason for hiding this comment

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

This one was introduced by the new code

Copy link
Member

Choose a reason for hiding this comment

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

This doc suggests that there is an option called index_attribute_name. I can't see it in the previous examples, where we only use index_by or inex-by. So, is this an error? Is there a missing example? Am I missing something? Thanks.

Copy link
Author

@XuruDragon XuruDragon Mar 20, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

@hi @javiereguiluz ,
indeed the option is called index_by into the !tagged argument.
With a little example it would be better :

    foo_service:
        class: Foo
        tags:
            - { name: foo,  key: bar_foo}
    foo_service_tagged:
        class: Bar
        arguments: [!tagged { tag: foo, index_by: key  }]

What we explain in the documentation, is that we can, here, omit the attribute called key If we implement a method called getDefaultIndexName

If in the index_by option I called it sun so the omit attribute would be sun.

Is that more clear ?

The rest of the docs explains that with example.

If you find a more intuitive way to explains this, don't hesitate tu push to this PR ;)

Copy link
Contributor

Choose a reason for hiding this comment

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

I agree with Javier, the sentence should be You can omit the ``key`` attribute..., then directly show the usage of

arguments: [!tagged { tag: 'app.handler', index_by: 'key', default_index_method: 'someFunctionName' }]

within the tip, and discard the following.

method ``getDefaultIndexAttributeName`` to the handler.

Based on the previous example ``App\Handler\One`` should look like this::

// src/Handler/One.php
namespace App\Handler;

class One
{
public static function getDefaultIndexName(): string
{
return 'handler_one';
}
}

And the configuration:

.. configuration-block::

.. code-block:: yaml

# config/services.yaml
services:
App\Handler\One:
tags:
- { name: 'app.handler', priority: 20 }

# ...

.. code-block:: xml

<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd">

<services>
<service id="App\Handler\One">
<tag name="app.handler" priority="20" />
</service>

<!-- ... -->
</services>
</container>

.. code-block:: php

// config/services.php
$container->register(App\Handler\One::class)
->addTag('app.handler', ['priority' => 20]);

// ...

You also can define the name of the static method to implement on each service
with the ``default_index_method`` attribute on the argument.

Based on the previous example ``App\Handler\One`` should look like::

// src/Handler/One.php
namespace App\Handler;

class One
{
public static function someFunctionName(): string
{
return 'handler_one';
}
}

And the configuration:

.. configuration-block::

.. code-block:: yaml

# config/services.yaml
services:
# ...

App\HandlerCollection:
# inject all services tagged with app.handler as first argument
arguments: [!tagged { tag: 'app.handler', index_by: 'key', default_index_method: 'someFunctionName' }]

.. code-block:: xml

<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd">

<services>

<!-- ... --!>

<service id="App\HandlerCollection">
<!-- inject all services tagged with app.handler as first argument -->
<argument type="tagged" tag="app.handler" index-by="key" default-index-method="someFunctionName" />
</service>
</services>
</container>

.. code-block:: php

// config/services.php
// ...

$container->register(App\HandlerCollection::class)
// inject all services tagged with app.handler as first argument
->addArgument(new TaggedIteratorArgument('app.handler', 'key', 'someFunctionName'));

See also :doc:`tagged locator services </service_container/service_subscribers_locators>`