[revised RFC] PEAR error handling

Error Handling RFC, revision 1 July 31, 2003 1. All packages that define new errors must define special error constants with a prefix of the package name followed by ERROR_, as in PHPDOCUMENTOR_ERROR_INVALID_TAG. Note that the use of pre-defined constants from other packages such as DB_ERROR, does not require redefinition. 2. Error constants must be returned as an error code with all errors. 3. Error constants will never be referred to by number, only by constant name. To resolve conflicts between packages, the returned error's getType() method must be used to determine which package an error came from. 4. All packages that define new errors as noted in point [1.] must extend PEAR_Error with an error class named Package_Error, as in PhpDocumentor_Error, and must use this error class in returning all unique errors. If there is a difference between an error and exception, the Package_Exception class should be defined and used to throw a fatal exception. An example of this difference is a fatal documentation error in PhpDocumentor (error), and an invalid input to a function in PhpDocumentor (exception). 5. It is suggested to define Package_Warning and Package_Notice classes for those packages that need to pass warnings and notices to a callback function, to allow non-fatal but potential errors to be ignored, or displayed and/or logged as necessary. These should be called using PEAR::raiseError() without returning the warning/notice, to allow a callback function to catch the information for logging/display. 6. Only errors and exceptions should be returned. If an error must terminate the program execution, it is an exception. If an error must terminate the current function, but not the program execution, it is an error. If an error is a problem that need not terminate execution, or might be questionable but intended behavior, a warning should be used (for example, deprecated methods). If an error is simply a valid situation that could lead to other more serious errors in certain conditions, it is a notice. Examples of error handlers: PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'handler'); function handler($err) { switch ($err->getType()) {

      case 'phpdocumentor_error' :
         handleDocError($err);
      break;
      case 'db_error' :
         handleDBError($err);
      break;
      case 'msgserver_warning' :
         if ($err->getCode == MSGSERVER_ERROR_INVALID_INPUT) {
            // convert this warning into a phpDocumentor exception
            PhpDocumentor::throw(PHPDOCUMENTOR_ERROR_MSGSERVER_INVALID, $err);
         }

} } function handleDocError($err) { switch ($err->getCode()) {

      case PHPDOCUMENTOR_ERROR_THINGY :
      // handle this error
      break;

} } function handleDBError($err) { switch ($err->getCode()) {

      case DB_ERROR_THAT_THINGY :
      // handle this DB-related error
      break;

}