Section 7.4. Exceptions

7.4. Exceptions

7.4.1. What Are Exceptions?

Exceptions are a high-level built-in error mechanism that is new as of PHP 5. Just as for PEAR errors, the relative cost of generating exceptions is high, so use them only to notify about unexpected events.

Exceptions are objects that you can "throw" to PHP. If something is ready to "catch" your exception, it is handled gracefully. If nothing catches your exception, PHP bails out with an error message like this:

[View full width]
 Fatal error: Uncaught exception 'FileException' with message 'Could not open config /home /ssb/foo/conf/my.conf' in .../My/Config.php:49 Stack trace: #0 .../My/Config.php(31): config->parseFile('my.conf') #1 .../My/prepend.inc(61): config->__construct('my.conf') #2 {main}   thrown in .../My/Config.php on line 49 

Although PEAR errors are loosely modeled after exceptions, they lack the execution control that exceptions provide. With PEAR errors, you always need to check if a return value is an error object, or the error does not propagate down to the original caller. With exceptions, only code that cares about a particular exception needs to check for (catch) exceptions.

7.4.2. try, catch, and throw

Three language constructs are used by exceptions: try, catch, and throw.

To handle an exception, you need to run some code inside a try block, like this:

 try {     $article->display(); } 

The try block instructs PHP to look out for exceptions generated as the code inside the block is executed. If an exception occurs, it is passed on to one or more catch blocks immediately following the try block:

 catch (Exception $e) {     die($e->getMessage()); } 

As you can see, the variable $e seems to contain an object. It doesexceptions are actually objects, the only requirement is that it must be or inherit the Exception class. The Exception class implements a few methods, such as getMessage(), that give you more details about where the origin and cause of the exception. See Chapter 3, "PHP 5 OO Language," the details on the Exception class.

To generate an exception in your own code, use the throw statement:

 $fp = @fopen($filename, "r"); if (!is_resource($fp)) {    throw new FileException("could not read '$filename'"); } while ($line = fgets($fp)) { ... 

In the previous catch example, you saw that the exception was an object. This example creates that object. There is nothing magical about this syntax; throw simply uses the specified object as part of the exception.

To semantically separate various types of exceptions, you can define subclasses of Exception as you see fit:

 class IO_Exception extends Exception { } class XML_Parser_Exception extends Exception { } class File_Exception extends IO_Exception { } 

No member variables or methods are required in the exception class; everything that you need is already defined in the built-in Exception class.

PHP checks the class names in the catch statement against the exception object with a so-called is_a comparison. That is, if the exception object is an instance of the catch class, or an instance of a subclass, PHP executes the catch block. Here is an example:

 try {     $article->display(); } catch (IO_Exception $e) {     print "Some IO problem occurred!"; } catch (XML_Parser_Exception $e) {     print "Bad XML input!"; } 

Here, the IO_Exception catch catches both IO_Exception and File_Exception, because File_Exception inherits IO_Exception.

If every catch fails to capture the exception, the exception goes on to the calling function, giving the calling function the opportunity to catch it.

If the exception is not caught anywhere, PHP offers a last chance: the exception-handling function. By default, PHP prints the error message, class name, and a backtrace. By calling set_exception_handler(), you can replace this built-in behavior:

 <?php     function my_exception_handler(Exception $e) {     print "Uncaught exception of type " . get_class($e) . "\n";     exit; } set_exception_handler("my_exception_handler"); throw new Exception; 

In this example, my_exception_handler is called for any exception that is not caught inside a catch block. The exception handler function receives the exception object as its single parameter. The exception handler function effectively negates the exception, execution will proceed as if the exception was not thrown.

Exceptions may not be thrown from within an exception handler function.