Как декорировать сервисы

Дата обновления перевода 2023-01-11

Как декорировать сервисы

При переопределении существующего определения, первоначальный сервис теряется:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
        # config/services.yaml
services:
    App\Mailer: ~

    # это заменяет старое определение app.mailer новым,
    # а старое определение теряется
    App\Mailer:
        class: App\NewMailer
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        <!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
    xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Mailer"/>

        <!-- это заменяет старое определение app.mailer новым,
             а старое определение теряется -->
        <service id="App\Mailer" class="App\NewMailer"/>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Mailer;
use App\NewMailer;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set(Mailer::class);

// это заменяет старое определение app.mailer новым,
// а старое определение теряется
    $services->set(Mailer::class, NewMailer::class);
};
    

В большинстве случаев это будет именно то, что вы будете хотеть сделать. Но иногда, вы можете захотеть вместо этого декорировать старый сервис, (i.e. apply the Decorator pattern). In this case, the old service should be kept around to be able to reference it in the new one. This configuration replaces App\Mailer with a new one, but keeps a reference of the old one as .inner:

Attributes
YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
        // src/DecoratingMailer.php
namespace App;

// ...
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;

#[AsDecorator(decorates: Mailer::class)]
class DecoratingMailer
{
    // ...
}
    

        1
2
3
4
5
6
7
8
        # config/services.yaml
services:
    App\Mailer: ~

    App\DecoratingMailer:
        # переопределяет сервис App\Mailer,
        # но этот сервис все еще доступен как ".inner"
        decorates: App\Mailer
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
    xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Mailer"/>

        <!-- переопределяет сервис App\Mailer,
             но этот сервис все еще доступен как ".inner" -->
        <service id="App\DecoratingMailer"
            decorates="App\Mailer"
        />

    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\DecoratingMailer;
use App\Mailer;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set(Mailer::class);

    $services->set(DecoratingMailer::class)
        // переопределяет сервис App\Mailer,
        // но этот сервис все еще доступен как ".inner"
        ->decorate(Mailer::class);
};
    

6.1

Атрибут #[AsDecorator] был представлен в Symfony 6.1.

Опция decorates сообщает контейнеру, что сервис App\DecoratingMailer заменяет сервис App\Mailer. Если вы используете конфигурацию services.yaml по умолчанию , декорированный сервис автоматически внедряется, когда конструктор декориующего сервиса имеет один аргумент с подсказкой декорированного класса сервиса.

Если вы не используете автомонтирование или декорирующий сервис имеет более одного аргумента конструктора с подсказкой декорированного класса сервиса, ви должны внедрить декорированный сервис ясно (ID декорированного сервиса автоматически изменяется на '.inner'):

Attributes
YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // src/DecoratingMailer.php
namespace App;

// ...
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
use Symfony\Component\DependencyInjection\Attribute\MapDecorated;

#[AsDecorator(decorates: Mailer::class)]
class DecoratingMailer
{
    private $inner;

    public function __construct(#[MapDecorated] $inner)
    {
        $this->inner = $inner;
    }

    // ...
}
    

        1
2
3
4
5
6
7
8
        # config/services.yaml
services:
    App\Mailer: ~

    App\DecoratingMailer:
        decorates: App\Mailer
        # pass the old service as an argument
        arguments: ['@.inner']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
    xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="App\Mailer"/>

        <service id="App\DecoratingMailer"
            decorates="App\Mailer"
        >
            <!-- pass the old service as an argument -->
            <argument type="service" id=".inner"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\DecoratingMailer;
use App\Mailer;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set(Mailer::class);

    $services->set(DecoratingMailer::class)
        ->decorate(Mailer::class)
        // pass the old service as an argument
        ->args([service('.inner')]);
};
    

Tip

Видимость декорированного сервиса App\Mailer (который явялется псевдонимом нового сервиса), будет такой же, как и видимость первоначального App\Mailer.

Note

Сгенерированный внутрений id осовывается на is сервиса декоратора (тут App\DecoratingMailer), а не декорированном сервисе (тут App\Mailer). Вы можете контролировать внутренний сервис через опцию decoration_inner_name:

YAML
XML
PHP

        1
2
3
4
5
6
        # config/services.yaml
services:
    App\DecoratingMailer:
        # ...
        decoration_inner_name: App\DecoratingMailer.wooz
        arguments: ['@App\DecoratingMailer.wooz']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        <!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
    xsd:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <!-- ... -->

        <service
            id="App\DecoratingMailer"
            decorates="App\Mailer"
            decoration-inner-name="App\DecoratingMailer.wooz"
            public="false"
        >
            <argument type="service" id="App\DecoratingMailer.wooz"/>
        </service>

    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\DecoratingMailer;
use App\Mailer;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set(Mailer::class);

    $services->set(DecoratingMailer::class)
        ->decorate(Mailer::class, DecoratingMailer::class.'.wooz')
        ->args([service(DecoratingMailer::class.'.wooz')]);
};
    

Приоритет декорирования

При применении нескольких декораторов к сервису, вы не можете контролировать их порядок с опцией decoration_priority. Это значение является целым числом, по умолчанию 0, а более высокий приоритет означает, что декораторы будут применены раньше.

Attributes
YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
        // ...
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
use Symfony\Component\DependencyInjection\Attribute\MapDecorated;

#[AsDecorator(decorates: Foo::class, priority: 5)]
class Bar
{
    private $inner;

    public function __construct(#[MapDecorated] $inner)
    {
        $this->inner = $inner;
    }
    // ...
}

#[AsDecorator(decorates: Foo::class, priority: 1)]
class Baz
{
    private $inner;

    public function __construct(#[MapDecorated] $inner)
    {
        $this->inner = $inner;
    }

    // ...
}
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        # config/services.yaml
services:
    Foo: ~

    Bar:
        decorates: Foo
        decoration_priority: 5
        arguments: ['@.inner']

    Baz:
        decorates: Foo
        decoration_priority: 1
        arguments: ['@.inner']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <!-- 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 https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Foo"/>

        <service id="Bar" decorates="Foo" decoration-priority="5">
            <argument type="service" id=".inner"/>
        </service>

        <service id="Baz" decorates="Foo" decoration-priority="1">
            <argument type="service" id=".inner"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set(\Foo::class);

    $services->set(\Bar::class)
        ->decorate(\Foo::class, null, 5)
        ->args([service('.inner')]);

    $services->set(\Baz::class)
        ->decorate(\Foo::class, null, 1)
        ->args([service('.inner')]);
};
    

Сгенерированный код будет следующим:

        1
        $this->services[Foo::class] = new Baz(new Bar(new Foo()));
    

Стек декораторов

Альтернативой использования приоритетов декорирования является создание stack упорядоченных сервисов, где каждый декорирует следующий:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        # config/services.yaml
services:
    decorated_foo_stack:
        stack:
            - class: Baz
              arguments: ['@.inner']
            - class: Bar
              arguments: ['@.inner']
            - class: Foo

    # используя короткий синтаксис:
    decorated_foo_stack:
        stack:
            - Baz: ['@.inner']
            - Bar: ['@.inner']
            - Foo: ~

    # может быть упрощенным, если включено автомонтирование:
    decorated_foo_stack:
        stack:
            - Baz: ~
            - Bar: ~
            - Foo: ~
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
        <!-- 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
        https://symfony.com/schema/dic/services/services-1.0.xsd"
>
    <services>
        <stack id="decorated_foo_stack">
            <service class="Baz">
                <argument type="service" id=".inner"/>
            </service>
            <service class="Bar">
                <argument type="service" id=".inner"/>
            </service>
            <service class="Foo"/>
        </stack>

        <!-- может быть упрощенным, если включено автомонтирование: -->
        <stack id="decorated_foo_stack">
            <service class="Baz"/>
            <service class="Bar"/>
            <service class="Foo"/>
        </stack>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return function(ContainerConfigurator $container) {
    $container->services()
        ->stack('decorated_foo_stack', [
            inline_service(\Baz::class)->args([service('.inner')]),
            inline_service(\Bar::class)->args([service('.inner')]),
            inline_service(\Foo::class),
        ])

        // может быть упрощенным, если включено автомонтирование:
        ->stack('decorated_foo_stack', [
            inline_service(\Baz::class),
            inline_service(\Bar::class),
            inline_service(\Foo::class),
        ])
    ;
};
    

Результат будет таким же, как и в предыдущем разделе:

        1
        $this->services['decorated_foo_stack'] = new Baz(new Bar(new Foo()));
    

Как и псевдонимы, stack может использовать только атрибуты public и deprecated.

Каждый фрейм в stack может быть либо встроенным сервисом, либо ссылкой, либо дочерним определением. Последнее позволяет встраивание определений stack друг в друга, вот продвинутый пример:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        # config/services.yaml
services:
    some_decorator:
        class: App\Decorator

    embedded_stack:
        stack:
            - alias: some_decorator
            - App\Decorated: ~

    decorated_foo_stack:
        stack:
            - parent: embedded_stack
            - Baz: ~
            - Bar: ~
            - Foo: ~
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        <!-- 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
        https://symfony.com/schema/dic/services/services-1.0.xsd"
>
    <services>
        <service id="some_decorator" class="App\Decorator"/>

        <stack id="embedded_stack">
            <service alias="some_decorator"/>
            <service class="App\Decorated"/>
        </stack>

        <stack id="decorated_foo_stack">
            <service parent="embedded_stack"/>
            <service class="Baz"/>
            <service class="Bar"/>
            <service class="Foo"/>
        </stack>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Decorated;
use App\Decorator;

return function(ContainerConfigurator $container) {
    $container->services()
        ->set('some_decorator', Decorator::class)

        ->stack('embedded_stack', [
            service('some_decorator'),
            inline_service(Decorated::class),
        ])

        ->stack('decorated_foo_stack', [
            inline_service()->parent('embedded_stack'),
            inline_service(\Baz::class),
            inline_service(\Bar::class),
            inline_service(\Foo::class),
        ])
    ;
};
    

Результатом будет:

        1
        $this->services['decorated_foo_stack'] = new App\Decorator(new App\Decorated(new Baz(new Bar(new Foo()))));
    

Note

Чтобы изменить существующие стеки (то есть, из передачи компилятора), вы можете получить доступ к каждому фрейму по его сгенерированному id со следующей структурой: .stack_id.frame_key. Из примера выше, .decorated_foo_stack.1 будет ссылкой на встроенный сервис Baz, а .decorated_foo_stack.0 - на встроенный стек. Чтобы получить более ясные id, вы можете дать каждому фрейму имя:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
        # ...
decorated_foo_stack:
    stack:
        first:
            parent: embedded_stack
        second:
            Baz: ~
        # ...
    

        1
2
3
4
5
6
        <!-- ... -->
<stack id="decorated_foo_stack">
    <service id="first" parent="embedded_stack"/>
    <service id="second" class="Baz"/>
    <!-- ... -->
</stack>
    

        1
2
3
4
5
6
        // ...
->stack('decorated_foo_stack', [
    'first' => inline_service()->parent('embedded_stack'),
    'second' => inline_service(\Baz::class),
    // ...
])
    

Id фрейма Baz теперь будет .decorated_foo_stack.second.

Контроль поведения, если декорированный сервис не существует

Когда вы декорируете сервис, который не существует, опция decoration_on_invalid позволяет вам выбрать желаемое поведение.

Доступны три разных вида поведения:

exception: Будет вызвано ServiceNotFoundException, сообщающее, что зависимость декоратора отсутствует (по умолчанию).
ignore: Контейнер удалит декоратор.
null: Контейнер оставит сервис декоратора и установит декорированный как null.

Attributes
YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        // ...
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
use Symfony\Component\DependencyInjection\Attribute\MapDecorated;
use Symfony\Component\DependencyInjection\ContainerInterface;

#[AsDecorator(decorates: Mailer::class, onInvalid: ContainerInterface::IGNORE_ON_INVALID_REFERENCE)]
class Bar
{
    private $inner;

    public function __construct(#[MapDecorated] $inner)
    {
        $this->inner = $inner;
    }

    // ...
}
    

        1
2
3
4
5
6
7
        # config/services.yaml
Foo: ~

Bar:
    decorates: Foo
    decoration_on_invalid: ignore
    arguments: ['@.inner']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- 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 https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Foo"/>

        <service id="Bar" decorates="Foo" decoration-on-invalid="ignore">
            <argument type="service" id=".inner"/>
        </service>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Component\DependencyInjection\ContainerInterface;

return function(ContainerConfigurator $configurator) {
    $services = $configurator->services();

    $services->set(Foo::class);

    $services->set(Bar::class)
        ->decorate(Foo::class, null, 0, ContainerInterface::IGNORE_ON_INVALID_REFERENCE)
        ->args([service('.inner')])
    ;
};
    

Caution

При использовании null, вам может понадобиться обновить конструктор декоратора, чтобы сделать декорированную зависимость nullable:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        // src/Service/DecoratorService.php
namespace App\Service;

use Acme\OptionalBundle\Service\OptionalService;

class DecoratorService
{
    private $decorated;

    public function __construct(?OptionalService $decorated)
    {
        $this->decorated = $decorated;
    }

    public function tellInterestingStuff(): string
    {
        if (!$this->decorated) {
            return 'Just one interesting thing';
        }

        return $this->decorated->tellInterestingStuff().' + one more interesting thing';
    }
}
    

Note

Иногда, вам может захотеться добавить передачу компилятора, которая создает определения сервиса на лету. Если вы хотите декорировать такой сервис, убедитесь в том, что ваша передача компилятора зарегистрирована с типом PassConfig::TYPE_BEFORE_OPTIMIZATION, чтобы передача декорации могла найти созданные сервисы.