Spec: Error Handling

Abstract

This specification describes the lithium way of dealing with exceptional situations and clarifies the difference between exceptions and errors.

Current Development

A code draft exists for the Error Handler, as well as associated modifications to the switchboard.

What's The Difference Between Exceptions and Errors?

n/a

Exceptions

Use Only In Exceptional Situations

The situation is really exceptional and doesn't occur under normal conditions.

Examples:

• Try reading a file and file does not exist/is not readable

Don't Use For Flow Control

Exceptions shouldn't be used for flow control because they're quite expensive (a stack trace must be generated).

Use Instead Of Error Codes

function foo($bar) {
    if (!$bar) {
        return ERROR_FOO_BAR;
    }
    return true;
}

function foo($bar) {
    if (!$bar) {
        throw new Exception("Foo Bar!");
    }
    return true;
}

Describe

Describe the exception using a message. One message may consist of multiple sentences. Start the message with a capital letter and end with a period. Always use double quotes. The message must not include the method/class name.

throw new \lithium\error\Exception("The operation `{$name}` failed.");

Only create new subclasses if you need to pass additional information.

class DatabaseException extends \lithium\core\Exception {

    protected $_sql;

    public function __construct($message = null, $info = array()) {
        extract($info);
        $this->_sql = $sql;
        parent::__construct($message, $code);
    }

    /// ...

}

Use Other Built-In Exceptions

• \BadFunctionCallException A callback refers to an undefined function or some arguments are missing.
• \BadMethodCallException A callback refers to an undefined method or some arguments are missing.
• \DomainException
• \InvalidArgumentException An argument does not match with the expected value.
• \LengthException A length is invalid.
• \LogicException A logic expression is invalid.
• \OutOfBoundsException A value is not a valid key.
• \OutOfRangeException A value does not match with a range.
• \OverflowException When you add an element into a full container.
• \RangeException When an invalid range is given.
• \RuntimeException:An error which can only be found on runtime occurs.
• \UnderflowException When you try to remove an element of an empty container.
• \UnexpectedValueException A value does not match with a set of values.

Catch What You Can Handle

Cited from http://www.c2.com/cgi/wiki?CatchWhatYouCanHandle:

[...] Ideally a catch clause should either try some other strategy to accomplish the method's goal or, more often, report the error to the end user and return the program to a passive state. Alternatively a catch clause may clean up resources and re-throw the exception [...] In all cases decisions are only made by decision making code.

Errors

Only E_USER_NOTICE and E_USER_DEPRECATED should be triggered. In all other situations use an exception.

The Exception & Error Handler

n/a

References

• http://onjava.com/pub/a/onjava/2003/11/19/exceptions.html
• http://php.net/manual/en/language.exceptions.extending.php
• http://www.c2.com/cgi/wiki?ExceptionPatterns