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

Proposed Component Name Zend_Deprecation
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Deprecation
Proposers Tobias Gies
Zend Liaison TBD
Revision 1.0 - 3 June 2008: Initial Draft. (wiki revision: 5)

Table of Contents

1. Overview

Zend_Deprecation is a component that is meant to offer developers both an easy way to control the behaviour of deprecation errors and a unified interface and nomenclature to provide the user with deprecation information.

The need for such a component arises as we approach version 2.0 and need to find a way to give developers information about soon-to-be-removed components while still maintaining a sensible amount of backwards compatibility.

The component is meant to be designed in a similar fashion to PHP's own error handling functionality.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • This component will offer a completely static interface.
  • This component will display error messages in the same way PHP does, respecting the setting of the ini variable html_errors
  • This component will log error messages to an error stack which can be called later to retrieve the errors and, for example, log them to a file, output them to a command line, etc.
  • This component will offer a way to configure which kinds of deprecation errors will be displayed, including an option to turn off the displaying of error messages completely.
  • This component will offer a way to configure which kinds of deprecation errors will be logged, including an option to turn off the logging of error messages completely.

4. Dependencies on Other Framework Components

  • Zend_Exception

5. Theory of Operation

In her bootstrap, the developer will be able to configure the behaviour of ALL deprecation errors that could ever be thrown during the lifetime of the script. During the script lifetime, deprecation errors thrown by the application will be handled with respect to the settings made in the bootstrap.

6. Milestones / Tasks

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

7. Class Index

  • Zend_Deprecation

8. Use Cases

UC-01

Developer configures behaviour of deprecation error handling

UC-02

Example of throwing a deprecation error in a deprecated component

UC-03

Example of pulling deprecation errors from the stack later on

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. Jun 20, 2008

    <p>Is this proposal ready for community review? If so, please move it to the 'Ready for Review' section and announce to the fw-general mailing list.</p>

    <p>,Wil</p>

  2. Jul 17, 2008

    <p>+1</p>

  3. Jul 17, 2008

    <p>I agree with Bill Karwin's post on the mailing list that raising PHP's built-in E_USER_NOTICE with trigger_error() may be sufficient to do the job without requiring a whole new component.</p>

    <p>Since one advantage of this proposal compared to E_USER_NOTICE is that this can support several different types of deprecation. As such, this is a good opportunity to discuss whether the benefit of that flexibility outweighs the cost.</p>

    <p>It's my opinion that based on the information we have available right now, simply raising an E_USER_NOTICE (with a clear message) from any deprecated API would be good enough to inform the developer of what they need to change. If we get any more clarity on what the final requirements will really be, we may discover that E_USER_NOTICE is not enough, and hence need a more sophisticated solution, such as that proposed here.</p>

    1. Jul 22, 2008

      <p>PHP 5.3 adds a E_USER_DEPRECATED error type. This should be sophisticated enough.</p>