[RFC] Errors and handling in PEAR

Hi, I'd like to propose a new way of thinking about error-handling to amend the discussion started earlier. 1. All packages that raise unique errors must define special error constants with a prefix of the package name followed by ERR_, as in PHPDOCUMENTOR_ERR_INVALID_TAG 2. 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. 3. All packages that raise unique errors 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). 4. 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. 5. 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, it is a notice. That's about it :) Greg