pear:rfc:pear2_exception_policy

This is an old revision of the document!


Summary

Information

Document Information

Author(s) Information

  • Name: Brett Bieber
  • Email: brett.bieber@gmail.com
  • This RFC is under the BSD License

Discussion List

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.

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.

pear/rfc/pear2_exception_policy.1226520501.txt.gz · Last modified: 2017/09/22 13:28 (external edit)