Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="info"><ac:parameter ac:name="title">New Proposal Template</ac:parameter><ac:rich-text-body>
<p>This page has been created from a template that uses "zones." To proceed:</p>

<li>Edit the page</li>
<li>Replace sample content within each zone-data tag with your own content</li>
<li>Remove this notice</li>
<li>Save the page</li>
<li>When you are ready for community review, move this page to the <ac:link><ri:page ri:content-title="Ready for Review" /></ac:link> section on the edit page.</li>

<ac:macro ac:name="note"><ac:parameter ac:name="title">No placeholders allowed!</ac:parameter><ac:rich-text-body>
<p>Please do not create placeholders. Wait until you have sufficient content to replace all sample data in the proposal template before creating your proposal document.</p></ac:rich-text-body></ac:macro></ac:rich-text-body></ac:macro>

<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_Magic Component Proposal

Proposed Component Name Zend_Magic
Developer Notes
Proposers My Name
Zend Liaison TBD
Revision 1.0 - 1 January 2008: Initial Draft. (wiki revision: 5)

Table of Contents

1. Overview

Registry: "A well-known object that other objects can use to find common objects and services. [...] I almost always see some form of Registry in an application, but I always try to access objects through regular inter-object references instead. Basically, you should use a Registry as a last resort." (Fowler 2003, pp. 480-483)

Registries must be avoided at all costs but alas, they are sometimes necessary. The use of registries is and should be very limited and, as such, no other components of the Zend Framework must depend on the registry. It is indeed a shortcut to register object references in the registry but this breaks the normal dependency/relationship chain which characterizes powerful and meaningful object-orientated designs. Using a registry is not a substitute for dependency injection.

Zend_Registry, in its current implementation, has many restrictions which limit its usefulness. First and foremost, Zend_Registry is a "static object", thus limiting one to have one and only one registry for a complex application which may necessitate many registries with domain specific methods. It is also limited to a one level hierarchy, which is very impractical and, I gather, has prompted the Zend_Registry_Namespace proposal (which is superseded by this proposal). The goal of this proposal is to create a specification for a new component, which will replace the current registry implementation. This new component will be easy to use, easy to test and easy to extend.

2. References

  • Fowler, Martin, Patterns of Enterprise Application Architecture, 2003.

3. Component Requirements, Constraints, and Acceptance Criteria

  • This component must be easily extensible
  • This component must provide one instance which is available in all scopes and an unlimited number of instances in any other number of scopes
  • This component must not be used by any other components of the Zend Framework
  • The use of this component must be discouraged in documentation
  • This component must be able to implement an arbitrary number of levels of hierarchy

4. Dependencies on Other Framework Components

  • Zend_Exception

5. Theory of Operation

The "global" registry is accessible statically (thus from any scope), by calling the Zend\Registry::getInstance() method. Ideally, this dependency should be injected but, considering that this component, as much as any singleton, is bound to be abused, a mechanism to replace the object obtained with the getInstance() method should be contemplated for testability purposes.

An arbitrary number of registries may be created, simply by instanciating an object of the class Zend\Registry.

There exist three types of registry entries: variables, values and subregistries. Variables are mutable, values are immutable and subregistries are simply another level of hierarchy (and are also immutable). A quick rule of thumb to verify if the registry is abused: if most of the entries are not values, you are doing something wrong.

Dummy code:
$registry = new Zend\Registry;
$registry->key = 'value'; // Immutable by default
$registry->key = 'newValue'; // An exception is thrown
$registry->set('key', 'yetAnotherValue'); // An exception is thrown
unset($registry->key); // An exception is thrown

$registry->new('mutableKey', true); // True here means "mutable"
$registry->mutableKey = 'foo';
$registry->mutableKey = 'bar';

$registry->sub->key = 'bar';
$registry->sub->bar = 'foo';
unset($registry->sub); // Throws exception

6. Milestones / Tasks

Describe some intermediate state of this component in terms of design notes, additional material added to this page, and / code. Note any significant dependencies here, such as, "Milestone #3 can not be completed until feature Foo has been added to ZF component XYZ." Milestones will be required for acceptance of future proposals. They are not hard, and many times you will only need to think of the first three below.

  • Milestone 1: design notes will be published here
  • Milestone 2: Working prototype checked into the incubator supporting use cases #1, #2, ...
  • Milestone 3: Working prototype checked into the incubator supporting use cases #3 and #4.
  • Milestone 4: Unit tests exist, work, and are checked into SVN.
  • Milestone 5: Initial documentation exists.

If a milestone is already done, begin the description with "[DONE]", like this:

  • Milestone #: [DONE] Unit tests ...

7. Class Index

  • Zend_Magic_Exception
  • Zend_Magic (factory class)
  • Zend_Magic_MindProbe
  • Zend_Magic_MindProbe_Intent
  • Zend_Magic_Action
  • Zend_Magic_CodeGen

8. Use Cases


... (see good use cases book)

9. Class Skeletons



Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Feb 06, 2011

    <p>Archiving this proposal, feel free to recover it when you want to work on it again. For more details see <a href="">this email</a>.</p>