pear:rfc:pear2_exception_policy

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
pear:rfc:pear2_exception_policy [2008/11/12 20:08] – Change namespace separator from :: to \ saltybeaglepear:rfc:pear2_exception_policy [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 3: Line 3:
 ==== Document Information ==== ==== Document Information ====
   * Title: PEAR2 Exception Policy   * Title: PEAR2 Exception Policy
-  * Version: 0.1.0 +  * Version: 1.0.1 
-  * Status: Draft+  * Status: Ratified
   * Type: Informative Document   * Type: Informative Document
   * Wiki link: http://wiki.php.net/pear/rfc/PEAR2_Exception_Policy   * Wiki link: http://wiki.php.net/pear/rfc/PEAR2_Exception_Policy
-  * Last updated: November 12th, 2008+  * Last updated: September 22nd, 2009 
 +  * Passed:  September 20th, 2009 
 + 
 +This RFC has been incorporated into the PEAR2 Standards ([[pear/rfc/pear2_standards]]). 
 ==== Author(s) Information ==== ==== Author(s) Information ====
   * Name: Brett Bieber   * Name: Brett Bieber
-  * Email: brett.bieber@gmail.com+  * Name: Chuck Burgess 
 +  * Email: pear-group@php.net
  
 ==== Legal Information ==== ==== Legal Information ====
Line 19: Line 24:
  
 ===== Introduction ===== ===== Introduction =====
-This RFC proposes changes to the [http://wiki.php.net/pear/rfc/PEAR2_Standards#Base_Exception_class 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.+This RFC proposes changes to the [[http://wiki.php.net/pear/rfc/PEAR2_Standards#Base_Exception_class|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 ===== ===== Summary =====
Line 47: Line 52:
  <?php  <?php
  namespace PEAR2\PackageName;  namespace PEAR2\PackageName;
- class UnexpectedValueException extends UnexpectedValueException implements Exception {}+ class UnexpectedValueException extends \UnexpectedValueException implements Exception {}
 </code> </code>
  
Line 78: Line 83:
  require_once 'PEAR2/Autoload.php';  require_once 'PEAR2/Autoload.php';
  try {  try {
-     $p = new PEAR2\PackageName\Foo();+     $p = new \PEAR2\PackageName\Foo();
      $p->run('bar');      $p->run('bar');
- } catch (PEAR2\PackageName\Exception $e) {+ } catch (\PEAR2\PackageName\Exception $e) {
      echo "Caught exception from PEAR2\\PackageName";      echo "Caught exception from PEAR2\\PackageName";
  }  }
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 ''catch (\PEAR2\PackageName\Exception $e)''.
 +
 +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
 +}
 +</code>
 +
 +
 +===== 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:
 +<code>
 +<?php
 +namespace foo;
 +
 +interface Exception {}
 +class InvalidArgumentException extends \InvalidArgumentException implements Exception {}
 +class OutOfBoundsException     extends \OutOfBoundsException     implements Exception {}
 +
 +class Foo {
 +
 +    public function badArg() {
 +        throw new InvalidArgumentException();
 +    }
 +
 +    public function badBounds() {
 +        throw new OutOfBoundsException();
 +    }
 +}
 +?>
 +</code>
 +
 +Bar package that uses a base Exception class:
 +<code>
 +<?php
 +namespace bar;
 +
 +class Exception                extends \Exception {}
 +class InvalidArgumentException extends \InvalidArgumentException {}
 +class OutOfBoundsException     extends \OutOfBoundsException {}
 +
 +class Bar {
 +
 +    public function badArg() {
 +        throw new InvalidArgumentException();
 +    }
 +
 +    public function badBounds() {
 +        throw new OutOfBoundsException();
 +    }
 +}
 +?>
 +</code>
 +
 +Test script:
 +<code>
 +<?php
 +
 +echo 'Testing the Exception base INTERFACE ======================' . PHP_EOL;
 +require_once 'Foo.php';
 +$x = new \foo\Foo();
 +try {
 +    echo '  * Will catch(\foo\Exception) catch a \foo\InvalidArgumentException ???' . PHP_EOL;
 +    $x->badArg();
 +} catch (\foo\Exception $e) {
 +    echo '    * Caught a \foo\Exception ok, so YES... as expected.' . PHP_EOL;
 +}
 +echo PHP_EOL;
 +
 +echo 'Testing the Exception base CLASS =====================' . PHP_EOL;
 +require_once 'Bar.php';
 +$y = new \bar\Bar();
 +try {
 +    echo '  * Will catch(\bar\Exception) catch a \bar\InvalidArgumentException ???' . PHP_EOL;
 +    $y->badArg();
 +} catch (\bar\Exception $e) {
 +    echo '    * Caught a \bar\Exception ok, so YES... this is unexpected!' . PHP_EOL;
 +}
 +?>
 +</code>
 +
 +Test results:
 +<code>
 +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:  Uncaught exception 'bar\InvalidArgumentException' in /home/ashnazg/exceptions/Bar.php:11
 +Stack trace:
 +#0 /home/ashnazg/exceptions/test.php(19): bar\Bar->badArg()
 +#1 {main}
 +  thrown in /home/ashnazg/exceptions/Bar.php on line 11
 +</code>
pear/rfc/pear2_exception_policy.1226520501.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools