PHP: Making an exception

Gavin Sherry continues his exploration of what makes PHP 5 so special. This month it's exceptional.

In the time between this and my last column, PHP 5 has moved out of beta and into stable release, which means that you can now begin using PHP 5 in production with the confidence that it's supported and well tested. This month, I'll be looking at one of the very exciting new features in PHP 5 - exceptions.

Python vs. PHP: Choosing your next project's language

What are exceptions?

An exception is an error that occurs during the course of the execution of a script. When an error occurs in PHP 4, control is passed to the error handler, which outputs an error message to the user. A few months ago we looked at how to customise this error handling with set_error_handler(). The problem with this system is that you often need to code your scripts in such a way that you test for errors at each possible occurrence, swap error handlers around to match the code context you are in and more. This can be a nightmare, particularly if your application is being developed by more than one person, since you need to spend a lot of time getting the error handling right.

Object orientated languages such as Java, however, support an in-line mechanism which allows you to handle exceptions in a much more systematic way. This mechanism is to surround whole code blocks with an exception handler which is able to deal with any error in that block or, alternatively, pass it on to another exception handler. The way this is done can be seen in here:

01 try
02 {
03 /* code here */
04 }
05 catch(Exception $e)
06 {
07 /* recovery code */
08 }

Line 1 uses the try construct to instruct PHP that it should trap exceptions resulting from the execution of the code block which follows. If an exception occurs, control is passed to the catch block. This block is intended to allow the programmer to provide error recovery. If the catch block cannot resolve the error, it has the option of 're-throwing' the error. Consider the example below:

01 function test()
02 {
03 try
04 {
05 /* code */
06 }
07 catch(exception $e)
08 {
09 throw $e;
10 }
11 }
12 try
13 {
14 test();
15 }
16 catch(Exception $e)
17 {
18 /* recover here */
19 }

In this case, we have a function test(). The function tries to execute some code and if an exception occurs, control is passed to the catch block at line 07. We pretend that this catch block is unable to handle the error and we re-throw the error on line 09 using the 'throw' construct. We pass to this the exception itself: $e. By wrapping the call to test(), on line 14, in an exception block, we are able to catch the re-thrown error on line 16 and deal with it there.

Extending exceptions

In PHP 5, we can also extend exceptions. When dealing with a complex object-oriented project, you will want to be able to handle class specific exceptions. One of the most common places where this occurs is in dealing with databases, since errors encountered with the database are often completely unrelated to those in PHP - see here:

01 class SQLException extends Exception
02 {
03 var $state;
04 function _ _construct($SQLState)
05 {
06 $state = $SQLState;
07 }
08 function state2msg()
09 }
10 /* map SQLState code to message */
11 }
12 }
13 function runsql($sql)
14 {
15 /* prepare and send SQL query */
16 if($sqlstate)
17 throw new SQLException($sqlstate);
18 }
19 try
20 {
21 /* code, including runsql() */
22 }
23 catch(SQLException $e)
24 {
25 ech $e->state2msg();
26 }
27 catch($e)
28 {
29 /* Catch all axceptions */
30 }

We now have a very sophisticated exception handling frame work. On line 01, we declare a class SQLException which extends the Exception class which is built into PHP 5. We declare on line 04 a constructor which saves the SQLState passed in at object creation time. We declare on line 08 a function which will map the numeric error code sent from our database into a user friendly message. On line 13 we create a function, runsql(), which can execute an SQL query on a database server. If it encounters an error on line 16, we throw an exception (line 17) being careful to pass in the SQL error code, $sqlstate.

In our main code body, starting at line 19, we run some code, including runsql(), in a try block. If an ex­-ception is generated by runsql(), or some other function which is able to throw an exception of type SQLException, then we catch it at line 23. We then call the state2msg() method of SQLException and tell the user the error we've encountered. We're also careful on line 27 to catch any other exceptions which are not of the type SQLException.