Справочник API

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

Container

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

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

Container::init(): static
Container::getInstance(): static
Container::isInitialized(): bool

PSR-11

get(string $id): mixed
has(string $id): bool

Регистрация

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

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

Разрешение

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

make()

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

Порядок разрешения: (1) уже разрешённый синглтон / set()-значение, (2) кэш request-scope в контексте корутины, (3) проверка цикла по стеку текущей единицы работы, (4) ожидание синглтона, который строит другая корутина, (5) ручная привязка, (6) автовайринг по имени класса. Передача $overrides всегда строит свежий экземпляр и никогда не кэшируется. Бросает NotFoundException, если не разрешить, ContainerException при циклической зависимости — с полной цепочкой вида [A] → [B] → [A]. Шаги 3 и 4 разобраны в Конкурентном разрешении.

call()

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

$c->call([UserController::class, 'index']);   // разрешить класс, затем вызвать
$c->call([$controller, 'store']);              // существующий экземпляр
$c->call(fn(UserService $s) => $s->all());     // замыкание
$c->call([ImportJob::class, 'run'], ['chunkSize' => 100]);  // с overrides

makeContextual()

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

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

inject()

inject(object $instance): object

Заполняет свойства #[Autowired] / #[Inject] у объекта, который вы построили сами, и возвращает его же. Это вторая половина make(), вынесенная отдельно: make() и строит, и внедряет — что правильно, когда объект принадлежит контейнеру, и неправильно, когда идентичностью объекта должен управлять вызывающий.

public static function instance(?string $alias = null): static
{
  $repository = new static();                     // идентичность остаётся за вызывающим
  Container::getInstance()->inject($repository);  // зависимости всё равно приезжают

  return $alias === null ? $repository : $repository->as($alias);
}

Классический случай — хэндл репозитория с алиасом запроса: алиас живёт в состоянии объекта, поэтому два алиаса одной таблицы требуют двух разных объектов, а разрешение их через make() на общей привязке схлопнуло бы оба в один и потеряло бы алиас. Экземпляр никогда не подменяется, состояние конструктора не трогается, повторный вызов безвреден.

flushRequestScope()

flushRequestScope(): void

Завершает текущий request-scope: следующее разрешение #[Request]-привязки построит свежий экземпляр. Синглтоны и transient не затрагиваются — это конец scope’а, а не сброс контейнера.

По HTTP scope заканчивается сам: запрос — это корутина, её контекст умирает вместе с ней. Больше ни у чего такой границы нет. Тело долгоживущего воркера целиком выполняется в одной корутине, поэтому request-scoped бин, разрешённый в цикле, живёт весь прогон и передаёт каждой задаче состояние предыдущей:

while ($this->isRunning()) {
  $job = $queue->pop();

  $container->flushRequestScope();             // ← здесь начинается новая единица работы
  $ctx = $container->make(JobContext::class);  // свежий, каждый раз
  // ... работа ...
}

Где заканчивается одна единица работы, знает только код, который крутит цикл, — поэтому вызов явный.

Провайдеры

register(string $providerClass): static

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

Scanner

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

Scanner::run(string $rootDir, ?string $cache = null): static
  ->collect(CollectorInterface $collector): static
  ->exclude(array $dirs): static
  ->execute(): void

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

DICollector

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

new DICollector(Container $container)
collect(string $class, ReflectionClass $ref): void

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

CollectorInterface

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

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

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

ServiceProvider

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

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

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

ProxyInterface

Реализуйте, если генерируете подкласс, который должен разрешаться под именем того класса, чьё место он занимает.

interface ProxyInterface
{
  /** @return class-string  класс, за который выступает этот proxy */
  public static function proxyTarget(): string;
}

Прокси — это сгенерированный класс, наследующий оригинал и добавляющий поведение вокруг его методов: выполнить в фоне, обернуть в транзакцию, закэшировать результат. Именно так устроен #[Async] в ядре Winter. Проблема в том, что после подмены $instance::class возвращает UserService__Async, а не UserService, — и резолвер, который по этому имени решает, для кого строится зависимость, начинает ошибаться: фабрика contextual() назвала бы канал логгера сгенерированным классом.

Реализация интерфейса возвращает идентичность на место: резолвер планирует внедрение от целевого класса и его же передаёт фабрикам как потребителя.

final class UserServiceProxy extends UserService implements ProxyInterface
{
  public static function proxyTarget(): string
  {
      return UserService::class;
  }
}

$container->singleton(UserService::class, UserServiceProxy::class);

Метод статический намеренно: идентичность нужна резолверу до того, как экземпляр существует, — при сборке аргументов конструктора. $instance::class продолжает возвращать сгенерированное имя: интерфейс меняет то, как о нём рассуждает контейнер, а не то, что сообщает PHP. Внедрение в приватные свойства цели при этом работает — резолвер обходит иерархию классов, а не полагается на ReflectionClass::getProperties().

ReflectionCache

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

ReflectionCache::classOf(string $class): ReflectionClass
ReflectionCache::enumOf(string $enum): ReflectionEnum
ReflectionCache::method(string $class, string $method): ReflectionMethod
ReflectionCache::parameters(string $class, string $method): ReflectionParameter[]

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

Исключения

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

Атрибуты

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