Inspired by Spring Framework 3.0 new equivalent annotation, it allows to inject parameter values defined in your service container with a simple annotation in your services. Check the updated code on my Bitbucket.

If you use @Value without description, the parameter identifier will be automatically determined. You can also explicitly define the parameter identifier: @Value %mail.transport%.

parameters:
    foo: bar
    mailer.username: foo
    mailer.password: bar

/** 
 * @Service 
 */ 
class Default_Service_TestService 
{ 
    /** 
     * @Value
     */ 
    protected $_foo; 
  
    public function setFoo($foo) 
    { 
        $this->_foo = $foo; 
        return $this; 
    }

    protected $_username;

    /*
     * @Value %mailer.username%
     */
    public function setUsername($username)
    {
        $this->_username = $username;
        return $this;
    }

    // ....
}

For the second part of this series on Dependency Injection, we are going to see an elegant way to integrate the Symfony service container with your Zend Framework application.

During my researches, I found two blog posts that guided me for this integration:

• The first one is from Benjamin Eberlei and shows how to replace the Zend_Application default bootstrap container with the Symfony Service Container.
• The second one from Dolf Starreveld shows the same as Benjamin but with a more advanced integration by subclassing Zend_Application_Bootstrap_BootstrapAbstract class.

In the following post I will expose how to integrate the Symfony Dependency Injection container into Zend_Application bootstrap with a simple implementation of a ServiceContainerFactory. I will then expose how to inject your defined services into your controller with an action helper and with a simple @Inject annotation!

Replace the default boostrap container with Symfony’s Service Container

Since Zend Framework 1.8 bootstrapping applications is much more easier thanks to Zend_Application. It facilitates application bootstrapping and provides reusable resources to easily configure and initiate various components you will use such as Zend_Layout, Zend_Translate, Zend_Navigation or Zend_Db.

To be accessible throughout your application, the resources objects are registered in a container also called the resource registry. And as Matthew Weier O’Phinney (ZF’s project lead) said in Benjamin’s post comments, this explicit design was made to use a Dependency Injection container instead of the default Zend_Registry instance. So we are gonna replace this default registry with the full featured Symfony’s Dependency Injection container.

I wrote a class named LoSo_Zend_Application_Bootstrap_Bootstrap which extends the default Zend_Application_Bootstrap_Bootstrap class :

/**
 * Description of LoSo_Zend_Application_Bootstrap_Bootstrap
 *
 * @author Loïc Frering <loic.frering@gmail.com>
 */
class LoSo_Zend_Application_Bootstrap_Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    public function getContainer()
    {
        $options = $this->getOption('bootstrap');

        if(null === $this->_container && $options['container']['type'] == 'symfony') {
            $autoloader = Zend_Loader_Autoloader::getInstance();
            $autoloader->pushAutoloader(array('LoSo_Symfony_Components_Autoloader', 'autoload'));
            $container = LoSo_Symfony_Components_ServiceContainerFactory::getContainer($options['container']);
            $this->_container = $container;
            Zend_Controller_Action_HelperBroker::addHelper(new LoSo_Zend_Controller_Action_Helper_ServiceContainer());
        }
        return parent::getContainer();
    }
}

It overrides the getContainer method where I instantiate and return a Symfony Service Container if the option bootstrap.container.type value is set to symfony in your configs/application.ini file. Three main operations are done here:

• Registering the autoloader for loading Symfony Components classes
• Getting a Service Container instance from a factory
• Adding a helper for dependency injection to the action helper broker.

The LoSo_Symfony_Components_Autoloader is a simple class I developed to easily autoload the classes of the two Symfony Components necessary here: Dependency Injection and YAML (for defining services into YAML files). I will not describe it here, see the code for implementation details.

The Service Container Factory

LoSo_Symfony_Components_ServiceContainerFactory class purpose is to instantiate and configure the Symfony Service Container. Just pass an array of options to getContainer method to get an instance:

class LoSo_Symfony_Components_ServiceContainerFactory
{
    protected static $_container;

    public static function getContainer(array $options)
    {
        self::$_container = new sfServiceContainerBuilder();
        foreach($options['configFiles'] as $file) {
            self::_loadConfigFile($file);
        }

        return self::$_container;
    }

    protected static function _loadConfigFile($file)
    {
        $suffix = strtolower(pathinfo($file, PATHINFO_EXTENSION));

        switch ($suffix) {
            case 'xml':
                $loader = new sfServiceContainerLoaderFileXml(self::$_container);
                break;

            case 'yml':
                $loader = new sfServiceContainerLoaderFileYaml(self::$_container);
                break;

            case 'ini':
                $loader = new sfServiceContainerLoaderFileIni(self::$_container);
                break;

            default:
                throw new Atos_Symfony_Exception("Invalid configuration file provided; unknown config type '$suffix'");
        }
        $loader->load($file);
    }
}

As you can see in the extended Bootstrap class, the bootstrap.container.* options retrieved from application.ini are passed to the factory. You can specify definition files to load thanks to the configFiles array option:

bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
bootstrap.class = "Bootstrap"
bootstrap.container.type = "symfony"
bootstrap.container.configFiles[] = APPLICATION_PATH "/configs/services.yml"

Then the factory loads to the Service Container each configuration file by instantiating the correct loader according to the file extension.

Dependency Injection action helper

We have now integrated Symfony service container with Zend_Application and loaded configuration files easily defined in our application.ini. The last operation done in the extended getContainer method was to register a service container action helper. Let’s see now how to retrieve services from our controllers with this action helper.

The direct function allows to retrieve a service or a parameter by his identifier while the getContainer method simply returns the Symfony service container instance:

class LoSo_Zend_Controller_Action_Helper_ServiceContainer extends Zend_Controller_Action_Helper_Abstract
{
    /**
     * @var sfServiceContainer
     */
    protected $_container;

    public function __construct()
    {
        $this->_container = $this->getActionController()->getInvokeArg('bootstrap')->getContainer();
    }

    public function direct($name)
    {
        if($this->_container->hasService($name)) {
            return $this->_container->getService($name);
        }
        else if($this->_container->hasParameter($name)) {
            return $this->_container->getParameter($name);
        }
        return null;
    }

    public function  getContainer() {
        return $this->_container;
    }
}

Here are some examples on how you can use this helper in your controllers:

class MyController extends Zend_Controller_Action
{
    protected $_testService;

    public function init()
    {
        $this->_testService = $this->_helper->serviceContainer('testService');
    }

    public function indexAction()
    {
        $serviceContainer = $this->_helper->serviceContainer->getContainer();
        $myService = $serviceContainer->getService('myService');
        $myService = $serviceContainer->myService;
        $param = $serviceContainer->getParameter('param');
        // ....
    }
}

Depency Injection with annotations within our controllers

To ease and automate dependency injection in our controllers, we are going to use annotations to declare the services we want to be automatically injected. To achieve this task, we can think about declaring our controller classes in the service container by loading them with the ServiceContainerAnnotationsLoader I described in my previous post.

But we are not directly in charge of the controller instantiation, that’s the dispatcher‘s main mission. In a first approach I did not wanted to extend the standard dispatcher to let him manage the controllers lifecycle. Instead I decided to use introspection on the controller instance to inject the annotated dependencies. The best way to achieve this is in the preDispatch hook of an action helper because at this stade: the controller has been instantiated by the standard dispatcher and you can retrieve it via the getActionController method of Zend_Controller_Action_Helper_Abstract class.

Helper class? Hey we’ve just developed one for our service container! So here’s the complete implementation I made of my LoSo_Controller_Action_Helper_ServiceContainer:

class LoSo_Zend_Controller_Action_Helper_ServiceContainer extends Zend_Controller_Action_Helper_Abstract
{
    /**
     * @var sfServiceContainer
     */
    protected $_container;

    public function __construct()
    {
        $this->_container = $this->getActionController()->getInvokeArg('bootstrap')->getContainer();
    }

    public function preDispatch()
    {
        $actionController = $this->getActionController();

        $r = new Zend_Reflection_Class($actionController);
        $properties = $r->getProperties();

        foreach($properties as $property) {
            if($property->getDeclaringClass()->getName() == get_class($actionController)) {
                if($property->getDocComment()->hasTag('Inject')) {
                    $injectTag = $property->getDocComment()->getTag('Inject');
                    $serviceName = $injectTag->getDescription();
                    if(empty($serviceName)) {
                        $serviceName = $this->_formatServiceName($property->getName());
                    }
                    if($this->_container->hasService($serviceName)) {
                        $property->setAccessible(true);
                        $property->setValue($actionController, $this->_container->getService($serviceName));
                    }
                }
            }
        }
        
    }

    protected function _formatServiceName($serviceName)
    {
        if(strpos($serviceName, '_') === 0) {
            $serviceName = substr($serviceName, 1);
        }
        return $serviceName;
    }

    public function direct($name)
    {
        if($this->_container->hasService($name)) {
            return $this->_container->getService($name);
        }
        else if($this->_container->hasParameter($name)) {
            return $this->_container->getParameter($name);
        }
        return null;
    }

    public function  getContainer() {
        return $this->_container;
    }
}

Here’s what the preDispatch method do:

• Introspect the action controller class
• For each property of the class, if the property is tagged @Inject:
• Determine which service identifier we want to inject:
• If a service name is explicitly defined in the @Inject description (eg @Inject myService), use this name as identifier
• If not, use property name (with no _ if it begins with) as identifier
• Check if the service is declared in the container
• Then inject the service instance into the property

Here we are, we can now easily inject services into our controllers:

class MyController extends Zend_Controller_Action
{
    /**
     * @Inject
     */
    private $_testService;

    public function indexAction()
    {
        // ....
    }
}

The whole code base and examples are available on my Bitbucket.

Coming soon

My next post will describe how to automatically load your services classes into the container with the annotation loader. You will then just have to tag @Service the classes you want to be managed by the service container with no overhead XML or YAML configuration file.

I will not cover here the benefits of using a Dependency Injection container in your applications, refer to all the resources you can find on the web. As well, I will not debate about the pertinence to use a DI container with dynamic languages such as PHP nor Ruby.

So let’s start with the annotation loader. I developed a class called LoSo_Symfony_Components_ServiceContainerLoaderAnnotations which extends sfServiceContainerLoader. I use Zend_Reflection for the introspection of docblocks and his ability to retrieve annotation tags. The class is available on my GitHub.

Let’s see an example of an annotation described service:

/**
 * Description of Default_Service_TestService
 *
 * @author Loïc Frering <loic.frering@gmail.com>
 * @Service
 */
class Default_Service_TestService
{
    /**
     * @var Default_Service_TestService2
     */
    protected $_testService2;

    /**
     * @param Default_Service_TestService2 $testService2
     * @return Default_Service_TestService
     * @Inject
     */
    public function setTestService2($testService2)
    {
        $this->_testService2 = $testService2;
        return $this;
    }

    public function test()
    {
        return 'Test method from TestService';
    }

    public function test2()
    {
        return $this->_testService2->test2() . ' called from testService';
    }
}

@Service annotation

The @Service annotation register the class as a service managed by the DI Container. If no string follows the @Service annotation, the class name will be used to determine the service identifier:

• Default_Service_TestService will be identified as testService
• MyService will be identified as myService

You can also explicitly specify the service identifier:

/**
 * @Service myService
 */

@Inject annotation

The @Inject annotation specify a dependence that need to be injected by the container. You can use the annotations in three different ways.

Constructor injection

@Inject annotated constructor arguments will be introspected and declared in the Service Container for injection. The argument name will be used to determine the service id to inject.

/**
 * @Service
 */
class Default_Service_TestService
{
    /**
     * @var Default_Service_MyService
     */
    protected $_myService;

    /**
     * @Inject
     */
    public function __construct($myService)
    {
        $this->_myService = $myService;
    }

    // ....
}

Property injection

When the loader encounters a properties with the @Inject annotation, a method call will be declared in the service container to make the injection. A _testService or testService property will register a method call to setTestService with the testService as service identifier for injection.

/**
 * @Service
 */
class Default_Service_TestService
{
    /**
     * @var Default_Service_MyService
     * @Inject
     */
    protected $_myService;

    public function setMyService($myService)
    {
        $this->_myService = $myService;
    }

    // ....
}

You can also explicitly specify the service identifier:

/**
 * @Inject myService
 */

Setter injection

A setter method with @Inject annotation will also register a method call for a service injection. The service identifier to inject, if not explicitly defined with the annotation, will be determined with the method name : testService service will be injected in the setTestService method.

/**
 * @Service
 */
class Default_Service_TestService
{
    /**
     * @var Default_Service_MyService
     */
    protected $_myService;

    /**
     * @Inject
     */
    public function setMyService($myService)
    {
        $this->_myService = $myService;
    }

    // ....
}

Using the loader

Using the loader is as simple as using XML or YAML loaders. Just pass to the loader constructor a path to a directory to be scanned by the loader:

$container = new sfServiceContainerBuilder();
$loader LoSo_Symfony_Components_ServiceContainerLoaderAnnotations($container);
$loader->load($path);

The Need for Speed

As you might have wondered, using annotations introspection on each request is not very efficient. Not a problem: have a look at Symfony Dependency Injection component documentation and paticularly at the chapter named The Need for Speed.

Did you read it ? So you just have to use the PHP dumper to generate the plain optimized PHP code for your Service Container with the definition corresponding to what you have declared with your annotations.

$dumper = new sfServiceContainerDumperPhp($container);
file_put_contents($file, $dumper->dump(array('class' => 'MyContainer'));

Then stock the generated file when it does not exist on the first request and use the generated class on the following request.

Coming soon

Next post will be about elegant integration of Symfony Dependency Injection component with Zend Framework. You will be able to inject your services in your controllers with a simple @Inject annotation!