Пакет · di

Авторегистрация аннотированных классов

Пометка класса #[Singleton] объявляет его scope, но кто-то должен прочитать этот атрибут и зарегистрировать привязку. Scanner один раз обходит код проекта и передаёт каждый класс в DICollector, который регистрирует те, у кого есть scope-атрибут — так что вам не нужно перечислять их вручную.

Базовое сканирование

Наведите Scanner на корень исходников, подключите DICollector, привязанный к контейнеру, и запустите.

bootstrap.php
<?php

use Flytachi\Winter\DI\Container;
use Flytachi\Winter\DI\Scanner;
use Flytachi\Winter\DI\Collector\DICollector;

$container = Container::init();

Scanner::run(__DIR__ . '/src')
  ->collect(new DICollector($container))
  ->execute();

DICollector сопоставляет каждый scope-атрибут соответствующей привязке:

Атрибут Регистрация
#[Singleton] $container->singleton($class)
#[Request] $container->request($class)
#[Transient] $container->transient($class)

Класс без scope-атрибута коллектор пропускает — он остаётся автовайримым по требованию как transient.

Что Scanner пропускает

Абстрактные классы, интерфейсы и трейты отфильтровываются до запуска коллекторов, поэтому collect() всегда видит только инстанцируемые классы. vendor/ исключается всегда.

Сканировать то, что объявлено в composer.json

Код проекта — это то, что автозагружает его composer.json, а не всё, что лежит под корнем. Если обходить корень целиком, каждый .php в нём считается кодом: тесты и скрипты подключаются через require_once (их код верхнего уровня выполняется, а тест-класс без dev-зависимостей — фатальная ошибка), а любая папка, которую нельзя открыть, вроде тома базы данных, останавливает скан.

Scanner::composer() берёт каталоги из секции autoload файла composer.json в переданном каталоге:

bootstrap.php
Scanner::composer(__DIR__, cache: __DIR__ . '/var/cache/di.php')
  ->collect(new DICollector($container))
  ->execute();

В скан попадают все пути psr-4 и psr-0 и все записи classmap из autoload. Не попадают:

  • autoload-dev — тесты не часть приложения, а в продакшн-установке (composer install --no-dev) того, от чего они наследуются, нет;
  • files — Composer и так подключает их на каждом запросе, и объявляют они функции, а не сервисы.

Объявленный путь, которого ещё нет на диске, пропускается — Composer его тоже терпит. Список каталогов без запуска скана возвращает Scanner::composerRoots($projectRoot).

Без autoload скан не запустится

Если composer.json нет или он не читается, либо в autoload не объявлено ни одного каталога, composer() и composerRoots() бросают Flytachi\Winter\DI\Exception\ScanException. Сообщение подсказывает, что добавить: "autoload": {"psr-4": {"Main\\": "main/"}}, затем composer dump-autoload.

Несколько каталогов за один проход

run() принимает и один каталог, и список. Элементом списка может быть и отдельный файл — он сканируется сам по себе. Все пути обходятся как один скан: файл, попавший в два пересекающихся пути, читается один раз.

php
Scanner::run([__DIR__ . '/src', __DIR__ . '/lib', __DIR__ . '/bootstrap.php'])
  ->collect(new DICollector($container))
  ->execute();

Папки, которые не открываются

Каталог, который нельзя открыть на чтение списка (нет прав, его не отдаёт примонтированный том), пропускается, а не роняет скан. Какие каталоги пропущены в последнем обходе, возвращает skipped():

php
$scanner = Scanner::composer(__DIR__)->collect(new DICollector($container));
$scanner->execute();

foreach ($scanner->skipped() as $dir) {
  // classes under $dir were not registered
  error_log("Scan skipped {$dir}");
}

Классы из пропущенного каталога не регистрируются. После попадания в кэш skipped() пуст: обхода не было.

Добавьте продакшн-кэш

Сканировать файловую систему при каждом старте расточительно в продакшене. Передайте путь cache: первый старт обходит дерево и записывает список найденных имён классов; последующие старты загружают этот список и полностью пропускают обход.

php
Scanner::run(__DIR__ . '/src', cache: __DIR__ . '/var/cache/di.php')
  ->collect(new DICollector($container))
  ->execute();

Файл кэша — обычный PHP-массив полностью квалифицированных имён классов:

var/cache/di.php
<?php

return [
  'App\\Service\\UserService',
  'App\\Repository\\UserRepository',
  // ...
];

Инвалидация кэша

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

Исключение каталогов

vendor/ исключается всегда — в каждом сканируемом каталоге. Добавьте другие пути через exclude() (абсолютные пути):

php
Scanner::run(__DIR__ . '/src')
  ->exclude([
      __DIR__ . '/src/legacy',
      __DIR__ . '/src/generated',
  ])
  ->collect(new DICollector($container))
  ->execute();

В исключённый каталог сканер не заходит вовсе — его файлы не читаются. Совпадение считается по границе каталога: исключение vendor не задевает соседний vendor-tools/.

Запуск нескольких коллекторов за один проход

DICollector — один коллектор; у фреймворка их обычно больше (маршруты, обработчики исключений, консольные команды). Зарегистрируйте их все на одном Scanner, и они разделят один обход файловой системы — ни один класс не читается дважды.

php
Scanner::run(__DIR__ . '/src', cache: $cachePath)
  ->collect(new DICollector($container))     // scope-атрибуты
  ->collect(new MappingCollector($router))   // атрибуты маршрутов
  ->collect(new ExceptionCollector())        // обработчики исключений
  ->execute();

Коллекторы вызываются в порядке регистрации для каждого класса.

Напишите свой коллектор

Любой класс, реализующий CollectorInterface, может присоединиться к сканированию. Он получает имя каждого класса и ReflectionClass — делайте своё чтение атрибутов и регистрацию.

src/RouteCollector.php
<?php

use Flytachi\Winter\DI\Contract\CollectorInterface;
use ReflectionClass;

final class RouteCollector implements CollectorInterface
{
  public function __construct(private readonly Router $router) {}

  public function collect(string $class, ReflectionClass $ref): void
  {
      foreach ($ref->getAttributes(Route::class) as $attr) {
          $route = $attr->newInstance();
          $this->router->add($route->method, $route->path, $class);
      }
  }
}

Держите коллекторы лёгкими

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

Связанное