7.1 Before and After: Handling Errors

This section compares PHP 4's style of error handling, where you check the return values of functions, with the new PHP 5 method known as exceptions.

7.1.1 PHP 4: Checking Return Values

Traditional error handling as implemented in PHP 4 requires you to interleave a significant amount of bug-handling code with your program logic. This not only makes scripts hard to understand, but it's annoying to check every return value.

For instance, Example 7-1 shows how most people use the DOM XML extension.

Example 7-1. Failing to check for errors

 $version = '1.0'; $element = 'address-book'; $dom = domxml_new_doc($version); $ab = $dom->create_element($element); $ab = $dom->append_child($ab); 

It seems unlikely that any of these methods will fail, so most people omit error checking. However, it's entirely possible that something could go wrong. For instance, create_element( ) fails when the element name contains illegal characters , such as spaces or ampersands ( & ). Since this code does zero error handling, there's no way to identify a problem and proceed accordingly .

Example 7-2 is a rewritten version of Example 7-1 that handles errors.

Example 7-2. Checking return values

 $version = '1.0'; $element = 'address-book'; if ($dom = domxml_new_doc($version)) {     if ($ab = $dom->create_element($element)) {         if ($ab = $dom->append_child($ab)) {             // Successfully appended address-book element         } else {              // Cannot append child         }     } else {         // Cannot create <address-book> element     } } else {     // Cannot create new document } 

When a PHP 4 DOM method has an error, it returns false . This lets you identify problems and handle them inside the else blocks.

This code is more robust, but it's 16 lines instead of 6. It's also more difficult to decipher. As a result, many of the benefits of proper error handling are outweighed by these deficits.

7.1.2 PHP 5: Catching Exceptions

PHP 5 provides a different way to identify and track errors. This method is called exception handling. Exceptions make it possible to handle errors in a clear and comprehensive fashion by avoiding nested if statements.

An exception is a signal that some error (or other non-normal activity) has occurred. When an exception occurs, it is "thrown" by the offending method. A thrown exception can be "caught" by a block of code known as an exception handler, which processes the exception and takes action as necessary.

Exceptions become more clear when you see them in PHP instead of English. Using PHP 5 and exceptions, Example 7-2 turns into Example 7-3.

Example 7-3. Catching exceptions

 $version = '1.0'; $element = 'address-book'; try {     $dom = new DOMDocument($version);     $ab = new DOMElement($element);     $ab = $dom->appendChild($ab); } catch (DOMException $e) {     print $e; } 

Exception handlers operate on code wrapped around a try block. (Here it's checking DOM objects.) Then, just like you set up an if/else , there's a catch block below the try .

The catch block specifies the type of exception to catch and the variable in which to store it. This example uses the special DOM exception class called DOMException , and names it $e . Inside the catch , you can access $e to find out more information about the problem. $e isn't anything magical ; it's just a variable that PHP populates with an object when an exception is thrown.

The easiest way to get an overview of the exception is by printing $e . This triggers the object's _ _toString( ) method, which returns a formatted version of all the data stored in the object.

For instance, if $element is set to an illegal XML element name, such as & , Example 7-3 prints:

  exception 'DOMException' with message 'Invalid Character Error'   in /www/www.example.com/dom.php:7   Stack trace:   #0 {main}  

The exception is a DOMException , which tells you it's from the DOM extension. Its message is Invalid Character Error , and it occurred in on line 7 of /www/www.example.com/dom.php . At the bottom is a stack trace, something that's described in more detail in Section 7.8, later in this chapter.

PHP dies with a fatal error when you fail to catch an exception, as in Example 7-4.

Example 7-4. Failing to catch an exception

 $version = '1.0'; $element = '&'; // & is an ILLEGAL element name $dom = new DOMDocument($version); $ab = new DOMElement($element); $ab = $dom->appendChild($ab);  PHP Fatal error:  Uncaught exception 'DOMException' with message   'Invalid Character Error' in /www/www.example.com/dom.php:7   Stack trace:   #0 {main}   thrown in /www/www.example.com/dom.php on line 7  

You can control this output using a custom exception handler. See Section 7.6, later in this chapter, for more details.