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:22] – Add FAQ about why a base interface 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 12th2008+  * Last updated: September 22nd2009 
 +  * 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 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 93: Line 98:
 Q. **Why a base package exception interface?** 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)''.+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: This allows end users to easily do the following:
Line 100: Line 105:
 try { try {
     //do something with PEAR2\Package1     //do something with PEAR2\Package1
-} catch (PEAR2\Package1\Exception $e) {+} catch (\PEAR2\Package1\Exception $e) {
     //do the same thing with PEAR2\Package2     //do the same thing with PEAR2\Package2
-} catch(Exception $e) {+} catch(\Exception $e) {
     //an unknown exception occurred     //an unknown exception occurred
 } }
 </code> </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.1226521330.txt.gz · Last modified: 2017/09/22 13:28 (external edit)