Using the container

This documentation describes the API of the container object itself.

get() & has()

The container implements the PSR-11 standard. That means it implements Psr\Container\ContainerInterface:

namespace Psr\Container;

interface ContainerInterface
{
    public function get($id);
    public function has($id);
}

You are encouraged to type-hint against this interface instead of the implementation (DI\Container) whenever possible. Doing so means your code is decoupled from PHP-DI and you can switch to another container anytime.

set()

You can set entries directly on the container:

$container->set('foo', 'bar');
$container->set('MyInterface', \DI\create('MyClass'));

However it is recommended to use definition files. See the definition documentation.

make()

The container also offers a make() method. This method is defined in DI\FactoryInterface.

class GithubProfile
{
    public function __construct(ApiClient $client, $user)
    ...
}

$container->make('GithubProfile', [
    'user' => 'torvalds',
]);

The make() method works like get() except it will resolve the entry every time it is called. Depending on the type of the entry this means:

Please note that only the entry you ask for will be resolved every time: all the dependencies of the entry will not! That means that if the entry is an alias, the entry the alias points to will be resolved only once.

If you provide parameters to Container::make() in the second argument, and if the entry to resolve is an object to create, the parameters provided will be used for the constructor of the object, and the missing parameters will be resolved from the container.

Container::make() is useful for creating objects that should not be stored inside the container (i.e. that are not services, or that are not stateless), but that have dependencies. It is also useful if you want to override some parameters of an object's constructor.

If you need to use the make() method inside a service, or a controller, or whatever, it is recommended that you type-hint against FactoryInterface. That avoids coupling your code to the container. DI\FactoryInterface is automatically bound to DI\Container so you can inject it without any configuration.

call()

The container exposes a call() method that can invoke any PHP callable.

It offers the following additional features over using call_user_func():

The best part is that you can mix all that:

$container->call(function (Logger $logger, $dbHost, $operation) {
    // ...
}, [
    'operation' => 'delete',
    'dbHost'    => \DI\get('db.host'),
]);

The call() method is particularly useful to invoke controllers, for example:

$controller = function ($name, EntityManager $em) {
    // ...
}

$container->call($controller, $_GET); // $_GET contains ['name' => 'John']

This leaves the liberty to the developer writing controllers to get request parameters and services using dependency injection.

As with make(), call() is defined in Invoker\InvokerInterface (in the PHP-DI/Invoker package) so that you can type-hint against that interface without coupling yourself to the container. Invoker\InvokerInterface is automatically bound to DI\Container so you can inject it without any configuration.

namespace Invoker;

interface InvokerInterface
{
    public function call($callable, array $parameters = []);
}

Container::call() can call any callable, that means:

Additionally you can call:

In both case, 'My\CallableClass' and 'MyClass' will be resolved by the container using $container->get().

That saves you from a more verbose form, for example:

$object = $container->get('My\CallableClass');
$container->call($object);

// can be written as
$container->call('My\CallableClass');

injectOn()

Sometimes you want to inject dependencies on an object that is already created.

For example, some old frameworks don't allow you to control how controllers are created. With injectOn, you can ask the container to fulfill the dependencies after the object is created.

Keep in mind it's usually always better to use get() or make() instead of injectOn(), use it only where you really have to.

Example:

class UserController extends BaseController
{
    /**
     * @Inject
     * @var SomeService
     */
    private $someService;

    public function __construct()
    {
        // The framework doesn't let us control how the controller is created, so
        // we can't use the container to create the controller
        // So we ask the container to inject dependencies
        $container->injectOn($this);

        // Now the dependencies are injected
        $this->someService->doSomething();
    }
}

As you might have guessed, you can't use constructor injection with this method. But other kind of injections (property or setter) will work, whether you use annotations or whether you configured your object in a definition file.

Extending the container

If you wish to delve into the container's internals, be aware that only the classes and interfaces tagged with the @api annotation are meant to be used by PHP-DI users.

All other classes and interfaces are internal classes, you may try to use them but backward compatibility is not guaranteed, even between minor versions.