7.4 The Exception Class

What you're actually catching when PHP throws an exception is either an instance of the Exception class or a class that's descended from Exception.

The methods of the Exception class provide you with easy access to the individual details of the exception, such as the message, error code, filename, and line number. Use them when the overview you get from printing an object doesn't help you find the information you need.

For example, you might want to take different action based upon the specific error code stored in the exception. Some problems may be recoverable, while others aren't.

Table 7-1 contains a list of all the exception methods and what they do.

Table 7-1. Exception methods

Method name


getMessage( )

A text description of the error

getCode( )

A numeric error code

getFile( )

The filename where the error occurred

getLine( )

The line where the error occurred

getTrace( )

The array output of debug_backtrace( )

getTraceAsString( )

The string output of debug_print_backtrace( )

_ _toString( )

A comprehensive description of the exception

Example 7-5 calls four of the Exception class methods.

Example 7-5. Retrieving exception specifics
$version = '1.0';

$element = '&'; // & is an ILLEGAL element name

try {

    $dom = new DOMDocument($version);

    $ab = new DOMElement($element);

    $ab = $dom->appendChild($ab);

} catch (Exception $e) {

    error_log('Error in file ' . $e->getFile( ) . ' on line ' . 

       $e->getLine( ) . ".\n" . 'Error message: "' . $e->getMessage( ) . 

       '" and error code: ' . $e->getCode( ) . '.');


Error in file /www/www.example.com/dom.php on line 7.

Error message: "Invalid Character Error" and error code: 5.

The getFile( ) and getLine( ) methods return the filename and line number where the error occurred. They're what you would get if you captured the _ _FILE_ _ and _ _LINE_ _ constants at the location of the error. (Printing these constants inside the catch give you the current filename and line number inside the catch, not the name and number where the error actually took place.)

The getMessage( ) and getCode( ) methods provide a text description of the error and an error number. According to the DOM specification, trying to create an element with an illegal name must generate an invalid character error, which has an error code of 5.

The Exception class also provides access to a backtrace of the current working environment at the time of the error. Access it through getTraceAsString( ). Since the code in Example 7-5 lives in the main scope, it's not too exciting or useful:

#0 {main}

There is also getTrace( ), which returns the same information as getTraceAsString( ) but with each line as an element in an array. Backtraces and their format are the topic of the last section of this chapter.

As you've seen, DOM actually throws a DOMException instead of a regular Exception. A DOMException is a subclass of the base Exception class. It doesn't contain any additional methods or properties, but it lets you easily differentiate DOM errors from errors thrown by other extensions.

Unlike Java, PHP does not support the finally keyword. The finally block designates a region of code that's always run, regardless of whether there's an exception. It's used to close open connections and release locked files. The solution is to place as much cleanup code inside your objects' destructors and handle the remaining details (if any) inside the catch block.