README

🧩 Omegaalfa Container

Dependency Injection PSR-11 explícito e tipado para PHP 8.4

O problema que este pacote resolve

Em uma aplicação pequena, montar objetos manualmente é simples:

$config = new Config(...);
$logger = new Logger(...);
$database = new Database($config, $logger);
$repository = new UserRepository($database);
$service = new UserService($repository, $logger);
$controller = new UserController($service);

Conforme a aplicação cresce, essa montagem se repete. A ordem fica difícil de controlar, trocar implementações exige mudanças em vários arquivos, algumas instâncias precisam ser compartilhadas e outras precisam ser novas. Testes também passam a conhecer detalhes de infraestrutura.

Com o container, as regras ficam centralizadas:

use Omegaalfa\Container\ContainerBuilder;
use Psr\Container\ContainerInterface;

$builder = new ContainerBuilder();
$builder->set(Config::class, new Config(...));
$builder->singleton(Logger::class, static fn(): Logger => new Logger());
$builder->singleton(
    Database::class,
    static fn(ContainerInterface $container): Database => new Database(
        $container->get(Config::class),
        $container->get(Logger::class),
    ),
);
$builder->autowire(UserRepository::class);
$builder->autowire(UserService::class);
$builder->autowire(UserController::class);
$container = $builder->build();
$controller = $container->get(UserController::class);

Em vez de cada parte da aplicação decidir como criar suas dependências, essa responsabilidade fica concentrada na configuração do container.

O que é injeção de dependências?

Sem injeção, uma classe cria internamente aquilo de que precisa:

final class UserService
{
    public function __construct()
    {
        $database = new Database();
        $this->repository = new UserRepository($database);
    }
}

Com injeção, a classe recebe a dependência:

final class UserService
{
    public function __construct(private UserRepository $repository)
    {
    }
}

Dependency Injection é uma técnica de projeto. O container é uma ferramenta que ajuda a aplicá-la; eles não são a mesma coisa.

ContainerBuilder e Container: qual é a diferença?

O builder funciona como a receita; o container é a estrutura pronta.

Objeto	Responsabilidade
`ContainerBuilder`	Registrar e configurar serviços
`Container`	Resolver e devolver serviços durante a execução
`build()`	Criar um snapshot da configuração atual

Snapshot é uma cópia naquele momento. Alterar o builder depois de build() não altera containers já construídos. Cada container mantém seus próprios singletons e proxies lazy.

Exemplo completo para iniciantes

O arquivo examples/beginner.php demonstra set(), singleton(), factory(), autowire(), alias(), lazy(), get(), has(), make() e call().

composer install
php examples/beginner.php

Important

O builder configura; o container resolve. Autowiring é explícito, interfaces não são adivinhadas e escalares nunca são inventados.

📑 Índice

Recursos e instalação
Início rápido
Ciclos de vida
Values, singletons, factories e aliases
Autowiring
make() e call()
Lazy services
Referência da API pública
Exceções e PSR-11
Workers, segurança e limitações
Desenvolvimento

✨ Recursos

📦 values prontos: escalares, objetos e closures;
♻️ singletons lazy por container;
🏭 factories transient;
🔗 aliases que preservam o ciclo de vida;
🧠 autowiring explícito por construtor e cache de Reflection;
🧰 make() para criação transient e call() para invocação;
💤 proxies nativos via omegaalfa/lazy-object;
🔄 ciclos detectados com caminho completo;
✅ Psr\Container\ContainerInterface.

📋 Instalação

Requer PHP ^8.4, Composer 2 e psr/container ^2.0.

composer require omegaalfa/container

Para lazy services:

composer require omegaalfa/lazy-object

Checkout local:

composer install
php exemplo.php

🚀 Início rápido

<?php

declare(strict_types=1);

use Omegaalfa\Container\ContainerBuilder;
use Psr\Container\ContainerInterface;

$builder = new ContainerBuilder();
$builder->set('app.name', 'Minha aplicação');
$builder->set(Config::class, new Config('production'));
$builder->singleton(
    Logger::class,
    static fn (ContainerInterface $_container): Logger => new Logger(),
);
$builder->alias(LoggerInterface::class, Logger::class);
$builder->autowire(UserRepository::class);
$builder->autowire(UserService::class);

$container = $builder->build();
$service = $container->get(UserService::class);

O arquivo exemplo.php é executável e cobre todos os recursos principais:

php exemplo.php

🔁 Ciclos de vida

Registro	Execução	Cache	Identidade
`set()`	valor já pronto	definição	sempre a mesma
`singleton()`	primeiro `get()`	resultado	a mesma por container
`factory()`	todo `get()`	nenhum	normalmente diferente
`autowire()`	todo `get()`	nenhum	diferente
`lazy()`	proxy no primeiro `get()`; real no acesso	proxy	mesmo proxy
`alias()`	segue destino	segue destino	segue destino
`make()`	toda chamada	nenhum	diferente

Containers de chamadas distintas a build() não compartilham singletons, proxies ou estado de resolução.

📦 Values, singletons, factories e aliases

Value

set() devolve exatamente o valor registrado. Closure registrada assim não é executada.

$builder->set('app.name', 'Omegaalfa');
$builder->set('limit', 100);
$builder->set(LoggerInterface::class, new ConsoleLogger());
$builder->set('callback', static fn (): string => 'valor');

Singleton

A factory executa uma vez, somente no primeiro get().

$builder->singleton(
    DatabaseConnection::class,
    static fn (ContainerInterface $container): DatabaseConnection =>
        new DatabaseConnection($container->get(Config::class)->dsn),
);

Falhas não armazenam resultados parciais. A exceção original é preservada e outra resolução tenta novamente.

Factory transient

Executa em cada resolução e não armazena resultado.

$builder->factory(
    RequestContext::class,
    static fn (ContainerInterface $_container): RequestContext => new RequestContext(),
);

Alias

$builder->singleton(RedisCache::class, static fn (): RedisCache => new RedisCache());
$builder->alias(CacheInterface::class, RedisCache::class);

O alias preserva o ciclo de vida do destino. Self-alias é rejeitado. Destino ausente ou cadeia circular faz has() retornar false.

Note

O container pode ser usado em factories na composition root. Evite injetá-lo nos serviços como Service Locator.

🧠 Autowiring

$builder->autowire(UserRepository::class);
$builder->autowire(UserService::class);

Política:

resolve tipos de objeto registrados;
interfaces exigem registro ou alias explícito;
usa defaults quando não há resolução;
nullable recebe null sem candidato;
escalares obrigatórios e parâmetros sem tipo não são inventados;
union exige exatamente um candidato;
intersection é rejeitada;
classes abstratas, inexistentes e construtores não públicos são rejeitados;
variádicos sem valores explícitos ficam vazios;
nenhuma propriedade é injetada após a construção.

final readonly class UserService
{
    public function __construct(
        public UserRepository $repository,
        public int $limit = 25,
    ) {}
}

🧰 `make()` e `call()`

make() cria objeto transient, resolve dependências e aceita parâmetros por nome:

$controller = $container->make(
    UserController::class,
    ['request' => $request, 'limit' => 50],
);

Não modifica eventual singleton registrado. Parâmetro desconhecido ou obrigatório ausente gera UnresolvableParameterException.

call() resolve closures, funções e métodos:

$result = $container->call(
    [$controller, 'handle'],
    ['request' => $request],
);

$result = $container->call(
    static fn (LoggerInterface $logger, string $message): string =>
        $handler->handle($logger, $message),
    ['message' => 'Processar pedido'],
);

O retorno não é transformado. Use somente callables confiáveis.

💤 Lazy services

lazy() chama Omegaalfa\LazyObject\LazyObject::proxy(); não há proxy próprio.

$builder->lazy(
    ReportGenerator::class,
    static fn (ContainerInterface $container): ReportGenerator =>
        new ReportGenerator($container->get(DatabaseConnection::class)),
    ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE,
);

$container = $builder->build();
$report = $container->get(ReportGenerator::class); // proxy
echo $report->status; // inicializa a instância real

Comportamento:

registro, build() e has() não executam a factory;
o primeiro get() cria um proxy ainda não inicializado;
o proxy é singleton por container;
a factory captura o container, nunca o builder;
opções nativas são encaminhadas sem alteração;
pacote ausente gera LazyServiceException, sem fallback eager;
erros da biblioteca e do PHP são preservados;
classes sem propriedades podem não permanecer lazy.

Lazy loading adia criação; não substitui Dependency Injection.

📚 Referência da API pública

`ContainerBuilder`

Assinatura	Descrição
`set(string $id, mixed $value, bool $override = false): self`	Registra valor pronto.
`singleton(string $id, Closure $factory, bool $override = false): self`	Factory compartilhada.
`factory(string $id, Closure $factory, bool $override = false): self`	Factory transient.
`alias(string $id, string $target, bool $override = false): self`	Identificador alternativo.
`autowire(string $class, bool $override = false): self`	Construção explícita por Reflection.
`lazy(string $class, Closure $factory, int $options = 0, bool $override = false): self`	Proxy lazy singleton.
`addDefinitions(array $definitions, bool $override = false): self`	Objetos de definição; API de baixo nível.
`build(): Container`	Snapshot independente das definições.

Identificador vazio é rejeitado. Duplicatas exigem override: true. Containers já construídos não mudam quando o builder é alterado.

`Container`

Assinatura	Descrição
`get(string $id): mixed`	Resolve entrada conforme o ciclo de vida.
`has(string $id): bool`	Verifica sem construir ou executar factory.
`make(string $class, array $parameters = []): object`	Cria instância transient.
`call(callable $callable, array $parameters = []): mixed`	Injeta argumentos e invoca callable.

has() === true indica definição conhecida, não que a construção futura será infalível. Prefira ContainerBuilder::build() ao construtor direto de Container.

🚨 Exceções

Exceção	Situação
`ContainerException`	base PSR-11
`NotFoundException`	entrada ausente; implementa `NotFoundExceptionInterface`
`CircularDependencyException`	ciclo em alias, factory ou autowiring
`InvalidDefinitionException`	id vazio, duplicata ou definição inválida
`AutowiringException`	classe não construível
`AmbiguousTypeException`	union ambígua
`UnresolvableParameterException`	parâmetro não resolvível
`LazyServiceException`	pacote lazy ausente

Circular dependency detected: A -> B -> C -> A

Exceções de factories, construtores e callables consumidores são preservadas.

🔌 PSR-11

Container implementa Psr\Container\ContainerInterface. A PSR-11 padroniza apenas get() e has(); registros são extensões do pacote.

function boot(Psr\Container\ContainerInterface $container): void
{
    if ($container->has(Application::class)) {
        $application = $container->get(Application::class);
    }
}

O Composer fornece psr/container-implementation: 1.0.0, conforme a PSR-11. Isso é independente de psr/container ^2.0.

🧵 Workers, segurança e limitações

Não existe estado estático global. Singletons vivem enquanto o container; em workers persistentes, reusar o container também mantém singletons e proxies. Não há escopo automático por request, Fiber, coroutine ou tenant.

Identificadores, classes, factories e callables são configuração executável confiável. Não encaminhe entrada HTTP diretamente a get(), make() ou call() e não carregue definições remotas.

Ainda não existem bindings contextuais, atributos, property injection, autowiring implícito por get(), lazy ghosts, lazy transient, compilação ou escopos complexos. Consulte ROADMAP.md.

🧪 Desenvolvimento

composer install
composer test
composer analyse
composer lint
composer check
XDEBUG_MODE=coverage composer coverage
composer benchmark
php exemplo.php

O benchmark usa hrtime(true), warm-up e várias rodadas. Resultados dependem de hardware, OPcache, JIT e carga.

📄 Licença

Distribuído sob a licença MIT.

omegaalfa / container

Maintainers

Package info

Statistics

Security

README

🧩 Omegaalfa Container

Dependency Injection PSR-11 explícito e tipado para PHP 8.4

O problema que este pacote resolve

O que é injeção de dependências?

ContainerBuilder e Container: qual é a diferença?

Exemplo completo para iniciantes

📑 Índice

✨ Recursos

📋 Instalação

🚀 Início rápido

🔁 Ciclos de vida

📦 Values, singletons, factories e aliases

Value

Singleton

Factory transient

Alias

🧠 Autowiring

🧰 `make()` e `call()`

💤 Lazy services

📚 Referência da API pública

`ContainerBuilder`

`Container`

🚨 Exceções

🔌 PSR-11

🧵 Workers, segurança e limitações

🧪 Desenvolvimento

📄 Licença

omegaalfa / container

Maintainers

Package info

Statistics

Security

README

🧩 Omegaalfa Container

Dependency Injection PSR-11 explícito e tipado para PHP 8.4

O problema que este pacote resolve

O que é injeção de dependências?

ContainerBuilder e Container: qual é a diferença?

Exemplo completo para iniciantes

📑 Índice

✨ Recursos

📋 Instalação

🚀 Início rápido

🔁 Ciclos de vida

📦 Values, singletons, factories e aliases

Value

Singleton

Factory transient

Alias

🧠 Autowiring

🧰 make() e call()

💤 Lazy services

📚 Referência da API pública

ContainerBuilder

Container

🚨 Exceções

🔌 PSR-11

🧵 Workers, segurança e limitações

🧪 Desenvolvimento

📄 Licença

🧰 `make()` e `call()`

`ContainerBuilder`

`Container`