This is an old revision of the document!
Summary
Information
Document Information
- Title: PEAR2 Exception Policy
- Version: 1.0.0
- Status: Ratified
- Type: Informative Document
- Last updated: November 12th, 2008
- Passed: September 20th, 2009
This RFC has been incorporated into the PEAR2 Standards (pear2_standards).
Author(s) Information
- Name: Brett Bieber
- Name: Chuck Burgess
- Email: pear-group@php.net
Legal Information
- This RFC is under the BSD License
Discussion List
- Currently only pear-group however, future is http://news.php.net/php.pear.dev
Introduction
This RFC proposes changes to the PEAR2 Standards regarding the Base Exception class requirement. Changes available in PHP 5.3 make the base exception class PEAR2\Exception unnecessary. Further, this RFC proposes how exceptions should be handled at the individual package level, and provides recommendations on the usage of SPL exception classes.
Summary
The PEAR2 Standards include a package related rule defining how exceptions should be handled in PEAR2 packages. This includes a base exception class named PEAR2\Exception which each package must extend.
The base exception class in PEAR2 intended to supplement the Exception class available in PHP, adding features which were missing at the time, and provide that functionality to all PEAR2 classes. The getCause() function in PEAR2_Exception provided a mechanism for nested/chained exceptions. With the addition of the getPrevious() function in PHP 5.3, PEAR2_Exception offers no advantages over the base Exception class, and should be removed from the PEAR2 Package-related rules as a required external dependency.
This RFC proposes changing the Base Exception class rule to Base Package Exception interface, and further define how exceptions should be used at the package level.
Proposed Changes:Base Exception interface
Each package must define a base Exception interface which is implemented by any exception thrown within the package.
PEAR2/PackageName/Exception.php
<?php namespace PEAR2\PackageName; interface Exception {}
SPL exceptions are encouraged, and should be used when possible.
Extending SPL Example: PEAR2/PackageName/UnexpectedValueException.php
<?php namespace PEAR2\PackageName; class UnexpectedValueException extends \UnexpectedValueException implements Exception {}
Exception throwing example:
<?php namespace PEAR2\PackageName; class Foo { function run($method) { switch($method) { case 'add': case 'del': case 'up': $this->$method(); break; default: throw new UnexpectedValueException($method . ' is not a valid method.'); } } }
User exception catching example:
<?php require_once 'PEAR2/Autoload.php'; try { $p = new \PEAR2\PackageName\Foo(); $p->run('bar'); } catch (\PEAR2\PackageName\Exception $e) { echo "Caught exception from PEAR2\\PackageName"; }
Requirement
No Exceptions to this rule
Proposed Changes
Alter the Base Exception class rule to the Base Package Exception interface above.
Common Questions
Q. Why a base package exception interface?
A. By implementing the base package exception interface, all exceptions for a given pear package can be caught with catch (\PEAR2\PackageName\Exception $e)
.
This allows end users to easily do the following:
<?php try { //do something with PEAR2\Package1 } catch (\PEAR2\Package1\Exception $e) { //do the same thing with PEAR2\Package2 } catch(\Exception $e) { //an unknown exception occurred }