Dependency Injection / Service Location

DI explained

The following example is a bit long, but it attempts to explain why Phalcon uses service location and dependency injection. First, let’s assume we are developing a component called SomeComponent. This performs some task. Our component has a dependency, that is a connection to a database.

In this first example, the connection is created inside the component. Although this is a perfectly valid implementation, it is impartical, due to the fact that we cannot change the connection parameters or the type of the database system because the component only works as created.

<?phpclassSomeComponent{/**
* The instantiation of the connection is hardcoded inside
* the component, therefore it's difficult replace it externally
* or change its behavior
*/publicfunctionsomeDbTask(){$connection=newConnection(['host'=>'localhost','username'=>'root','password'=>'secret','dbname'=>'invo',]);// ...}}$some=newSomeComponent();$some->someDbTask();

To solve this shortcoming, we have created a setter that injects the dependency externally before using it. This is also a valid implementation but has its shortcomings:

Now consider that we use this component in different parts of the application and then we will need to create the connection several times before passing it to the component. Using a global registry pattern, we can store the connection object there and reuse it whenever we need it.

So far we have seen how dependency injection solved our problems. Passing dependencies as arguments instead of creating them internally in the code makes our application more maintainable and decoupled. However, in the long-term, this form of dependency injection has some disadvantages.

For instance, if the component has many dependencies, we will need to create multiple setter arguments to pass the dependencies or create a constructor that pass them with many arguments, additionally creating dependencies before using the component, every time, makes our code not as maintainable as we would like:

<?php// Create the dependencies or retrieve them from the registry$connection=newConnection();$session=newSession();$fileSystem=newFileSystem();$filter=newFilter();$selector=newSelector();// Pass them as constructor parameters$some=newSomeComponent($connection,$session,$fileSystem,$filter,$selector);// ... Or using setters$some->setConnection($connection);$some->setSession($session);$some->setFileSystem($fileSystem);$some->setFilter($filter);$some->setSelector($selector);

Think if we had to create this object in many parts of our application. In the future, if we do not require any of the dependencies, we need to go through the entire code base to remove the parameter in any constructor or setter where we injected the code. To solve this, we return again to a global registry to create the component. However, it adds a new layer of abstraction before creating the object:

Now we find ourselves back where we started, we are again building the dependencies inside of the component! We must find a solution that keeps us from repeatedly falling into bad practices.

A practical and elegant way to solve these problems is using a container for dependencies. The containers act as the global registry that we saw earlier. Using the container for dependencies as a bridge to obtain the dependencies allows us to reduce the complexity of our component:

<?phpusePhalcon\Di;usePhalcon\DiInterface;classSomeComponent{protected$di;publicfunction__construct(DiInterface$di){$this->di=$di;}publicfunctionsomeDbTask(){// Get the connection service// Always returns a new connection$connection=$this->di->get('db');}publicfunctionsomeOtherDbTask(){// Get a shared connection service,// this will return the same connection every time$connection=$this->di->getShared('db');// This method also requires an input filtering service$filter=$this->di->get('filter');}}$di=newDi();// Register a 'db' service in the container$di->set('db',function(){returnnewConnection(['host'=>'localhost','username'=>'root','password'=>'secret','dbname'=>'invo',]);});// Register a 'filter' service in the container$di->set('filter',function(){returnnewFilter();});// Register a 'session' service in the container$di->set('session',function(){returnnewSession();});// Pass the service container as unique parameter$some=newSomeComponent($di);$some->someDbTask();

The component can now simply access the service it requires when it needs it, if it does not require a service it is not even initialized, saving resources. The component is now highly decoupled. For example, we can replace the manner in which connections are created, their behavior or any other aspect of them and that would not affect the component.

Phalcon\Di is a component implementing Dependency Injection and Location of services and it’s itself a container for them.

Since Phalcon is highly decoupled, Phalcon\Di is essential to integrate the different components of the framework. The developer can also use this component to inject dependencies and manage global instances of the different classes used in the application.

Basically, this component implements the Inversion of Control pattern. Applying this, the objects do not receive their dependencies using setters or constructors, but requesting a service dependency injector. This reduces the overall complexity since there is only one way to get the required dependencies within a component.

Additionally, this pattern increases testability in the code, thus making it less prone to errors.

Registering services in the Container

The framework itself or the developer can register services. When a component A requires component B (or an instance of its class) to operate, it can request component B from the container, rather than creating a new instance component B.

This way of working gives us many advantages:

We can easily replace a component with one created by ourselves or a third party.

We have full control of the object initialization, allowing us to set these objects, as needed before delivering them to components.

We can get global instances of components in a structured and unified way.

Services can be registered using several types of definitions:

Simple Registration

As seen before, there are several ways to register services. These we call simple:

String

This type expects the name of a valid class, returning an object of the specified class, if the class is not loaded it will be instantiated using an auto-loader. This type of definition does not allow to specify arguments for the class constructor or parameters:

Class instances

This type expects an object. Due to the fact that object does not need to be resolved as it is already an object, one could say that it is not really a dependency injection, however it is useful if you want to force the returned dependency to always be the same object/value:

Closures/Anonymous functions

This method offers greater freedom to build the dependency as desired, however, it is difficult to change some of the parameters externally without having to completely change the definition of dependency:

Some of the limitations can be overcome by passing additional variables to the closure’s environment:

<?phpusePhalcon\Config;usePhalcon\Db\Adapter\Pdo\MysqlasPdoMysql;$config=newConfig(['host'=>'127.0.0.1','username'=>'user','password'=>'pass','dbname'=>'my_database',]);// Using the $config variable in the current scope$di->set('db',function()use($config){returnnewPdoMysql(['host'=>$config->host,'username'=>$config->username,'password'=>$config->password,'dbname'=>$config->name,]);});

You can also access other DI services using the get() method:

<?phpusePhalcon\Config;usePhalcon\Db\Adapter\Pdo\MysqlasPdoMysql;$di->set('config',function(){returnnewConfig(['host'=>'127.0.0.1','username'=>'user','password'=>'pass','dbname'=>'my_database',]);});// Using the 'config' service from the DI$di->set('db',function(){$config=$this->get('config');returnnewPdoMysql(['host'=>$config->host,'username'=>$config->username,'password'=>$config->password,'dbname'=>$config->name,]);});

Complex Registration

If it is required to change the definition of a service without instantiating/resolving the service, then, we need to define the services using the array syntax. Define a service using an array definition can be a little more verbose:

<?phpusePhalcon\Logger\Adapter\FileasLoggerFile;// Register a service 'logger' with a class name and its parameters$di->set('logger',['className'=>'Phalcon\Logger\Adapter\File','arguments'=>[['type'=>'parameter','value'=>'../apps/logs/error.log',]]]);// Using an anonymous function$di->set('logger',function(){returnnewLoggerFile('../apps/logs/error.log');});

Both service registrations above produce the same result. The array definition however, allows for alteration of the service parameters if needed:

<?php// Change the service class name$di->getService('logger')->setClassName('MyCustomLogger');// Change the first parameter without instantiating the logger$di->getService('logger')->setParameter(0,['type'=>'parameter','value'=>'../apps/logs/error.log',]);

In addition by using the array syntax you can use three types of dependency injection:

Constructor Injection

This injection type passes the dependencies/arguments to the class constructor. Let’s pretend we have the following component:

Resolving a service whose definition is complex may be slightly slower than simple definitions seen previously. However, these provide a more robust approach to define and inject services.

Mixing different types of definitions is allowed, everyone can decide what is the most appropriate way to register the services according to the application needs.

Array Syntax

The array syntax is also allowed to register services:

<?phpusePhalcon\Di;usePhalcon\Http\Request;// Create the Dependency Injector Container$di=newDi();// By its class name$di['request']='Phalcon\Http\Request';// Using an anonymous function, the instance will be lazy loaded$di['request']=function(){returnnewRequest();};// Registering an instance directly$di['request']=newRequest();// Using an array definition$di['request']=['className'=>'Phalcon\Http\Request',];

In the examples above, when the framework needs to access the request data, it will ask for the service identified as ‘request’ in the container. The container in turn will return an instance of the required service. A developer might eventually replace a component when he/she needs.

Each of the methods (demonstrated in the examples above) used to set/register a service has advantages and disadvantages. It is up to the developer and the particular requirements that will designate which one is used.

Setting a service by a string is simple, but lacks flexibility. Setting services using an array offers a lot more flexibility, but makes the code more complicated. The lambda function is a good balance between the two, but could lead to more maintenance than one would expect.

Phalcon\Di offers lazy loading for every service it stores. Unless the developer chooses to instantiate an object directly and store it in the container, any object stored in it (via array, string, etc.) will be lazy loaded i.e. instantiated only when requested.

Loading services from YAML files

This feature will let you set your services in yaml files or just in plain php. For example you can load services using a yaml file like this:

config:className:\Phalcon\Configshared:true

<?phpusePhalcon\Di;$di=newDi();$di->loadFromYaml('services.yml');$di->get('config');// will properly return config service

This approach requires that the module Yaml be installed. Please refer to this for more information.

Resolving Services

Obtaining a service from the container is a matter of simply calling the ‘get’ method. A new instance of the service will be returned:

$request=$di->get('request');

Or by calling through the magic method:

$request=$di->getRequest();

Or using the array-access syntax:

$request=$di['request'];

Arguments can be passed to the constructor by adding an array parameter to the method ‘get’:

Events

Phalcon\Di is able to send events to an EventsManager if it is present. Events are triggered using the type ‘di’. Some events when returning boolean false could stop the active operation. The following events are supported:

Event Name

Triggered

Can stop operation?

Triggered on

beforeServiceResolve

Triggered before resolve service. Listeners receive the service name and the parameters passed to it.

No

Listeners

afterServiceResolve

Triggered after resolve service. Listeners receive the service name, instance, and the parameters passed to it.

No

Listeners

Shared services

Services can be registered as ‘shared’ services this means that they always will act as singletons. Once the service is resolved for the first time the same instance of it is returned every time a consumer retrieve the service from the container:

<?phpusePhalcon\Session\Adapter\FilesasSessionFiles;// Register the session service as 'always shared'$di->setShared('session',function(){$session=newSessionFiles();$session->start();return$session;});// Locates the service for the first time$session=$di->get('session');// Returns the first instantiated object$session=$di->getSession();

An alternative way to register shared services is to pass ‘true’ as third parameter of ‘set’:

<?php// Register the session service as 'always shared'$di->set('session',function(){// ...},true);

If a service isn’t registered as shared and you want to be sure that a shared instance will be accessed every time the service is obtained from the DI, you can use the ‘getShared’ method:

$request=$di->getShared('request');

Manipulating services individually

Once a service is registered in the service container, you can retrieve it to manipulate it individually:

<?phpusePhalcon\Http\Request;// Register the 'request' service$di->set('request','Phalcon\Http\Request');// Get the service$requestService=$di->getService('request');// Change its definition$requestService->setDefinition(function(){returnnewRequest();});// Change it to shared$requestService->setShared(true);// Resolve the service (return a Phalcon\Http\Request instance)$request=$requestService->resolve();

Instantiating classes via the Service Container

When you request a service to the service container, if it can’t find out a service with the same name it’ll try to load a class with the same name. With this behavior we can replace any class by another simply by registering a service with its name:

<?php// Register a controller as a service$di->set('IndexController',function(){$component=newComponent();return$component;},true);// Register a controller as a service$di->set('MyOtherComponent',function(){// Actually returns another component$component=newAnotherComponent();return$component;});// Create an instance via the service container$myComponent=$di->get('MyOtherComponent');

You can take advantage of this, always instantiating your classes via the service container (even if they aren’t registered as services). The DI will fallback to a valid autoloader to finally load the class. By doing this, you can easily replace any class in the future by implementing a definition for it.

Automatic Injecting of the DI itself

If a class or component requires the DI itself to locate services, the DI can automatically inject itself to the instances it creates, to do this, you need to implement the Phalcon\Di\InjectionAwareInterface in your classes:

Factory Default DI

Although the decoupled character of Phalcon offers us great freedom and flexibility, maybe we just simply want to use it as a full-stack framework. To achieve this, the framework provides a variant of Phalcon\Di called Phalcon\Di\FactoryDefault. This class automatically registers the appropriate services bundled with the framework to act as full-stack.

<?phpusePhalcon\Di\FactoryDefault;$di=newFactoryDefault();

Service Name Conventions

Although you can register services with the names you want, Phalcon has a several naming conventions that allow it to get the the correct (built-in) service when you need it.