Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Container Component Proposal

Proposed Component Name Zend_Container
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Container
Proposers Bradley Holt
Zend Liaison TBD
Revision 1.0 - 28 July 2008: Initial Draft. (wiki revision: 20)

Table of Contents

1. Overview

Zend_Container is a simple dependency injection container that is intended to replace use of Zend_Registry and class-based singletons. This is a proposal for a simpler dependency injection component than Zend_Di and Zend_Context. Note that the word "component" is overloaded in this proposal. This proposal is for a Zend Framework "component" but it also uses the word "component" to refer to an object managed by Zend_Container.

The author of this component is not entirely sure that a dependency injection component is inline with Zend Framework's balance of power and simplicity. However, the author believes that if Zend Framework is to have a dependency injection component that this component should be as simple as possible and designed to solve a limited set of use cases.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • This component will replace Zend_Registry.
  • This component will use reflection.
  • This component will not allow more than one instance of a given type to be registered in a given container.
  • This component will not act as a factory (except for creating the single instance of a given type).
  • This component will allow manual component registration or configuration-based component registration.
  • This component will allow a hierarchy of containers.
  • This component will allow a container to have zero or one parent container.
  • This component will allow a container to have zero or more child containers.
  • This component will allow a child container to access components in its parent container.
  • This component will not allow a parent container to access components in its child container(s).

4. Dependencies on Other Framework Components

  • Zend_Reflection
  • Zend_Loader
  • Zend_Config (optional)
  • Zend_Exception

5. Theory of Operation

Zend_Container provides a simple dependency injection container in which components may be registered. A component may be registered under its own type or one of its parent types (class or interface). Only one component of a given type may be registered in a given container. This means that two objects of the same type may be registered in the same container if they are registered under different parent types. This also means that two objects of different types may not be registered in the same container if an attempt is made to register them under the same parent type.

Components can be registered manually using calls to the addComponent method or through configuration. Registering components through configuration simply calls the appropriate addComponent methods for you based on the contents of your configuration object. Dependencies to be injected are detected using reflection on added components.

A hierarchy of containers can be created by assigning a parent container upon instantiating a new container. When attempting to get a component of a given type a container will first look in itself and then its parent container (if applicable). The parent container will recurse to its parent container until the component is found or there are no more parent containers. This means that if a component of the same type is registered in a child and a parent container, the component in the child container will be used.

6. Milestones / Tasks

  • Milestone 1: Write proposal
  • Milestone 2: Design interface
  • Milestone 3: Use cases
  • Milestone 3: Gather feedback and incorporate design changes
  • Milestone 4: Approval of Zend_Reflection
  • Milestone 5: Review by the Zend Team
  • Milestone 6: Write unit tests
  • Milestone 7: Develop full implementation
  • Milestone 8: Write API doc
  • Milestone 9: Documentation

7. Class Index

  • Zend_Container
  • Zend_Container_Components
  • Zend_Container_Exception
  • Zend_Container_Types

8. Use Cases

UC-01: Manually wiring dependencies

The above code is the equivalent of (assuming setter injection):

UC-02: A container with a parent container

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Oct 21, 2008

    <p>It looks simple enough to be useful in ZF imho <ac:emoticon ac:name="smile" /><br />
    Is there already some code available to look at?<br />
    Also, it might be nice to add a use case that shows a common scenario in ZF apps and how Zend_Container could be used in such a scenario.</p>

  2. Jan 03, 2009

    <p>From the current usecases I have to assume that dependencies are injected into a class (assuming setter injection) based on the typehint of the setter method. This gives the user no way to specify which setters are mandatory and should be injected, and which are optional.</p>

    <p>The only way around this - without touching the source of the receiving class - would be to explicity tell the compontent which setters should be injected. Or use constructor injection: Any non-optional argument of the constructor obviously is a mandatory dependency that should be injected. But again this won't work with many Zend_Framework classes, that have only optional arguments on the constructor to give the user a choice between setting the dependencies in the constructor or through setters.</p>

    <p>It also must be possible to inject string configuration values that are necessary for operation of a component. An example would be the URI for a Zend_Http_Client. The component can't be used without it, so it must be injected like any required object dependency. A possible API for this</p>

    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    // setter injection
    $container->addComponent('Zend_Http_Client', 'Zend_Http_Client', array(
    'setUri' => array('http://example.com'),
    'setConfig' => array(
    'maxredirects' => 0,
    'timeout' => 30)));

    // constructor injection
    $container->addComponent('Zend_Http_Client', 'Zend_Http_Client', array(
    '__construct' => array(
    'http://example.com',
    array(
    'maxredirects' => 0,
    'timeout' => 30))));
    ]]></ac:plain-text-body></ac:macro>

    <p>This explicit notation for setter and constructor arguments can also solve the problem of specifying mandatory dependencies and dependencies with missing type hints.</p>

    <p>It can also be possible, to add as a component a concrete instance of a class instead of just the class name:</p>

    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $container->addComponent('Zend_Http_Container', new Zend_Http_Container('http://example.com'));
    ]]></ac:plain-text-body></ac:macro>

    1. Jan 07, 2009

      <p>I implemented a quick prototype / proof of concept for the above examples. Now I'm waiting for my boss to sign the CLA, but I'd like to discuss the relative merits of the approaches. Maybe they can be combined?</p>

  3. Jan 17, 2009

    <p>Here are a few usecases covered by the prototype that I implemented for internal use.</p>

    <table><tbody>
    <tr>
    <th><p>UC-01: Explicit Constructor Injection</p></th>
    </tr>
    </tbody></table>

    <p>Using DI to parametrize Zend_Log and its writer.</p>
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $di = new Zend_Container();
    $di->addComponent('Zend_Log')
    ->injectConstructor('Zend_Log_Writer_Stream');
    $di->addCompontent('Zend_Log_Writer_Stream')
    ->injectConstructor('/path/to/logfile');

    $log = $di->getInstance('Zend_Log');
    ]]></ac:plain-text-body></ac:macro>

    <table><tbody>
    <tr>
    <th><p>UC-02: Implicit Constructor Injection</p></th>
    </tr>
    </tbody></table>

    <p>Zend_Container can use reflection to select components to inject.</p>
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $di = new Zend_Container();
    $di->addComponent('Zend_Log_Writer_Abstract', 'Zend_Log_Writer_Stream')
    ->injectConstructor('/path/to/logfile');

    $log = $di->getInstance('Zend_Log');
    ]]></ac:plain-text-body></ac:macro>

    <table><tbody>
    <tr>
    <th><p>UC-03: Setter Injection</p></th>
    </tr>
    </tbody></table>

    <p>Parametrizing a Zend_Http_Client through its setters. setAdapter doesn't have a typehint, so implicit injection won't work.</p>
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $di = new Zend_Container();
    $di->addComponent('Zend_Http_Client')
    ->injectSetter('setUri', 'http://www.example.com')
    ->injectSetter('setAdapter', 'Zend_Http_Client_Adapter_Test');

    $client = $di->getInstance('Zend_Http_Client');
    ]]></ac:plain-text-body></ac:macro>

    <table><tbody>
    <tr>
    <th><p>UC-04: Configuration</p></th>
    </tr>
    </tbody></table>

    <p>The following is the ini-file equivalent to UC-03</p>
    <ac:macro ac:name="code"><ac:parameter ac:name="title">dependencies.ini</ac:parameter><ac:default-parameter>none</ac:default-parameter><ac:plain-text-body><![CDATA[
    [Zend_Http_Client]
    class = "Zend_Http_Client"
    init.setUri = "http://www.example.com"
    init.setAdapter = "Zend_Http_Client_Adapter_Test"
    ]]></ac:plain-text-body></ac:macro>
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $di->addconfig(new Zend_Config_Ini('dependencies.ini'));
    $client = $di->getInstance('Zend_Http_Client');
    ]]></ac:plain-text-body></ac:macro>

    <p>I think this would greatly increase the possible uses of this propoal. Comments welcome.</p>

  4. Apr 10, 2009

    <p>You could use <a href="http://code.google.com/p/addendum/">Addendum</a> if you wanted to be really Java-ish. <ac:emoticon ac:name="smile" /></p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    class Example
    {
    /**

    • @Inject
      */
      protected $_something;

    public function setSomething(Something $something)

    Unknown macro: { $this->_something = $something; }

    }
    ]]></ac:plain-text-body></ac:macro>
    <p>Erm ... not sure whether to annotate the field or the setter.</p>

  5. Feb 05, 2011

    <p>Archiving this proposal, feel free to recover it when you want to work on it again. For more details see <a href="http://framework.zend.com/wiki/display/ZFDEV/Archiving+of+abandoned+proposals+(Feb+5+2011)">this email</a>.</p>