IoC Container

In previous article, we've see that the magician $app produced the $kernel out of gloved hands with a spell Illuminate\Contracts\Http\Kernel::class. Let's reveal the secrets of the magic.

The $app is a instance of Illuminate\Foundation\Application, which extends Illuminate\Container\Container. The magic is inherited from here, the container, or recognized as IoC container.

How it works? It's absolutely not to simply call new on the given class. In fact, you'll find it's a interface rather then a class:

namespace Illuminate\Contracts\Http; interface Kernel

We've also find some code seems like binding a instantiable class with the interface:

$app->singleton( Illuminate\Contracts\Http\Kernel::class, App\Http\Kernel::class );

So is the $app just call new on this class? You can try it, an ArgumentCountError will be thrown. The constructor of class App\Http\Kernel requires 2 parameters.

/** * Create a new HTTP kernel instance. * * @param \Illuminate\Contracts\Foundation\Application $app * @param \Illuminate\Routing\Router $router * @return void */ public function __construct(Application $app, Router $router)

For instantiating, the container need to know this. Therefore, there must be metaprogramming inside, must be reflecting inside. Let's trace the code:

// the copy of code is modified to focus on the topical public function singleton($abstract, $concrete) { $this->bind($abstract, $concrete); } public function bind($abstract, $concrete) { if (! $concrete instanceof Closure) { $concrete = $this->getClosure($abstract, $concrete); } $this->bindings[$abstract] = ['concrete' => $concrete]; } protected function getClosure($abstract, $concrete) { return function ($container) use ($abstract, $concrete) { if ($abstract == $concrete) { return $container->build($concrete); } return $container->resolve($concrete); }; }

We call singleton() on bind() with an $abstract and a concrete class. The $abstract is just act as a string, you can replace Illuminate\Contracts\Http\Kernel::class both in public/index.php and bootstrap/app.php to 'This is the HTTP Kernel!'. It'll work fine as before. For magical, let's just call it the 'Spell'. There is benefit to use the class or interface name as the Spell, We'll see later.

The container keeps a map from each Spell to a anonymous function for instantiation: $this->bindings. When you call make() or get() on the container, these instantiation functions will be call.

// the copy of code is modified to focus on the topical public function make($abstract, array $parameters = []) { return $this->resolve($abstract, $parameters); } protected function resolve($abstract) { $concrete = $this->getConcrete($abstract); $object = $this->build($concrete); return $object; } public function build($concrete) { if ($concrete instanceof Closure) { return $concrete($this); }

There are some recurrent calls, but in the very end, it will call the build() with the $concrete you first given. It end up as the code like this:

$app->build(App\Http\Kernel::class)

You can modify the public/index.php in this way. It'll work well as well. Why don't Laravel just take this simple way? Because we may access the kernel in other places, a singleton is necessary. What's more, functions added by extend() will not work if we use build() directly instead of make(). We will talk about extend() later.

Let's back to the build() called with a class name.

// the copy of code is modified to focus on the topical public function build($concrete) { $reflector = new ReflectionClass($concrete); $constructor = $reflector->getConstructor(); $dependencies = $constructor->getParameters(); $instances = $this->resolveDependencies($dependencies); return $reflector->newInstanceArgs($instances); } protected function resolveDependency(ReflectionParameter $dependency) { if (is_null($dependency->getClass())) { $concrete = $this->getContextualConcrete('$'.$parameter->name); return $concrete instanceof Closure ? $concrete($this) : $concrete; } $this->make($dependency->getClass()->name); }

The metaprogramming magic is here. They reflect the class and get the dependencies from constructor. Then make the dependencies, and call the constructor with these dependencies to instantiate. If we add a class or interface as type hint of a parameter. The container will use it as the Spell. Now you see, that's the benefit of using class or interface name as Spell we've talk about. We only need to write the Spell as type hint in __construct(), and the container will call the Spell automatically. That's why Laravel using Illuminate\Contracts\Http\Kernel::class rather then something like 'This is the HTTP Kernel!'. If the type hint is not suitable as a Spell, such as the dependency is a string or a resource, or the same Spell for different concretes in different place. We can use a feature named contextual concrete:

class Foo { public function __construct($phpInput) {} } $container->addContextualBinding(Foo::class, '$phpInput', fopen( 'php://input', 'r' )); $container->make(Foo::class);

Or you can use more readable syntax like the case in documentation:

$container->when(Foo::class)->need('$phpInput')->give(fopen( 'php://input', 'r' ));

For readable and efficiency, we can set aliases to Spells. If you can use 'Ex' instead of 'Expelliarmus', Noseless Voldemort will not have enough time to call the 'Avada Kedavra'. It's a joke, but app for Illuminate\Contracts\Foundation\Application, http-kernel for Illuminate\Contracts\Http\Kernel etc. will be helpful.

$app->alias(Illuminate\Contracts\Http\Kernel::class, 'http-kernel'); $kernel = $app->make('http-kernel');

We also need take care of these code:

// the copy of code is modified to focus on the topical protected function resolve($abstract) { $object = $this->build($concrete); foreach ($this->getExtenders($abstract) as $extender) { $object = $extender($object, $this); } return $object; }

The object returned by resolve() may not be the one from build(). Follow the getExtenders(), we find:

// the copy of code is modified to focus on the topical protected function getExtenders($abstract) { return $this->extenders[$abstract] ?? []; } public function extend($abstract, Closure $closure) { $this->extenders[$abstract][] = $closure; }

That's means we can use extend() to add modifiers to end up modify or change the object. If you bind with abstract and concrete class, like our kernel example, the resolve will recurrently called with both the abstract and concrete. Therefore, you can both call extend with abstract and concrete.

$app->singleton( Illuminate\Contracts\Http\Kernel::class, App\Http\Kernel::class ); $app->extend(App\Http\Kernel::class, function ($kernel) { $kernel->foo = 'foo'; return $kernel; }); $app->extend(Illuminate\Contracts\Http\Kernel::class, function ($kernel) { $kernel->bar = 'bar'; return $kernel; }); $kernel = $app->make(Illuminate\Contracts\Http\Kernel::class); $kernel->foo; // 'foo' $kernel->bar; // 'bar'

For extendable, understandable and maintainable reason, it's better only to modify the object but not to change it in the extender.

// Good $app->extend(Foo::class, function ($foo) { $foo->doSomeExtends(); return $foo; }); // Bad $app->extend(Foo::class, function ($foo) { $bar = new SomethingElse(); return $bar; });

Now, let's talk about the IoC. IoC is short for Inversion of Control. It's made up with Dependence Inversion Principle (DIP) and Dependency Injection (DI). The DIP says: a module should not depend on another module, but both them should depend on abstraction. For example:

interface Connection {} class FooConnection implement Connection { public function __construct() {} } class App { public function __construct(Connection $connection) {} } $connection = new FooConnection(); $app = new App($connection);

As we see, class App is not depend on class FooConnection, but both two classes depend on the interface Connection. So when we change FooConnection to BarConnection, class App need not be modified. And when we test the class App, we can pass a MockConnection to prevent a real connection.

So far, we also need face to a problem: every time we instantiate App, we need instantiate a implement of Connection first. Different implement of Connection may requires different dependencies, dependency may has it's own dependencies... Now, DI is what we need, it is a feature that detecting the dependencies then instantiating them and injecting into the constructor. This just happen to be what container acts.

So we have a overview of IoC, decoupling dependent between modules, and instantiating automatically with container. Your module code and module using code become more declarative, and standalone, not caring about details about other modules but only interfaces.

I just have a question about the naming 'Inversion'. That's not invert anything, that's just the original way to design things. Do you agree?

After touching the textbook knowledge, let's back to see our example:

// the copy of code is modified to focus on the topical namespace Illuminate\Foundation\Http; class Kernel implements KernelContract { public function __construct(\Illuminate\Contracts\Foundation\Application $app, \Illuminate\Routing\Router $router)

The \Illuminate\Contracts\Foundation\Application is a interface but \Illuminate\Routing\Router is not. So this is not fully follow the DIP. So the defect is we cannot change the router freely. But we still can extends it. We can write a MyRouter extends \Illuminate\Routing\Router, then register it in the App\Providers\RouteServiceProvider:

public function boot() { $this->app->singleton(\Illuminate\Routing\Router::class, MyRouter::class);

Now, you can make creative works in MyRouter. If you register MyRouter in bootstrap/app.php, you will find your routes will not work, and all request will responded with 404. That's some reason about the service providers. We will talk about this on next article.

DI is so powerful, we can expect it's not only for constructing. By searching public function in the container class, we can find to methods that official documentation not talk about: call() and wrap().

/** * Call the given Closure / class@method and inject its dependencies. * * @param callable|string $callback * @param array $parameters * @return mixed */ public function call($callback, array $parameters = [] ) /** * Wrap the given closure such that its dependencies will be injected when executed. * * @param \Closure $callback * @param array $parameters * @return \Closure */ public function wrap(Closure $callback, array $parameters = []) { return function () use ($callback, $parameters) { return $this->call($callback, $parameters); }; }

Here is some examples for call():

$container->call(function (Illuminate\Contracts\Http\Kernel $kernel) { dump( $kernel ); });

function function_name(Illuminate\Contracts\Http\Kernel $kernel) { dump( $kernel ); } $app->call( 'function_name' );

class ClassName { public static function methodName(Illuminate\Contracts\Http\Kernel $kernel) { dump( $kernel ); } } $app->call( [ClassName::class, 'methodName'] ); $app->call( 'ClassName::methodName' ); $app->call( 'ClassName@methodName' ); // not standard, not recommended

class ClassName { public function methodName(Illuminate\Contracts\Http\Kernel $kernel) { dump( $kernel ); } } $app->call( [new ClassName(), 'methodName'] ); $app->call( 'ClassName@methodName' ); // for non-static method, container will instantiate the class automatically.

The method wrap() however, returns a anonymous function for calling later or higher order functions. unfortunately, the wrap() is not as powerful as call() because of a improper type hint.

Summing up

In this article, we dig into Container, find out how it works. Then learn what is IoC, DIP and DI, know why the container designed like this. And show a example about how to extend a framework module with the container.