gadwinn / psr-container
PSR-11 container with shared services, factories and constructor autowiring.
Requires
- php: >=8.3
- psr/container: ^2.0
Requires (Dev)
- phpdocumentor/shim: *
- phpstan/phpstan: *
- phpunit/phpunit: *
- povils/phpmnd: *
- roave/security-advisories: dev-latest@dev
- squizlabs/php_codesniffer: *
Suggests
None
Provides
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 17:59:21 UTC
README
A small PHP 8.3+ dependency injection container implementing PSR-11, with shared services, factories and constructor autowiring.
Installation
composer require gadwinn/psr-container
Usage
Defining and reading entries
use G\Container\Container; $container = new Container(); $container ->set('app.name', 'My application') // plain value ->set(Mailer::class, Mailer::class) // class name: instantiated on first get() ->set(Clock::class, fn () => new SystemClock()); // factory: called on first get() $container->get('app.name'); // 'My application' $container->get(Mailer::class); // Mailer instance $container->has('unknown'); // false
set() with null removes the entry. Setting an identifier again replaces its definition and
forgets the instance built from the previous one.
What gets built, what is returned as is
| Entry value | Behaviour of get() |
|---|---|
Closure |
called, result returned |
array callable ([$object, 'method'], [Foo::class, 'create']) |
called, result returned |
| name of an existing class | instantiated (see autowiring) |
| anything else | returned as is |
A string is only ever treated as a class name: a value such as 'date' or 'Foo::bar' is
never called, even though PHP considers it callable. Likewise, an object is always returned
as is, even when it is invokable. Wrap it in a closure if you need it to act as a factory.
Shared services and factories
By default the value built for an entry is shared: it is built once and the same value is
returned by every get(). Flag an entry with isFactory() to build a new value each time:
$container->set(Mailer::class, Mailer::class); // shared $container->set(Message::class, Message::class)->isFactory(); // new instance on every get() $container->isFactory(Message::class); // same, by identifier
Autowiring
A class which was never defined with set() is built on first get() when it is
instantiable, then shared like any other service: there is no need to declare classes whose
constructor the container can resolve on its own.
$container = new Container(); $container->has(Mailer::class); // true: Mailer is an instantiable class $container->get(Mailer::class); // built once, then shared
Interfaces, abstract classes, enums and traits cannot be instantiated: has() returns false
and get() throws a NotFoundException asking to define the implementation to use:
$container->set(LoggerInterface::class, FileLogger::class);
The container itself is available under Psr\Container\ContainerInterface (and its own class
name), unless you define that identifier yourself. isDefined($id) tells whether an
identifier was defined with set() (or designates the container), as opposed to a class which
would only be autowired. isResolved($id) tells whether its shared instance has already been
built, which lets you act on a service only when it was used (for example, reset it between
two requests of a long-running worker without building it).
Constructor and factory parameters
The parameters of a constructor (class name entries, autowired classes) and of a factory (Closure or array callable) are resolved in this order:
- a parameter whose type is a class or an interface defined in the container receives that entry
(a parameter typed
ContainerInterfacetherefore receives the container); - otherwise the default value of the parameter is used, if any: an optional parameter is never autowired;
- otherwise a parameter whose type is an instantiable class is autowired;
- otherwise
nullis used when the parameter is a nullable class or interface; - otherwise a
ContainerExceptionis thrown, naming the parameter and the class or factory.
Union and intersection types are not autowired.
final class Mailer { public function __construct(private LoggerInterface $logger, private int $retries = 3) { } } $container->set(LoggerInterface::class, fn () => new FileLogger('/var/log/app.log')); $container->get(Mailer::class); // Mailer built with the FileLogger and 3 retries
Use a factory for anything autowiring cannot guess; it receives the container, and any other service it asks for by type:
use Psr\Container\ContainerInterface; $container->set( Mailer::class, fn (ContainerInterface $c) => new Mailer($c->get(LoggerInterface::class), 5) ); $container->set(Report::class, fn (Mailer $mailer, Clock $clock) => new Report($mailer, $clock->now()));
As in most PHP containers, an untyped first parameter receives the container too:
fn ($c) => new Mailer($c->get(LoggerInterface::class), 5).
When a dependency cannot be built, the message of the ContainerException keeps the chain of
the entries being built (Unable to resolve the dependency 'B' of the class 'A': ...).
Errors
| Situation | Exception |
|---|---|
| Unknown identifier, undefined interface, abstract class, enum or trait | G\Container\Exception\NotFoundException (Psr\Container\NotFoundExceptionInterface) |
| Entry that cannot be built: unresolvable parameter, missing dependency, class not instantiable, circular dependency | G\Container\Exception\ContainerException (Psr\Container\ContainerExceptionInterface) |
As required by PSR-11, a missing dependency of an existing entry is reported as a
ContainerException, not as a NotFoundException. Exceptions thrown by your own factories
and constructors are not wrapped.
Custom resolver
The way entries are built can be replaced by passing your own
G\Container\Resolver\ResolverInterface to the constructor:
$container = new Container($myResolver);
Development
composer install
composer test-all # security audit, code style, static analysis, unit tests, magic numbers
License
MIT, see LICENSE.