Feature Class scanning

📂 Сканирование каталога

← Возможности · Главная · Сравнение

scan() авто-регистрирует классы из каталога по namespace/regex — не нужно перечислять каждый сервис вручную. Туториал — Class-scanning.

Принцип работы

ClassScanner обходит файлы каталога, извлекает объявленные классы (парсинг namespace/class без загрузки), фильтрует по regex/namespace и регистрирует подходящие как autowired. Дальше они разрешаются обычным autowiring.

$c->enableAutowiring();
$c->scan(
    directory: __DIR__ . '/src/Handlers',
    namespace: 'App\\Handlers',
    pattern: '/Handler$/',   // только классы, оканчивающиеся на Handler
);

$c->get(App\Handlers\CreateOrderHandler::class); // авто-зарегистрирован

Плюсы

• Convention over configuration: новые классы по соглашению попадают в контейнер без правок конфига.
• Regex-фильтр даёт точный контроль над тем, что регистрируется.
• Хорошо для однотипных наборов: хендлеры, команды, подписчики.

Минусы

• «Неявная» регистрация — по конфигу не видно полного списка сервисов (используйте dump() для обзора).
• Сканирование файлов имеет стоимость на старте (в проде — compiled, где граф уже собран).

✅ Рекомендуется

• Сканировать узкие, однотипные каталоги (Handlers, Commands) с точным pattern.
• Комбинировать с тегами: сканируем хендлеры → собираем их в tagged-локатор.
• В проде — компилировать контейнер, чтобы убрать сканирование из рантайма.

❌ Антипаттерны

• Сканировать весь src/ без фильтра — регистрируется мусор, теряется контроль и растёт старт.
• Полагаться на сканирование для сервисов, которым нужна особая сборка (их регистрируйте явно).

Исключение из скана (#[Exclude])

Класс с атрибутом #[Exclude] пропускается сканером — не регистрируется и не получает теги/alias'ы/декораторы (аналог Symfony #[Exclude] / exclude:):

use CloudCastle\DI\Attribute\Exclude;

#[Exclude]
final class InternalHelper {}   // лежит в каталоге сервисов, но в контейнер не попадёт

Удобно для базовых/вспомогательных классов рядом с сервисами, которые не должны регистрироваться автоматически.

Аналоги в других контейнерах

Контейнер	Аналог
PHP-DI	нет прямого скана каталога (⚠️ — через autowiring по требованию)
Symfony	resource: + exclude: в конфиге (эталон)
Laravel	автозагрузка + ручная регистрация в провайдерах (⚠️)
Pimple	нет (❌)
Nette	RobotLoader / search в конфиге

Symfony, Nette — развитый скан; CloudCastle даёт regex-скан с явным контролем.

См. также: Class-scanning (гайд) · Теги и tagged services.