<ac:macro ac:name="info"><ac:parameter ac:name="title">Zend_Options</ac:parameter><ac:rich-text-body>
<ac:macro ac:name="note"><ac:parameter ac:name="title">Terminology</ac:parameter><ac:rich-text-body><p>Throughout this proposal, the word "options" is used to refer to "the expected (preconceived) data structure of the variables passed as parameters to the methods of certain Zend Framework classes".</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_Options Component Proposal

Table of Contents

1. Overview

Zend_Options serves as a conceptual idea for standardizing, extending and persisting the predefined data structures of certain parameters (or simply, "the usage options") of certain Zend Framework class methods.

2. References

• Zend_Config
• Zend_Registry
• Zend_Mail

3. Component Requirements, Constraints, and Acceptance Criteria

• This component will allow Zend Framework class methods to define and validate the structure of the variables that are passed as parameters to their methods.
• This component will allow Zend Framework classes to expose the expected (allowable) data structure of the variables that are intended to be passed as parameters when calling their methods.
• This component will allow child classes to extend the expected data structures of their parent classes.
• This component will not attempt to replace Zend_Config or Zend_Registry, but rather to interact with them.

4. Dependencies on Other Framework Components

• Zend_Exception

5. Theory of Operation

The component attempts to address the differences in the implementation of method usage options of classes in the Zend Framework.

Usually, arrays (and sometimes instances of Zend_Config) are used to define and implement the usage options of class methods.

There is currently no standardised way to retrieve the valid (predefined) options for a given class method.

Zend_Mail_Transport_Smtp's constructor serves as a simple example of an existing Zend Framework class method that expects predefined data structures to be used as its parameters:

If Zend_Mail_Transport_Smtp had a method for defining, retrieving and governing the valid options for its constructor, its use could be simplified and predictable.

Given the Zend_Options class skeletons, Zend_Mail_Transport_Smtp could implement a getOptions() method, that returned an instance of Zend_Options.

The options for calling its constructor could then be exposed on order to be examined and modified:

Options could be assigned using instances of Zend_Options, also for different usage scenarios:

Switching between different sets of usage options could then be possible for different usage scenarios, without the need to create additional instances of a class:

If all classes use the same option interface for their methods (e.g. Zend_Options), reusing options would be more simplified, and their method parameter structures would be more predictable.

6. Milestones / Tasks

• Milestone 1: [DONE] Create class skeletons in order to be able to test feasibility.
• Milestone 2: [DONE] Publish proposal for Review.
• Milestone 3: Get input, share ideas, brainstorm. Decide whether components have a practical use in Zend Framework.
• Milestone 4: Revise proposal, approve for incubator development
• Milestone 5: Implement support for Zend_Options in constructor methods where appropriate.

7. Class Index

• Zend_Option_Exception
• Zend_Options_Exception
• Zend_Option
• Zend_Options

8. Use Cases

A simple mock class using Zend_Options to define a parameter's data structure.

Simple extension of parent class options.

Using options and option modes

9. Class Skeletons