Introduction to PHP Exceptions

By Kevin Waterson

Contents

1. What are Exceptions
2. Getting started
3. Custom Exceptions
4. Multiple Exceptions
5. Re-throwing Exceptions
6. Program flow with Exceptions
7. Top Level Exception Handler
8. Error Codes
9. Summary

What are Exceptions.

With the advent of PHP 5 came the new OO model and a new Object Oriented approach of dealing with errors. Exceptions give us much better handling of errors an allow us to customize the behavior of our scripts when an error (Exception) is encountered. Previously PHP dealt with errors by having error flags from functions and the trigger_error() function. These were well and good for pre-php5 days but in the new OO environment we need greater control.

In all other phPro tutorials we have dealt with good clean code. In this tutorial we will dealing with problems and how to deal with them.

Getting started.

In its simplest form, exceptions are still quite powerful in that they allow us to catch errors where and when we want. In a more complex form Exception give us an alternative to the use of special error return codes to signal a function call failure. We can use them for each function of for a whole block of code. Lets dive in and see what the fuss is about. Lets create a file called exception.php...

The above code will produce an error like this:

The error is has occured because an exception has been thrown in the checkNum function, but has not been caught. All exceptions need to be caught or this error will occur. An exception is caught using a catch block. But first we need to try the code that throws the exception. So the order of things is:

Just remember, if you throw something, you have to catch it. Lets put it to the test with some valid code.

When accessed, the above code will produce output to the browser similar to this:

Lets step through the code and get a grip on what is happening. The function checkNum simply checks is a number is greater than 3. If it is not, and exception is thrown with an error message. Next we have a try { } block that makes a call to the checkNum() function. If the condition in the checkNum() function is not met, an exeption is thrown and will be caught in the first catch block. You may have more than one catch block. PHP will attempt to parse anything that appears in this code block until either an Exception is thrown or the end of the code block. Any code after an exception is thrown is not executed.

In the catch(){ } block, the code first echoes a line of text saying we have caught an exception, then the error message is contained in the call to $e->getMessage() method from the exception class. The error message is passed directly to the Exception class construct. When catching the thrown Exception, we assign the instance to a variable (object) for use in or code, and now we have an exception object containing our exception information. So, enough of the basics. As we follow this document, we will explore deeper...

Custom Exceptions

The Exception class, like most classes, can be extended to create our own custom exception classes. When a new class is based on a parent classAs PHP uses unified constructors and allows inheritence. So when the Exception class is extended, all the methods are available to use. Lets take it for a run using a class to check for an invalid email address based on a value returned from the filter_var() function.

The class above is essentially an exception class on its own. It has the single addition of the exceptionMessage() method that calls the Exception class methods getLine() and getFile() and getMessage(). As they are defined in the base class, the extended class *inherits* from it. Lets take it for a test drive.

Obviously the email address supplied is invalid and when the filter_var() function returns bool FALSE an exception is thrown to the customException class. The exception is thrown as would any normal exception. Even though the only arguement passed to the customException class is the $email variable, all the methods available to the parent Exception class are available, such as getMessage(), getLine() and getFile(). Because the PHP OO model includes unified constructors, when the $email variable is passed to the customException class, it is immediately available to the parent class. But this example shows only how to try, throw, and catch a single exception. There are time when we need more than this. Multiple exceptions can be thrown an caught also.

Multiple Exceptions

Multiple exceptions can take many forms. they can be in a multiple if/else blocks, in a switch, or nested. Yes, you can nest exceptions in multiple try{ } catch(){ } blocks. A script may need to check for multiple conditions and different messages returned. Program flow may also need to change if an exception is thrown. Lets see how we can nest an exception and check for different error conditions. The customException class need not change for this. This is what is meant in PHP as re-usable code. Here we see an example of using nested try{ } catch(){ } blocks.

In the above example, the colors of the errors have been made red or blue to easily discern which error has been thrown. The problem with this sort of code, or nested if/else blocks, is if the program calls for large amounts of validation, we end up with very deeply nested code which can become very clumsy to read and debug. A better option is simply to code smarter.Lets look at an option using only single if() blocks to check a condition.

The above coding style makes much better sense and is much easier to follow and to read. Two catch(){ } blocks have been used in this code, as the Exception implementation allows for multiples. Once again the errors are color coded and this time we see that PHP has successfully jumped to the correct catch(){ } block corresponding to the thrown error. In this case, the $email variable has the word *fish* in it and so a standard exception is thrown, and caught in the appropriate catch(){ } block. If the customException catch block was omitted, and only the base Exception catch block was available, the Exception would be handled there.

Re-throwing Exceptions

An exception may be re-thrown when you wish to govern program flow. If a condition is not met, and an exception is thrown, you may wish to handle it differently based on a second condition or you may wish to try and recover from the error. It is generally considered practice to hide system errors from users. Lets consider a simple database connection with PDO. Because PDO is so totally amazing, it has a built in exceptions. If an error occurs when trying to connect to the database an exception is thrown and must be caught. While an error from the database may be meaningful to the person coding the application, it has little or no relevance to the user. So the exception can be re-thrown with a nice friendly message that the user is more likely to understand. Eg: a failed PDO database error would look like this:
SQLSTATE[HY000] [14] unable to open database file
When re-throwing errors from lower levels such as this, the exception must be wrapped inside the one being thrown. If the exception is not wrapped and caught, it will continue to "bubble up" the stack until it finds a catch(){ } block to handle it. If no catch(){ } block is found, and uncaught exception error will result. The example below demonstrates how to properly re-throw an exception.

From the code above we see a PDO exception is thrown when we try to connect to a non-existant database. This exception is caught and re-thrown with the customException class that handles the error and gracefully exits. Any un-caught Exception should be considered an application bug.

Program Flow with Exceptions

Exceptions should not be used as a GOTO, even though they seem ideally suited for the purpose. A good exception implemtation means the code will work without any of the try{} catch{} blocks. The Exception class should only be used error conditions. Below is an example of incorrect Exception usage.

The script above throws the exception when a value is found in the foreach loop. This is an abuse of the Exceptions class as a simple break here would have done the same job cleanly. No error has occured, so no Exception should be thrown.

Top Level Exception Handler

A most amazing feature of PHP is the set_exception_handler() function. This little charmer takes care of un-caught exceptions in what amounts to a last chance to catch any previously uncaught Exceptions, ie: if any Exception is not caught in a catch(){} block. This function takes a callback exception_handler as its only arguement which must be defined before any call to it. The default_handler will take a single parameter that is Exception object that has been thrown. This script below shows the workings.

If you wanted to restore the default Exception handler, simple use the restore_exception_handler(); function. This could also be used if your current default handler was another custom Exception class. The Exception classes are held in a stack can be restored with the restore_exception_handler() function as shown here.

So, from the script above we see the declaration of two Exception handlers, one makes the error messags red, and the other makes them blue. This is perhaps an abuse of the Exception functionality but serves well to demonstrate changes in classes as they occur. The initial default handler is set to red. The a check is run to see if an $email variable is set. Try removing the $email variable or commenting it out to see it work. If the $email varible is set, the code continues and the default handler is set to the blue_default_handler. Then using the filter_var() function, the $email is tested for validity and if it fails, a blue message is shown. Try changing the value of the email to 1234 to see the results. Finally we see the use of restore_exception_handler(); which pops the stack and returns the default Exception handler to the red_default_handler. When any of these exceptions occur, code execution stops and control is passed to the handler. You notice at the bottom of the script above that the line
echo 'This is not executed';
is never executed. But.. what if we wish to continue with the script and execute code below the thrown exceptions? This is the default behavior of Exceptions. Once outside the catch(){ } block you are free to include whatever code you wish.

Output buffering is Off by default in php.ini so it will need to be turned on via ob_start(). We can begin output to the brower in the script and if an exception is thrown, still use header() to redirect based on the exception type.

Error Codes

As seen in the beginning of this document, the Exception class contains a getCode() method that will fetch an error code, this can useful as you can define your own error codes as well as your own error messages. This quick demonstration shows how.

The above code returns the line:
Error: 10
Well, big deal you say.. Ok, if we can define our own error codes, we can script based on thier value! The following script shows some of the possibilities.

The error code generated when we the Exception is thrown is used in the switch block to choose how the script will be have next. You can probably think up your own uses for generating codes.

Summary

The PHP Exceptions class can be a very useful and significant tool to aid in the reporting and handling of errors. There is also room for abuse of the class and it is hoped that this document will point out the failings of using them so.