PHP exception handling

Arguably one of the best things to come out of PHP5 was its improved OO support. With OO comes easier separation of presentation, data, and business logic layers which leads to reusable code and better code management, amongst a host of others.

Example of an error

Exception handling appears daunting a first, but once you understand the concept it is very easy to use, and incredibly powerful. Let’s start off with an example of an error to demonstrate what we mean.

<?PHP
$a = Array("foo", "bar", "foobar");
$b = 10;
$c = $a + $b;
echo($c);

That small PHP block when parsed will produce the following error: Fatal error: Unsupported operand types in simple_php_error.php on line 5.

We get that error because we are trying to add an array data type to an integer data type. Since we can not possibly add them together, an error occurs. Although these are not the type of errors we will be dealing with via exception handling, they do give you an idea of why we would want to hide errors.

Why use exception handlers?

First and foremost it makes your applications far more professional. Users visiting your site do not want to be bombarded with error messages here, there and everywhere. Not only do they not want to see them, but inexperienced users could get confused—did they create the error themselves? Did they somehow brake the site? Oh dear, let’s quickly run away from this site!

By using exception handling we can catch these errors and deal with them how we choose. We could even hide them completely and just log them for you to observe and correct at a later date.

So who uses exception handling? Well, me for one. Not only me, but nearly ever other major PHP developer will rely upon them at some time in a project. So should you.

Alternatives to exception handling

There are several alternatives to exception handling, but each have their downfalls.

• error_reporting()
• The @ operator

error_reporting() is a function that tells the PHP engine what errors to display. Whilst in development stages, it is a good idea to have it set as E_ALL, and whilst in live stage, hide all the errors—after all, we don’t want them possibly knowing our database or file structure—that could become a security risk. The downfall of error_reporting() is that you can only show and hide the errors, you cannot handle them.

The @ operator suppresses any errors that may occur. You add it before a statement which could possibly cause an error, for instance:

<?PHP
@fopen('location/of/your/script.php', 'r+');

The downfalls of this operator is that it is greedy. By including the file via this method you will also be suppressing any errors within that file also. Whilst in development stages this is a very bad idea. If you have done this or rely upon it, give yourself a smack on the hand. The only realistic reason you should use the @ operator is when you are attempting to load files externally to your file system, or within try and catch statements.

The basic try and catch statement

We can handle errors by using a try and catch statement. We try and execute some code, and catch any errors which may occur. Let’s have a quick look at the basic syntax.

<?PHP
echo('<h1>Try and catch exercise</h1>');
 
try {
    throw new Exception('I do not want my password revealed!');
    echo('<p>My password is: php_is_great</p>');
} catch(Exception $e) {
    echo('<p>An error occurred: ' . $e -> getMessage() . '</p>');
}

When you run this, you will get the following:

<h1>Try and catch exercise</h1>
<p>An error occurred: I do not want my password revealed!</p>

You can see that line 6 is never executed because we threw an error—we told the PHP engine that an error had occurred on line 5. As the error occurred in a try statement, it will attempt to catch any errors. On line 5 we threw the exception Exception, but this could have been anything as long as we define it as a valid Exception class.

Creating our own exception classes

Let’s try a simple scenario where one needs a certain type of input, and will reject everything else. A simple example would be a cup of coffee. To make a refreshing cup, one needs to use boiling water, not cold water. Lets create a simple PHP class to simulate making a cup of coffee.

<?PHP
class Coffee
{
    private $waterTemperature = 0;
    private $poured = false;
 
    public function boilWater($temperature) {
        $this -> waterTemperature = $temperature;
    }
 
    public function pourWater() {
        $this -> poured = true;
        echo('Ahhh. A nice cup of coffee.');
    }
}
 
$myCoffee = new Coffee();
$myCoffee -> boilWater(10);
$myCoffee -> pourWater();

With this code, we are susceptible to a cold cup of coffee. At the moment we are only boiling the water to 10 degrees Celsius, which is nowhere near hot enough—we will be pouring ourselves a cold cup of coffee! So let’s make a few amendments so this tragedy will never arise.

<?PHP
class ColdWaterException extends Exception
{
    public function __construct($message) {
        parent::__construct($message, 0);
    }
 
    public function __toString() {
        echo('Error: ' . parent::getMessage());
    }
}
 
class Coffee
{
    private $waterTemperature = 0;
    private $minTemperature = 50;
 
    public function boilWater($temperature) {
        $this -> waterTemperature = $temperature;
    }
 
    public function pourWater() {
        try {
            $this -> checkTemperature();
            echo('Ahhh. A nice cup of coffee.');
        } catch(ColdWaterException $e) {
            $e -> __toString();
        }
    }
 
    private function checkTemperature() {
        if($this -> waterTemperature <= $this -> minTemperature) {
            throw new ColdWaterException('Water too cold.');
        }
    }
}
 
$myCoffee = new Coffee();
$myCoffee -> boilWater(49);
$myCoffee -> pourWater();

Explaining the code

As I said at the start, this may seem daunting. Read it through and try and understand what it is doing.

Read it through twice? Great. So, we first start off by creating the class ColdWaterException which will extend the Exception class. Try as you might, you will not be able to see the class in the above code. Why not? Well simply because it is built into PHP itself. All you need to know for now is that it is a good thing.

We have now created the custom exception class, extended the Exception class, so now it is time to populate it. As usual we will create the constructor method which will be called automatically when an instance is created. This takes one parameter called $message which is the error message we send. We call the parent::__construct() which does everything it needs to do in the Exception class which we don’t see.

So now the only thing left to do is to handle the error. This is where the function __toString() comes into play. The function is just to output the message you want to be seen, if any.

The Coffee class is quite similar to the original, with a few minor modifications. The first thing you might see is that there is another function, checkTemperature(). This function simply returns a ColdWaterException error if the temperature is below 50, since we want our coffee to be nice and hot. The pourWater() function uses the try and catch statement which we looked at earlier. If there is no exception then we echo out the success message, but if the statement has found a ColdWaterException then it will output the error message.

There are a few lines I would like to draw your attention to:

• Line 26: notice that we use the name of the Exception we threw, not just Exception. We also set the error object to $e which we make use of on the following line.
• Line 33: the most important line in the script. This is where we tell PHP that an exception has occurred.
• Line 39: this is the line where we set the temperature. To try this out on your own, try setting this to different values.

Conclusion

I am going to do the conclusion slightly different and actually go back to the first block of code and explain why we didn’t use exception handling on it. Let’s first recap on the code:

<?PHP
$a = Array("foo", "bar", "foobar");
$b = 10;
$c = $a + $b;
echo($c);

We can make this code parse by adding five extra characters. All we need to do it tell PHP that $a is an integer and not an array. “Ahh, of course” I can hear you say, “… but how can we do that?”. The answer is type casting. Type casting requires that you put the name of the data type you want to turn the value into at the start in brackets. Let’s look at it in this example.

<?PHP
$a = Array("foo", "bar", "foobar");
$b = 10;
$c = (int)$a + $b;
echo($c);

Run this code and you will see the output as 11. That’s right, 11. Not 10. The reason is that $a is not null, it contains a value, so it returns when cast as an integer the value 1. The reason for this small example is just to let you know that exception handling shouldn’t be used every time a error might occur—there are sometimes better ways.