Авторегистрация аннотированных классов
Пометка класса #[Singleton] объявляет его scope, но кто-то должен прочитать этот атрибут и
зарегистрировать привязку. Scanner один раз обходит код проекта и передаёт каждый
класс в DICollector, который регистрирует те, у кого есть scope-атрибут — так что вам не
нужно перечислять их вручную.
Базовое сканирование
Наведите Scanner на корень исходников, подключите DICollector, привязанный к контейнеру, и
запустите.
<?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 в
переданном каталоге:
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() принимает и один каталог, и список. Элементом списка может быть и отдельный
файл — он сканируется сам по себе. Все пути обходятся как один скан: файл, попавший в
два пересекающихся пути, читается один раз.
Scanner::run([__DIR__ . '/src', __DIR__ . '/lib', __DIR__ . '/bootstrap.php'])
->collect(new DICollector($container))
->execute();Папки, которые не открываются
Каталог, который нельзя открыть на чтение списка (нет прав, его не отдаёт
примонтированный том), пропускается, а не роняет скан. Какие каталоги пропущены в
последнем обходе, возвращает skipped():
$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: первый старт обходит дерево и записывает список найденных имён классов; последующие
старты загружают этот список и полностью пропускают обход.
Scanner::run(__DIR__ . '/src', cache: __DIR__ . '/var/cache/di.php')
->collect(new DICollector($container))
->execute();Файл кэша — обычный PHP-массив полностью квалифицированных имён классов:
<?php
return [
'App\\Service\\UserService',
'App\\Repository\\UserRepository',
// ...
];Инвалидация кэша
Кэш хранит список классов, а не привязки. Добавление, переименование или перемещение класса делает список устаревшим — удалите файл кэша, чтобы принудительно пересканировать при следующем старте. Встройте это в шаг деплоя.
Исключение каталогов
vendor/ исключается всегда — в каждом сканируемом каталоге. Добавьте другие пути через
exclude() (абсолютные пути):
Scanner::run(__DIR__ . '/src')
->exclude([
__DIR__ . '/src/legacy',
__DIR__ . '/src/generated',
])
->collect(new DICollector($container))
->execute();В исключённый каталог сканер не заходит вовсе — его файлы не читаются. Совпадение
считается по границе каталога: исключение vendor не задевает соседний vendor-tools/.
Запуск нескольких коллекторов за один проход
DICollector — один коллектор; у фреймворка их обычно больше (маршруты, обработчики
исключений, консольные команды). Зарегистрируйте их все на одном Scanner, и они разделят
один обход файловой системы — ни один класс не читается дважды.
Scanner::run(__DIR__ . '/src', cache: $cachePath)
->collect(new DICollector($container)) // scope-атрибуты
->collect(new MappingCollector($router)) // атрибуты маршрутов
->collect(new ExceptionCollector()) // обработчики исключений
->execute();Коллекторы вызываются в порядке регистрации для каждого класса.
Напишите свой коллектор
Любой класс, реализующий CollectorInterface, может присоединиться к сканированию. Он получает
имя каждого класса и ReflectionClass — делайте своё чтение атрибутов и регистрацию.
<?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() выполняется в плотном цикле по потенциально сотням классов. Делайте там только
дешёвую работу (чтение атрибутов, регистрация привязки); откладывайте инстанцирование и
тяжёлую настройку на время разрешения.
Связанное
- Scope’ы — что означает каждый атрибут
- Атрибуты — справочник по scope-атрибутам
- Сервис-провайдеры — привязки, которые атрибуты не выразят
- Жизненный цикл разрешения — что происходит при
make()