Внедрение зависимостей

Объекты в приложении собирает контейнер. Вы объявляете, что нужно классу — типом, — а он создаёт зависимость, её собственные зависимости и передаёт готовое дерево. Слова new в прикладном коде почти не остаётся.

Что такое внедрение зависимостей и зачем

Зависимость — любой объект, без которого класс не работает: контроллеру нужен сервис, сервису — репозиторий, репозиторию — подключение к базе.

Проблема. Когда класс создаёт зависимости сам, он обязан знать, как собирается каждая из них:

$service = new UserService(
  new UserRepository(new Connection(env('DB_DSN'), env('DB_USER'), env('DB_PASS'))),
  new Logger('user'),
);

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

Решение. Класс объявляет что ему нужно, а как это построить — забота контейнера:

class UserService
{
  public function __construct(
      private UserRepository $repo,
      private LoggerInterface $logger,
  ) {}
}

Дальше UserService берётся у контейнера, и он сам построит репозиторий, соединение и логгер. Класс перестаёт зависеть от способа сборки, а подмена реализации становится вопросом настройки, а не правки.

Как контейнер строит объекты

При запуске приложения сканер обходит проект и запоминает классы, которым задана область видимости, а также классы-конфигурации. Это тот же обход, что находит контроллеры и маршруты, — отдельного шага нет.

Дальше, когда кто-то просит объект, контейнер:

1. смотрит, есть ли для этого типа привязка или готовый экземпляр;
2. если нет — читает конструктор класса;
3. по типу каждого аргумента рекурсивно строит зависимость;
4. создаёт объект и заполняет свойства, помеченные #[Autowired];
5. кеширует результат, если область видимости это предполагает.

Просить объект вручную обычно не нужно: контроллеры, middleware, обработчики консольных команд и фоновых задач фреймворк создаёт сам.

Как объявить зависимость

Способов четыре, и они не равнозначны: первый — основной, остальные решают частные задачи.

Через конструктор

Базовый способ, никакого атрибута не требуется. Достаточно объявить тип:

<?php

namespace Main;

use Psr\Log\LoggerInterface;

class UserService
{
  public function __construct(
      private UserRepository $repo,
      private LoggerInterface $logger,
  ) {}

  public function find(int $id): User
  {
      $this->logger->info('lookup', ['id' => $id]);

      return $this->repo->findOrFail($id);
  }
}

Так следует писать везде, где конструктор в вашем распоряжении: зависимости видны в сигнатуре, класс можно собрать руками в тесте, а readonly-свойства остаются возможными.

Через свойство — #[Autowired]

Когда конструктор занят или недоступен, зависимость внедряется прямо в свойство:

use Flytachi\Winter\DI\Attribute\Autowired;

class PostController extends Controller
{
  #[Autowired] private PostService $service;
  #[Autowired] private LoggerInterface $logger;
}

Свойство может быть private — контейнер заполняет его сразу после создания объекта, до того как управление дойдёт до ваших методов.

Уточнение — #[Inject]

По типу контейнер понимает не всё: интерфейс сам по себе не говорит, какую реализацию взять, а число или строку по типу не разрешить вовсе. Для таких случаев есть #[Inject] — работает и на аргументе конструктора, и на свойстве.

use Flytachi\Winter\DI\Attribute\Inject;

class ReportService
{
  public function __construct(
      // 1. по типу — то же, что без атрибута, просто явно
      #[Inject] private CacheInterface $cache,

      // 2. конкретная реализация в обход общей привязки
      #[Inject(FileCache::class)] private CacheInterface $fallback,

      // 3. значение по ключу, положенное в контейнер заранее
      #[Inject('config.timeout')] private int $timeout,
  ) {}
}

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

Отложенное — #[Lazy]

#[Lazy] подставляет вместо объекта прокси, а настоящий экземпляр создаётся при первом обращении к нему.

Главное применение — разорвать круг. Если A нужен B, а B нужен A, обычное разрешение уйдёт в бесконечную рекурсию и упадёт. Достаточно пометить #[Lazy] одну сторону:

use Flytachi\Winter\DI\Attribute\Lazy;

class SmsSendService
{
  public function __construct(
      #[Lazy] private PeerService $peer,   // создастся при первом использовании
  ) {}
}

Круг в зависимостях — почти всегда признак того, что двум классам нужен третий. #[Lazy] решает проблему, но стоит сначала посмотреть, не разделяются ли классы. Подробный разбор — в документации пакета.

Области видимости

Область видимости отвечает на вопрос, сколько экземпляров класса существует и как долго они живут.

Данные запроса — #[Request]

Экземпляр живёт ровно один запрос и виден всем, кто его попросит внутри этого запроса. Параллельные запросы получают каждый свой — в Swoole изоляция идёт по корутинам, под PHP-FPM запрос и так равен процессу.

<?php

namespace Main;

use Flytachi\Winter\DI\Attribute\Request;

#[Request]
class AuthContext
{
  private ?User $user = null;

  public function setUser(User $user): void { $this->user = $user; }

  public function user(): User
  {
      return $this->user ?? throw new \LogicException('No authenticated user');
  }
}

Типичное применение: middleware аутентификации кладёт сюда пользователя, а контроллеры и сервисы читают. Разбор этого приёма по шагам — на странице Middleware.

Конфигурация — #[Configuration] и #[Bean]

Автоматической сборки хватает, пока речь о конкретных классах. Но интерфейс сам по себе не говорит, какую реализацию взять; объекту из чужой библиотеки может понадобиться нестандартная сборка; строку подключения нужно достать из окружения. Всё это описывается в классе-конфигурации.

<?php

namespace Main;

use Flytachi\Winter\Kernel\App\Attribute\Bean;
use Flytachi\Winter\Kernel\App\Attribute\Configuration;
use Flytachi\Winter\Kernel\App\Attribute\Value;

#[Configuration]
final class AppConfig
{
  #[Bean]
  public function cache(#[Value('REDIS_URL')] string $url): CacheInterface
  {
      return new RedisCache($url);
  }

  #[Bean]
  public function mailer(
      #[Value('MAIL_HOST', 'localhost')] string $host,
      LoggerInterface $logger,
  ): MailerInterface {
      return new SmtpMailer($host, $logger);
  }
}

Регистрировать класс нигде не нужно — его находит тот же скан. Дальше любой класс, запросивший CacheInterface, получит собранный здесь RedisCache.

Как это устроено:

Метод обязан возвращать объект и объявлять тип возврата — по нему и строится привязка.

Область видимости бина

По умолчанию бин — синглтон: метод отработает один раз, результат переиспользуется. Обратите внимание на разницу с обычными классами, где умолчание противоположное.

use Flytachi\Winter\Kernel\App\Scope;

#[Bean(scope: Scope::Transient)]          // новый на каждое обращение
public function query(): QueryBuilder
{
  return new QueryBuilder();
}

#[Bean(scope: Scope::Request)]            // один на запрос
public function correlation(): CorrelationId
{
  return new CorrelationId(bin2hex(random_bytes(8)));
}

Несколько бинов одного типа

Когда одного типа нужно две штуки, привязку по типу различают именем:

#[Bean(name: 'cache.redis')]
public function redis(): CacheInterface { /* ... */ }

#[Bean(name: 'cache.file')]
public function file(): CacheInterface { /* ... */ }

Забирается такой бин уточнением по ключу:

public function __construct(
  #[Inject('cache.redis')] private CacheInterface $cache,
) {}

Привязки из кода

Иногда привязку удобнее описать императивно — например, собрать её в цикле или выбрать по условию. Для этого есть провайдер: класс, которому контейнер даёт себя, чтобы тот записал в него привязки.

$c->singleton(CacheInterface::class, RedisCache::class);           // один на процесс
$c->request(AuthContext::class);                                   // один на запрос
$c->transient(QueryBuilder::class);                                // новый каждый раз
$c->bind(MailerInterface::class, fn(Container $c) => new SmtpMailer(env('MAIL_HOST')));
$c->set('config.timeout', (int) env('APP_TIMEOUT', 30));           // готовое значение

contextual() — самый нестандартный из них: фабрика получает имя класса-потребителя и может вернуть разное. Именно так устроен логгер — #[Autowired] LoggerInterface приходит уже названным по классу, в который его внедрили.

Когда контейнер не может собрать

Все шесть отказов приходят как исключения PSR-11, и сообщение называет настоящую причину — чинятся они в шести разных местах:

Деление ровно по PSR-11: NotFoundException — «строить нечего», ContainerException — «нашли, но собрать нельзя». Поэтому и ловить их можно по отдельности:

try {
  $gateway = $container->get(PaymentGateway::class);
} catch (NotFoundExceptionInterface $e) {
  // строить нечего — нет привязки, либо класс не установлен
} catch (ContainerExceptionInterface $e) {
  // нашли, но собрать нельзя — абстрактный, enum, приватный конструктор, цикл
}

Ошибка конструктора остаётся вашей: если тело __construct() бросило исключение, оно долетит как есть — контейнер не переклеивает на него свою этикетку, иначе единственное сообщение, говорящее где именно сломалось, потерялось бы.

Инструменты — call di

Посмотреть, что контейнер знает о проекте, и управлять кешем:

php call di show                # все классы в кеше контейнера
php call di show Main\Service    # только совпадающие с фрагментом имени
php call di build               # обойти проект один раз и собрать кеш
php call di clean               # удалить кеш и сгенерированные прокси
php call di async               # методы #[Async] и состояние их прокси

Команда пригождается, когда класс «не находится»: если его нет в выводе show, значит он не попал в скан — проверьте, что файл лежит не в resources/ или storage/ и что класс не абстрактный.

Дальше

• Winter DI — полный reference — разрешение, прокси, провайдеры
• Контроллеры — где #[Autowired] обязателен
• Middleware — как наполняется #[Request]-контекст
• Конфигурация — прочие настройки приложения