RUEN
Пакет · di

Справочник API

Полный справочник по публичной поверхности Winter DI. Это авторитетный источник сигнатур и значений по умолчанию; страницы руководств и глубокого погружения ссылаются сюда.

Container

final class Container implements Psr\Container\ContainerInterface. Реестр и резолвер. Он саморегистрируется, поэтому Container и ContainerInterface можно внедрять как зависимости.

Инициализация

php
Container::init(): static
Container::getInstance(): static
Метод Описание
init() Создаёт новый контейнер и сохраняет его как процессный синглтон. Вызывается один раз при bootstrap. Возвращает экземпляр для fluent-цепочки.
getInstance() Возвращает инициализированный контейнер. Бросает ContainerException, если init() не вызывался.

PSR-11

php
get(string $id): mixed
has(string $id): bool
Метод Описание
get($id) Псевдоним для make($id). Бросает NotFoundException, если у $id нет привязки и это не инстанцируемый класс.
has($id) true, если у $id есть привязка, разрешённое / set()-значение, или совпадает с существующим именем класса (class_exists).

Регистрация

php
bind(string $abstract, string|callable $concrete): static
singleton(string $abstract, string|callable|null $concrete = null): static
transient(string $abstract, string|callable|null $concrete = null): static
request(string $abstract, string|callable|null $concrete = null): static
contextual(string $abstract, callable $factory): static
set(string $id, mixed $value): static
Метод Scope Описание
bind() transient Сопоставляет $abstract конкретному классу или фабрике-замыканию. Новый экземпляр при каждом разрешении.
singleton() singleton Один общий экземпляр на процесс. $concrete по умолчанию $abstract (самопривязка).
transient() transient Как bind(), но допускает самопривязку, когда $concrete равен null.
request() request Один экземпляр на HTTP-запрос / корутину. $concrete по умолчанию $abstract.
contextual() — Фабрика, знающая потребителя: fn(Container $c, ?string $consumer). Наложение на время внедрения; результат никогда не кэшируется. См. makeContextual().
set() — Сохраняет скаляр или заранее построенный экземпляр под именованным ключом. Извлекается через make($id) или #[Inject('id')].

Фабрика-замыкание, переданная в bind() / singleton() / transient() / request(), получает контейнер: fn(Container $c) => new Service($c->make(Dep::class)).

Ручная регистрация переопределяет атрибуты

Вызов bind()/singleton()/request() всегда имеет приоритет над scope-атрибутом класса. Повторная регистрация того же абстракта заменяет предыдущую привязку.

Разрешение

php
make(string $abstract, array $overrides = []): mixed
call(callable|array $callable, array $overrides = []): mixed
makeContextual(string $abstract, ?string $consumer): mixed

make()

Разрешает абстракт — класс, интерфейс или именованное значение.

Параметр Тип По умолчанию Описание
$abstract string — Имя класса/интерфейса или ключ именованного значения.
$overrides array [] Переопределения параметров по имени. Обходит автовайринг для этих параметров.

Порядок разрешения: (1) уже разрешённый синглтон / set()-значение, (2) кэш request-scope в контексте корутины, (3) ручная привязка, (4) автовайринг по имени класса. Передача $overrides всегда строит свежий экземпляр и никогда не кэшируется. Бросает NotFoundException, если не разрешить, ContainerException при циклической зависимости.

call()

Вызывает метод или замыкание с параметрами, разрешёнными из контейнера.

php
$c->call([UserController::class, 'index']);   // разрешить класс, затем вызвать
$c->call([$controller, 'store']);              // существующий экземпляр
$c->call(fn(UserService $s) => $s->all());     // замыкание
$c->call([ImportJob::class, 'run'], ['chunkSize' => 100]);  // с overrides
Параметр Тип По умолчанию Описание
$callable callable|array — [class-string, method], [object, method] или любой callable/замыкание.
$overrides array [] Переопределения параметров по имени.

makeContextual()

php
makeContextual(string $abstract, ?string $consumer): mixed

Точка входа резолвера для контекстного внедрения. Если для $abstract зарегистрирована фабрика contextual(), она вызывается с $consumer (результат не кэшируется); иначе делегирует make($abstract). Прикладной код обычно использует make() — это существует для механизма внедрения. Контекстное наложение применяется только при внедрении (конструктор / метод / свойство); прямой make()/get() использует обычную привязку.

Провайдеры

php
register(string $providerClass): static

Инстанцирует $providerClass, проверяет, что он наследует ServiceProvider, и сразу выполняет его register(). Бросает ContainerException, если класс не наследует ServiceProvider.

Scanner

Проходит по дереву проекта один раз и передаёт каждый найденный класс всем зарегистрированным коллекторам.

php
Scanner::run(string $rootDir, ?string $cache = null): static
  ->collect(CollectorInterface $collector): static
  ->exclude(array $dirs): static
  ->execute(): void
Метод Описание
run($rootDir, $cache) Создаёт сканер для $rootDir. Когда $cache — путь: попадание в кэш загружает список FQCN и пропускает обход ФС; промах обходит и записывает список. null (по умолчанию) всегда обходит, никогда не кэширует.
collect($collector) Регистрирует коллектор, получающий каждый найденный класс. Вызываются в порядке регистрации.
exclude($dirs) Добавляет абсолютные пути каталогов для исключения. vendor/ исключается всегда.
execute() Запускает сканирование. Абстрактные классы, интерфейсы и трейты пропускаются до запуска коллекторов.

Файл кэша — обычный PHP-файл, возвращающий string[] FQCN. Удалите его, чтобы принудительно пересканировать. См. Сканирование и автообнаружение.

DICollector

final readonly class DICollector implements CollectorInterface. Встроенный коллектор, регистрирующий классы со scope-атрибутом.

php
new DICollector(Container $container)
collect(string $class, ReflectionClass $ref): void
Атрибут класса Регистрация
#[Singleton] $container->singleton($class)
#[Request] $container->request($class)
#[Transient] $container->transient($class)

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

CollectorInterface

Реализуйте, чтобы подключить свою логику к проходу Scanner.

php
interface CollectorInterface
{
  // @param class-string $class  FQCN
  // @param ReflectionClass $ref  экземпляр рефлексии
  public function collect(string $class, ReflectionClass $ref): void;
}

collect() вызывается один раз на инстанцируемый класс, в плотном цикле — держите его лёгким.

ServiceProvider

Абстрактная база для группировки привязок.

php
abstract class ServiceProvider
{
  abstract public function register(Container $c): void;
}

Регистрируется через $container->register(MyProvider::class). См. Сервис-провайдеры.

ReflectionCache

Кэш объектов рефлексии на процесс — строится один раз, переиспользуется всё время жизни процесса.

php
ReflectionCache::classOf(string $class): ReflectionClass
ReflectionCache::enumOf(string $enum): ReflectionEnum
ReflectionCache::method(string $class, string $method): ReflectionMethod
ReflectionCache::parameters(string $class, string $method): ReflectionParameter[]
Метод Возвращает Примечания
classOf($class) ReflectionClass Кэшируется по классу.
enumOf($enum) ReflectionEnum Кэшируется по enum.
method($class, $method) ReflectionMethod Кэшируется по class::method.
parameters($class, $method) ReflectionParameter[] Делегирует method(); разделяет его запись кэша.

Публичная утилита — см. Кэш рефлексии.

Исключения

Оба реализуют интерфейсы исключений PSR-11 и наследуют \RuntimeException.

Исключение Реализует Бросается когда
NotFoundException Psr\Container\NotFoundExceptionInterface Нет привязки для id, и это не инстанцируемый класс.
ContainerException Psr\Container\ContainerExceptionInterface Циклическая зависимость, неразрешимый параметр, неинициализированный контейнер, неверный провайдер, неверная цель #[Lazy].

Атрибуты

Справочные таблицы по #[Singleton], #[Request], #[Transient], #[Autowired], #[Inject] и #[Lazy] находятся на странице Атрибуты.