README

CloudCastle DI

Lightweight PSR-11 dependency injection container for PHP 8.1+
Лёгкий DI-контейнер: autowiring, конфигурация PHP/JSON/YAML/XML, scan, теги, декораторы.

⚡ Quick start · 📊 Сравнение · 📚 Wiki · Packagist · Releases

English: Lightweight PSR-11 dependency injection container for PHP 8.1+. Explicit set() / get() wiring, optional constructor/property/method autowiring, declarative configuration (PHP/JSON/YAML/XML, parameters + %env(...)%), directory scan, prototypes (make), aliases, lazy services, callable invocation (call), interface binding (bind), after-resolving hooks, custom inject attributes, tagged services (ids / iterator / locator), decorators, global registry — plus (v1.20) autoconfigure, extensions + compiler passes, #[AsService] auto-registration, service subscribers, and (v1.21) before-resolving hook, config-level calls: / factory: / parent / deprecated: / when@env, tag priority, #[AsDecorator] / #[Exclude] / #[AsAlias], config schema validation, stateful reset(), generated factory interfaces and a composite container — one runtime dependency (psr/container).

Русский: Лёгкий контейнер внедрения зависимостей для PHP 8.1+ с поддержкой PSR-11. Явная регистрация сервисов, singleton-фабрики, autowiring конструктора, свойств и методов, конфигурация из файлов (+ параметры и %env(...)%), сканирование каталогов, прототипы, alias, lazy, вызов callable с autowire, bind, afterResolving, пользовательские attributes, теги, декораторы и глобальный реестр. С v1.20 — autoconfigure (авто-тег реализаций интерфейса), расширения + compiler passes, авто-регистрация #[AsService] и service subscribers (scoped-локатор). С v1.21 — beforeResolving(), конфиг-возможности (calls: / factory: / parent / deprecated: / when@env), приоритет тегов, атрибуты #[AsDecorator] / #[Exclude] / #[AsAlias], валидация схемы конфига, reset() stateful, генерируемые фабрики-интерфейсы и композитный контейнер. Полный каталог — Возможности.

📊 Сравнение с аналогами

TL;DR (по честным тестам и фактам). Берите CloudCastle DI, если нужен быстрый standalone-контейнер для библиотеки / CLI / API с одной зависимостью psr/container: он обгоняет PHP-DI / Laravel / Pimple в get / has / make / autowire и Symfony / PHP-DI / Nette в compiled-режиме, единственный несёт object-pool / профилирование / TTL и детектит циклы (где Laravel зависает). Начиная с v1.20 несёт и «фреймворковые» возможности standalone: autoconfigure, параметры + env в конфиге, расширения + compiler passes, авто-регистрацию #[AsService], service subscribers; в v1.21 закрыт роадмап паритета — beforeResolving(), декларативные calls: / factory: / parent / deprecated: / when@env, приоритет тегов, атрибуты #[AsDecorator] / #[Exclude] / #[AsAlias], валидация конфига, reset() для long-running, фабрики-интерфейсы и композитный контейнер. Берите другой, если вы уже в экосистеме Symfony / Laravel / Nette, вам критичен минимум памяти пустого объекта (тогда Pimple / Laravel), либо нужны сам фреймворк и его интеграции (bundles, kernel, HTTP-слой). Числа и пороги качества — на Wiki (ссылки ниже), всё проверяемо.

Полные таблицы — возможности и замеры производительности (5 аналогов, колонка 🏆 победитель, усреднение по PHP 8.1–8.5) автоматически обновляются на Wiki: Comparison. Пороги качества — на Wiki: Testing.

Здесь, в README, эти таблицы намеренно не дублируются: файл в репозитории не обновляется автоматически, а на Wiki они пересобираются из тестов после каждого прогона.

✅ Подходит	❌ Лучше другой
Composition root, CLI, API, библиотеки	Уже Symfony / Laravel / Nette
Autowiring + compiled + contextual без фреймворка	Legacy PHP < 8.1
Одна зависимость `psr/container`	3–5 `set()` без autowire → Pimple

🧩 Возможности

📖 Детальный разбор каждой возможности — принцип работы, плюсы/минусы, примеры кода, рекомендации и антипаттерны, аналог в каждом из 5 конкурентов — в разделе Возможности в Wiki.

Базовый DI · Autowiring · Scan · Config · Tags

Категория	Возможности
Базовый DI	`set()` / `get()` / `has()`, фабрики, singleton-кэш, PSR-11
Autowiring	constructor, property, method; `Inject` / `Autowire`; union, intersection
Scan	`scan()` — обход каталога, фильтр namespace
Конфиг	`ContainerConfigurator` — PHP, JSON, YAML, XML; priority; каталоги (v1.7); параметры + `%env(...)%` (v1.20)
Расширения	`make()`, `alias()`, `lazy()`, `lazyGhost()` (v1.18), `call()`, `bind()`, `afterResolving()`
Теги	`tag()`, iterator, locator, `decorate()`
Прочее	`freeze()`, `dump()`, `ContainerRegistry`
Compiled (v1.9)	`ContainerCompiler` — PHP-класс без reflection на hot path
Contextual (v1.10–1.13)	`when()->needs()->give()` — runtime, config, compiled (#25)
Observability (opt-in)	profiler (v1.15), memory pool (v1.16), smart cache TTL (v1.17) — см. Performance
Scopes (v1.19)	`scoped()`, `beginScope()` / `endScope()`, вложенные scope-ы (#33)
v1.20	`autoconfigure()`, `registerExtension()` / `addCompilerPass()` / `build()`, `#[AsService]`, `ServiceSubscriberInterface` (scoped-локатор) — Возможности
v1.21	`beforeResolving()`; в конфиге — `calls:` / `factory:` / `parent` / `deprecated:` / `when@env`; приоритет тегов; `#[AsDecorator]` / `#[Exclude]` / `#[AsAlias]`; валидация схемы конфига; `reset()` stateful; генерируемые фабрики-интерфейсы; `CompositeContainer` — Возможности

🏗️ Как это устроено

flowchart TB
    subgraph entry [Точки входа]
        GET["get() — singleton"]
        MAKE["make() — прототип"]
        CALL["call() — autowire callable"]
    end

    subgraph bootstrap [Bootstrap]
        REG_API["set / bind / autowire / scan"]
        CONFIG["ContainerConfigurator"]
        FREEZE["freeze()"]
    end

    subgraph container [Container]
        RESOLVE[ServiceInstanceResolver]
        AUTO[Autowirer]
        DECO[decorators]
        TAGS[tags]
    end

    REG_API --> RESOLVE
    CONFIG --> REG_API
    GET --> RESOLVE
    MAKE --> RESOLVE
    CALL --> AUTO
    RESOLVE --> AUTO
    RESOLVE --> DECO
    FREEZE -.->|блокирует| REG_API

Схемы всех потоков — Wiki: Архитектура.

📋 Требования

PHP ^8.1 (CI: 8.1–8.5)
psr/container ^2.0
Опционально: ext-yaml — YAML-конфигурация

📦 Установка

composer require cloudcastle/di

⚡ Быстрый старт

<?php

use CloudCastle\DI\Container;

$container = new Container();
$container->enableAutowiring();
$container->bind(LoggerInterface::class, FileLogger::class);

$service = $container->get(App\Service\UserService::class);

Больше примеров — Wiki: Quick start · Bootstrap.

Примеры: явная регистрация, autowiring, scan, теги, конфиг

Явная регистрация

$container = new Container();
$container->set('logger', new Psr\Log\NullLogger());
$container->set(
    'repository',
    static fn (Container $c) => new UserRepository($c->get('logger')),
);

Autowiring + attributes

$container->enableAutowiring();
$container->enableParameterNameAutowiring();
$userService = $container->get(App\Service\UserService::class);

Scan, bind, call, tags

$container->scan(__DIR__ . '/Services', 'App\\Services\\');
$container->bind(LoggerInterface::class, FileLogger::class);
$container->call(static fn (LoggerInterface $log) => $log->info('ok'));
$container->tag('handler.email', 'handlers');

Конфигурация из файлов

use CloudCastle\DI\Configuration\ContainerConfigurator;

(new ContainerConfigurator())->configure($container, [
    __DIR__ . '/config/services.php',
]);
$container->freeze();

📚 Документация

Раздел	Ссылка
📚 Wiki — главная	Home
📊 Сравнение (таблица)	Comparison
⚡ Быстрый старт	Quick-start
🏗️ Архитектура	Architecture
📄 Конфигурация	Configuration
📖 Справочник конфига	Configuration-reference
📋 API	API-reference
🚀 Compiled container	Compiled-container
🔗 Contextual binding	Contextual-binding

Исходники Wiki — каталог wiki/. API после composer docs → docs/.

🧪 Качество

Пороги качества (Infection MSI ≥ 98%, покрытие ≥ 95%/файл, лимиты phpmd, PHP 8.1–8.5) генерируются из конфигов и публикуются на Wiki: Testing — в README не дублируются (файл в репозитории не обновляется автоматически).

Прогнать весь пайплайн качества локально:

composer install
composer ci


Тесты	PHPUnit: unit + integration + security + load + performance; актуальные числа по версиям PHP — Test-reports
Статика	PHPStan max, Psalm 6 (errorLevel 1), PHPMD, Deptrac, Rector
Coverage	≥95% line (per-file), ~99.8% типично; Infection MSI ≥98%
CI	PHP 8.1–8.5, benchmark-check, CodeQL

Wiki: Testing · Performance-and-load

💬 Сообщество

Discussions — вопросы и идеи
Issues — баги и задачи

📜 Лицензия

MIT

cloudcastle / di

Maintainers

Package info

Statistics

Security