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
Last revisionBoth sides next revision
pear:rfc:pear2_exception_policy [2008/11/12 20:22] – Add FAQ about why a base interface saltybeaglepear: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: 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 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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools