pear:rfc:pear2_exception_policy
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionLast revisionBoth sides next revision | ||
pear:rfc:pear2_exception_policy [2008/11/07 17:00] – created dufuz | pear:rfc:pear2_exception_policy [2009/09/22 22:05] – fix typo ashnazg | ||
---|---|---|---|
Line 3: | Line 3: | ||
==== Document Information ==== | ==== Document Information ==== | ||
* Title: PEAR2 Exception Policy | * Title: PEAR2 Exception Policy | ||
- | * Version: | + | * Version: 1.0.1 |
- | * Status: | + | * Status: |
* Type: Informative Document | * Type: Informative Document | ||
* Wiki link: http:// | * Wiki link: http:// | ||
- | * Last updated: | + | * Last updated: |
+ | * Passed: | ||
+ | |||
+ | This RFC has been incorporated into the PEAR2 Standards ([[pear/ | ||
==== Author(s) Information ==== | ==== Author(s) Information ==== | ||
* Name: Brett Bieber | * Name: Brett Bieber | ||
- | * Email: | + | |
+ | | ||
==== Legal Information ==== | ==== Legal Information ==== | ||
Line 19: | Line 24: | ||
===== Introduction ===== | ===== Introduction ===== | ||
- | This RFC proposes changes to the [http:// | + | This RFC proposes changes to the [[http:// |
===== Summary ===== | ===== 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 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/ | 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/ | ||
Line 36: | Line 41: | ||
<code php> | <code php> | ||
<? | <? | ||
- | | + | |
| | ||
</ | </ | ||
Line 46: | Line 51: | ||
<code php> | <code php> | ||
<? | <? | ||
- | | + | |
- | class UnexpectedValueException extends UnexpectedValueException implements Exception {} | + | class UnexpectedValueException extends |
</ | </ | ||
Line 54: | Line 59: | ||
<code php> | <code php> | ||
<? | <? | ||
- | | + | |
class Foo | class Foo | ||
{ | { | ||
Line 78: | Line 83: | ||
| | ||
try { | try { | ||
- | $p = new PEAR2::PackageName::Foo(); | + | $p = new \PEAR2\PackageName\Foo(); |
| | ||
- | } catch (PEAR2::PackageName::Exception $e) { | + | } catch (\PEAR2\PackageName\Exception $e) { |
- | echo " | + | echo " |
} | } | ||
</ | </ | ||
Line 90: | Line 95: | ||
Alter the **Base Exception class rule** to the **Base Package Exception interface** above. | 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 '' | ||
+ | |||
+ | This allows end users to easily do the following: | ||
+ | <code php> | ||
+ | <?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 | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== Full Code Example ===== | ||
+ | This example contrasts the usage of a base Exception interface with a base Exception class. | ||
+ | |||
+ | Foo package that uses a base Exception interface: | ||
+ | < | ||
+ | <?php | ||
+ | namespace foo; | ||
+ | |||
+ | interface Exception {} | ||
+ | class InvalidArgumentException extends \InvalidArgumentException implements Exception {} | ||
+ | class OutOfBoundsException | ||
+ | |||
+ | class Foo { | ||
+ | |||
+ | public function badArg() { | ||
+ | throw new InvalidArgumentException(); | ||
+ | } | ||
+ | |||
+ | public function badBounds() { | ||
+ | throw new OutOfBoundsException(); | ||
+ | } | ||
+ | } | ||
+ | ?> | ||
+ | </ | ||
+ | |||
+ | Bar package that uses a base Exception class: | ||
+ | < | ||
+ | <?php | ||
+ | namespace bar; | ||
+ | |||
+ | class Exception | ||
+ | class InvalidArgumentException extends \InvalidArgumentException {} | ||
+ | class OutOfBoundsException | ||
+ | |||
+ | class Bar { | ||
+ | |||
+ | public function badArg() { | ||
+ | throw new InvalidArgumentException(); | ||
+ | } | ||
+ | |||
+ | public function badBounds() { | ||
+ | throw new OutOfBoundsException(); | ||
+ | } | ||
+ | } | ||
+ | ?> | ||
+ | </ | ||
+ | |||
+ | Test script: | ||
+ | < | ||
+ | <?php | ||
+ | |||
+ | echo ' | ||
+ | require_once ' | ||
+ | $x = new \foo\Foo(); | ||
+ | try { | ||
+ | echo ' | ||
+ | $x-> | ||
+ | } catch (\foo\Exception $e) { | ||
+ | echo ' | ||
+ | } | ||
+ | echo PHP_EOL; | ||
+ | |||
+ | echo ' | ||
+ | require_once ' | ||
+ | $y = new \bar\Bar(); | ||
+ | try { | ||
+ | echo ' | ||
+ | $y-> | ||
+ | } catch (\bar\Exception $e) { | ||
+ | echo ' | ||
+ | } | ||
+ | ?> | ||
+ | </ | ||
+ | |||
+ | Test results: | ||
+ | < | ||
+ | Testing the Exception base INTERFACE ====================== | ||
+ | * Will catch(\foo\Exception) catch a \foo\InvalidArgumentException ??? | ||
+ | * Caught a \foo\Exception ok, so YES... as expected. | ||
+ | |||
+ | Testing the Exception base CLASS ===================== | ||
+ | * Will catch(\bar\Exception) catch a \bar\InvalidArgumentException ??? | ||
+ | PHP Fatal error: | ||
+ | Stack trace: | ||
+ | #0 / | ||
+ | #1 {main} | ||
+ | thrown in / | ||
+ | </ |
pear/rfc/pear2_exception_policy.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1