[dev] Code/Logic Exceptions vs. Execution Exceptions

[Michael M Slusarz]

Before I throw this into CODING_STANDARDS, wanted to run this by the list.


Exceptions in Framework Packages
================================

Exceptions thrown in packages can be divided into two categories:  
code/logic exceptions and execution exceptions.

Code/Logic Exceptions
---------------------

These are exceptions that should be thrown when there is an issue with  
the programming logic - e.g. the environment was not properly set up  
by an application, or a required parameter was not provided.

These type of exceptions should throw one of the SPL Exceptions (e.g.  
BadFunctionCallException, LogicException, RuntimeException), NOT a  
package exception.  This ensures that errors will normally cause a  
fatal error, rather than potentially being caught and ignored by the  
calling code.  As such, there is no need to document the exception in  
phpdoc.  Further, the exception messages should not be translated, as  
these messages are intended for developers not users.

Execution Exceptions
--------------------

These are exceptions that are thrown due to an error encountered while  
performing the action requested by the calling code.

Any package that throws at least one execution Exception should define  
a Package_Name_Exception class that extends Horde_Exception.   
Execution Exceptions should use this class when throwing an error.   
Any method that throws this kind of exception should document it in  
the phpdoc using the @throws keyword.  These messages should be  
translated, as they potentially could be displayed to the user at the  
application level.


michael

___________________________________
Michael Slusarz [slusarz at horde.org]