PSR-11 compatible dependency injection container that's able to instantiate and configure classes resolving dependencies.
Multibyte String
PHP extension.You could install the package with composer:
composer require yiisoft/di
Usage of the DI container is simple: You first initialize it with an array of definitions. The array keys are usually interface names. It will then use these definitions to create an object whenever the application requests that type. This happens, for example, when fetching a type directly from the container somewhere in the application. But objects are also created implicitly if a definition has a dependency on another definition.
Usually one uses a single container for the whole application. It's often
configured either in the entry script such as index.php
or a configuration
file:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withDefinitions($definitions);
$container = new Container($config);
You could store the definitions in a .php
file that returns an array:
return [
EngineInterface::class => EngineMarkOne::class,
'full_definition' => [
'class' => EngineMarkOne::class,
'__construct()' => [42],
'$propertyName' => 'value',
'setX()' => [42],
],
'closure' => fn (SomeFactory $factory) => $factory->create('args'),
'static_call_preferred' => fn () => MyFactory::create('args'),
'static_call_supported' => [MyFactory::class, 'create'],
'object' => new MyClass(),
];
You can define an object in several ways:
class
has the name of the class to instantiate.__construct()
holds an array of constructor arguments.$
) and method calls, postfixed with ()
. They're
set/called in the order they appear in the array.ContainerInterface
could be used to get current container instance.See yiisoft/definitions for more information.
After you configure the container, you can obtain a service via get()
:
/** @var \Yiisoft\Di\Container $container */
$object = $container->get('interface_name');
Note, however, that it's bad practice using a container directly. It's much better to rely on auto-wiring as provided by the Injector available from the yiisoft/injector package.
The DI container supports aliases via the Yiisoft\Definitions\Reference
class.
This way you can retrieve objects by a more handy name:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withDefinitions([
EngineInterface::class => EngineMarkOne::class,
'engine_one' => EngineInterface::class,
]);
$container = new Container($config);
$object = $container->get('engine_one');
A composite container combines many containers in a single container. When using this approach, you should fetch objects only from the composite container.
use Yiisoft\Di\CompositeContainer;
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$composite = new CompositeContainer();
$carConfig = ContainerConfig::create()
->withDefinitions([
EngineInterface::class => EngineMarkOne::class,
CarInterface::class => Car::class
]);
$carContainer = new Container($carConfig);
$bikeConfig = ContainerConfig::create()
->withDefinitions([
BikeInterface::class => Bike::class
]);
$bikeContainer = new Container($bikeConfig);
$composite->attach($carContainer);
$composite->attach($bikeContainer);
// Returns an instance of a `Car` class.
$car = $composite->get(CarInterface::class);
// Returns an instance of a `Bike` class.
$bike = $composite->get(BikeInterface::class);
Note that containers attached earlier override dependencies of containers attached later.
use Yiisoft\Di\CompositeContainer;
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$carConfig = ContainerConfig::create()
->withDefinitions([
EngineInterface::class => EngineMarkOne::class,
CarInterface::class => Car::class
]);
$carContainer = new Container($carConfig);
$composite = new CompositeContainer();
$composite->attach($carContainer);
// Returns an instance of a `Car` class.
$car = $composite->get(CarInterface::class);
// Returns an instance of a `EngineMarkOne` class.
$engine = $car->getEngine();
$engineConfig = ContainerConfig::create()
->withDefinitions([
EngineInterface::class => EngineMarkTwo::class,
]);
$engineContainer = new Container($engineConfig);
$composite = new CompositeContainer();
$composite->attach($engineContainer);
$composite->attach($carContainer);
// Returns an instance of a `Car` class.
$car = $composite->get(CarInterface::class);
// Returns an instance of a `EngineMarkTwo` class.
$engine = $composite->get(EngineInterface::class);
A service provider is a special class that's responsible for providing complex services or groups of dependencies for the container and extensions of existing services.
A provider should extend from Yiisoft\Di\ServiceProviderInterface
and must
contain a getDefinitions()
and getExtensions()
methods. It should only provide services for the container
and therefore should only contain code related to this task. It should never
implement any business logic or other functionality such as environment bootstrap or applying changes to a database.
A typical service provider could look like:
use Yiisoft\Di\Container;
use Yiisoft\Di\ServiceProviderInterface;
class CarFactoryProvider extends ServiceProviderInterface
{
public function getDefinitions(): array
{
return [
CarFactory::class => [
'class' => CarFactory::class,
'$color' => 'red',
],
EngineInterface::class => SolarEngine::class,
WheelInterface::class => [
'class' => Wheel::class,
'$color' => 'black',
],
CarInterface::class => [
'class' => BMW::class,
'$model' => 'X5',
],
];
}
public function getExtensions(): array
{
return [
// Note that Garage should already be defined in a container
Garage::class => function(ContainerInterface $container, Garage $garage) {
$car = $container
->get(CarFactory::class)
->create();
$garage->setCar($car);
return $garage;
}
];
}
}
Here you created a service provider responsible for bootstrapping of a car factory with all its dependencies.
An extension is callable that returns a modified service object.
In this case you get existing Garage
service
and put a car into the garage by calling the method setCar()
.
Thus, before applying this provider, you had
an empty garage and with the help of the extension you fill it.
To add this service provider to a container, you can pass either its class or a configuration array in the extra config:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withProviders([CarFactoryProvider::class]);
$container = new Container($config);
When you add a service provider, DI calls its getDefinitions()
and getExtensions()
methods
immediately and both services and their extensions get registered into the container.
You can tag services in the following way:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withDefinitions([
BlueCarService::class => [
'class' => BlueCarService::class,
'tags' => ['car'],
],
RedCarService::class => [
'definition' => fn () => new RedCarService(),
'tags' => ['car'],
],
]);
$container = new Container($config);
Now you can get tagged services from the container in the following way:
$container->get(\Yiisoft\Di\Reference\TagReference::to('car'));
The result is an array that has two instances: BlueCarService
and RedCarService
.
Another way to tag services is setting tags via container constructor:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withDefinitions([
BlueCarService::class => [
'class' => BlueCarService::class,
],
RedCarService::class => fn () => new RedCarService(),
])
->withTags([
// "car" tag has references to both blue and red cars
'car' => [BlueCarService::class, RedCarService::class]
]);
$container = new Container($config);
Despite stateful services isn't a great practice, these are often inevitable. When you build long-running
applications with tools like Swoole or RoadRunner you should
reset the state of such services every request. For this purpose you can use StateResetter
with resetters callbacks:
$resetter = new StateResetter($container);
$resetter->setResetters([
MyServiceInterface::class => function () {
$this->reset(); // a method of MyServiceInterface
},
]);
The callback has access to the private and protected properties of the service instance, so you can set the initial state of the service efficiently without creating a new instance.
You should trigger the reset itself after each request-response cycle. For RoadRunner, it would look like the following:
while ($request = $psr7->acceptRequest()) {
$response = $application->handle($request);
$psr7->respond($response);
$application->afterEmit($response);
$container
->get(\Yiisoft\Di\StateResetter::class)
->reset();
gc_collect_cycles();
}
You define the reset state for each service by providing "reset" callback in the following way:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withDefinitions([
EngineInterface::class => EngineMarkOne::class,
EngineMarkOne::class => [
'class' => EngineMarkOne::class,
'setNumber()' => [42],
'reset' => function () {
$this->number = 42;
},
],
]);
$container = new Container($config);
Note: resetters from definitions work only if you don't set StateResetter
in definition or service providers.
StateResetter
manuallyTo manually add resetters or in case you use Yii DI composite container with a third party container that doesn't support state reset natively, you could configure state resetter separately. The following example is PHP-DI:
MyServiceInterface::class => function () {
// ...
},
StateResetter::class => function (ContainerInterface $container) {
$resetter = new StateResetter($container);
$resetter->setResetters([
MyServiceInterface::class => function () {
$this->reset(); // a method of MyServiceInterface
},
]);
return $resetter;
}
To specify some metadata, such as in cases of "resetting services state" or "container tags," for non-array definitions, you could use the following syntax:
LogTarget::class => [
'definition' => static function (LoggerInterface $logger) use ($params) {
$target = ...
return $target;
},
'reset' => function () use ($params) {
...
},
],
Now you've explicitly moved the definition itself to "definition" key.
Each delegate is a callable returning a container instance that's used in case DI can't find a service in a primary container:
function (ContainerInterface $container): ContainerInterface
{
}
To configure delegates use extra config:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withDelegates([
function (ContainerInterface $container): ContainerInterface {
// ...
}
]);
$container = new Container($config);
By default, the container validates definitions right when they're set. In the production environment, it makes sense to turn it off:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withValidate(false);
$container = new Container($config);
Container may work in a strict mode, that's when you should define everything in the container explicitly. To turn it on, use the following code:
use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;
$config = ContainerConfig::create()
->withStrictMode(true);
$container = new Container($config);
If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.
The Yii Dependency Injection is free software. It is released under the terms of the BSD License.
Please see LICENSE
for more information.
Maintained by Yii Software.