Сервис-контейнер и автоконфигурация в Symfony: приёмы из практики

Вы добавили в конструктор сервиса интерфейс PaymentGatewayInterface, а Symfony падает с Cannot autowire service: argument $gateway references interface, no such service exists. Или того хуже — реализаций две, и контейнер не знает, какую подставить. Autowiring работает магически ровно до момента, когда типов больше, чем одна очевидная реализация. Дальше начинается конфигурация, и вопрос только в том, где вы её пишете и сколько она стоит в поддержке.

Разбираем на Symfony 7.x (приёмы справедливы и для 6.4 LTS) три узла, на которых спотыкаются: связывание интерфейсов с реализациями, передача скалярных и множественных аргументов, теги и итераторы сервисов. Для каждого — цена: что выигрываете и чем платите.

Что даёт автоконфигурация по умолчанию

Стандартный config/services.yaml в новом проекте включает три вещи, которые стоит понимать раздельно:

• autowire: true — контейнер подставляет зависимости в конструктор по типу аргумента. Ищет сервис, чей класс совпадает с тайп-хинтом.
• autoconfigure: true — сервис автоматически получает теги на основе интерфейсов, которые реализует (EventSubscriberInterface, CommandInterface и прочие). Без этого пришлось бы вешать теги руками.
• Загрузка по маске — блок App\: с resource регистрирует все классы из src/ как сервисы разом.

Пока каждый интерфейс имеет ровно одну реализацию, всё работает без единой строки настройки. Проблемы начинаются на неоднозначности.

Сноска: что такое сервис-контейнер

Сервис-контейнер — объект, который хранит инструкции по созданию сервисов (классов с логикой) и их зависимостей. Вместо ручного new Foo(new Bar()) вы просите у контейнера Foo, а он сам собирает граф зависимостей. Autowiring — механизм, который угадывает, какие зависимости передать, по типам аргументов конструктора.

Приём 1. Связать интерфейс с реализацией

Когда реализация одна, но вы тайп-хинтите на интерфейс, контейнер не знает, что SmsSender — это и есть SenderInterface. Явный алиас решает вопрос:

# config/services.yaml (Symfony 7.x)
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'

    # алиас: где просят интерфейс — подставить конкретный класс
    App\Notification\SenderInterface: '@App\Notification\SmsSender'

Теперь любой конструктор с аргументом SenderInterface $sender получит SmsSender. Альтернатива без YAML — атрибут #[AsAlias] прямо на классе реализации (доступен с Symfony 6.1):

<?php
// src/Notification/SmsSender.php

namespace App\Notification;

use Symfony\Component\DependencyInjection\Attribute\AsAlias;

#[AsAlias(SenderInterface::class)]
class SmsSender implements SenderInterface
{
    public function send(string $phone, string $text): void
    {
        // отправка
    }
}

Цена. Алиас в YAML держит конфигурацию в одном месте — удобно, когда реализацию меняют в зависимости от окружения. Атрибут #[AsAlias] держит связь рядом с кодом, но прячет её от того, кто читает конфиг. На большом проекте выбирайте что-то одно: смесь атрибутов и YAML для одного и того же интерфейса — верный способ потратить полчаса на поиск, откуда взялась реализация.

Приём 2. Несколько реализаций одного интерфейса

Реализаций две — SmsSender и EmailSender. Автовайринг тут бессилен: он не телепат. Начиная с Symfony 5.3 задачу решает атрибут #[Autowire] с указанием сервиса, а для именованных — #[Target] или связывание по имени аргумента.

Самый читаемый путь — привязать реализацию к имени аргумента через _defaults → bind или точечно в конкретном сервисе:

# config/services.yaml
services:
    App\Notification\OrderNotifier:
        arguments:
            $smsSender: '@App\Notification\SmsSender'
            $emailSender: '@App\Notification\EmailSender'

<?php
// src/Notification/OrderNotifier.php

namespace App\Notification;

class OrderNotifier
{
    public function __construct(
        private SenderInterface $smsSender,
        private SenderInterface $emailSender,
    ) {}
}

Имя аргумента ($smsSender) становится частью контракта — переименуете параметр и забудете поправить YAML, получите ошибку сборки контейнера. Это раздражает, но лучше молчаливой подстановки не той реализации.

Магия автовайринга хороша ровно до первой развилки. Как только у интерфейса больше одной реализации, вы всё равно пишете конфигурацию — вопрос лишь в том, найдёт ли её следующий разработчик за минуту или за час.

Приём 3. Скалярные аргументы и параметры

Autowiring умеет подставлять сервисы, но не строки и числа. Аргумент string $apiUrl он не разрешит — нет сервиса такого типа. Атрибут #[Autowire] (Symfony 6.1+) закрывает это прямо в конструкторе, без правки YAML:

<?php
// src/Client/WeatherClient.php

namespace App\Client;

use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Contracts\HttpClient\HttpClientInterface;

class WeatherClient
{
    public function __construct(
        private HttpClientInterface $httpClient,
        // значение из параметра контейнера
        #[Autowire(param: 'weather_api_url')]
        private string $apiUrl,
        // значение из переменной окружения
        #[Autowire(env: 'WEATHER_API_KEY')]
        private string $apiKey,
    ) {}
}

Параметр weather_api_url при этом объявляется в config/services.yaml в секции parameters. Ключи и токены держите в .env и через env(), а не в параметрах — в примере это WEATHER_API_KEY, реальное значение в репозиторий не коммитится.

Приём 4. Собрать все реализации разом — теги и итераторы

Задача: обработчик должен вызвать все зарегистрированные SenderInterface, не зная заранее их количества. Здесь работает #[AutowireIterator] либо тег плюс tagged_iterator. С autoconfigure все классы, реализующие помеченный интерфейс, получают тег автоматически — достаточно объявить это в _instanceof:

# config/services.yaml
services:
    _instanceof:
        App\Notification\SenderInterface:
            tags: ['app.notification_sender']

    App\Notification\NotificationHub:
        arguments:
            $senders: !tagged_iterator app.notification_sender

<?php
// src/Notification/NotificationHub.php

namespace App\Notification;

class NotificationHub
{
    /** @param iterable<SenderInterface> $senders */
    public function __construct(private iterable $senders) {}

    public function broadcast(string $to, string $text): void
    {
        foreach ($this->senders as $sender) {
            $sender->send($to, $text);
        }
    }
}

iterable здесь важен: сервисы из тега создаются лениво, при первой итерации, а не все сразу при сборке NotificationHub. Если тайп-хинтить массив, контейнер инстанцирует их всех немедленно.

Чем платить за каждый подход

Что ломается на практике

• Дубль регистрации. Класс попал под маску App\: и одновременно объявлен явно ниже — второе определение перезаписывает первое. Ошибок нет, но autoconfigure у явного определения по умолчанию наследуется из _defaults, а вот теги через _instanceof применяются к обоим. Проверяйте php bin/console debug:container ИмяСервиса.
• Приватность сервисов. По умолчанию сервисы приватны, из контейнера через $container->get() их не достать. Это правильно, но ломает старый код, который дёргал контейнер напрямую. Не делайте сервис публичным ради этого — инжектите зависимость.
• Порядок в tagged_iterator. Без priority в теге порядок не гарантирован между версиями. Если broadcast должен идти сначала по SMS, задайте приоритет явно.
• #[Autowire(env:)] и типы. Переменные окружения — строки. Нужно число — используйте процессор %env(int:PORT)%, иначе получите строку там, где ждали int.

Что делать дальше

Первое, что стоит завести в привычку, — php bin/console debug:autowiring и debug:container. Первая показывает, какие типы контейнер умеет разрешать автоматически и через какой алиас; вторая — во что превратилось конкретное определение после компиляции. Когда автовайринг «не видит» сервис, ответ почти всегда там.

Дальше — держите правило: одна связь интерфейс-реализация описывается одним способом на весь проект. Смешение YAML-алиасов, #[AsAlias] и bind для разных интерфейсов допустимо, для одного — нет. Компиляция контейнера и его отладка — отдельная тема; здесь мы разбирали только регистрацию и разрешение зависимостей.