Coding Horrors: PHP Exception Model

September 16, 2008 by Christoff Truter PHP   Coding Horrors  

PHP 5 introduced structured exception handling(try..catch) into its codebase a while ago and alongside it a new exception model, similar to those you'd find in other programming languages.

I've been using trycatches for many years in other languages like C#, Vb.net, Delphi, javascript and a few others, but find it a bit lacking in PHP. The whole idea is to wrap errors and throw an exception object in its place, which we can catch and handle gracefully.

Something that you can't count on with an out of the box PHP distro(maybe in PHP 6?), some functions and classes do this, some don't, others do it half heartedly (looking at you SimpleXML) - you essentially end up needing to cater for two exception models (the old and the new).

Consider the following code snippet:

try
{
	$handle = file_get_contents("somefile.txt");
}
catch(Exception $ex)
{
	echo "Something went wrong";
}

If somefile.txt doesn't exist, one would expect that the message "Something went wrong" would be displayed. Instead we find that our try..catch gets ignored (since its looking for a non existing exception object) and we end up with an ugly message like this:

Warning:  file_get_contents(somefile.txt) [<a href='function.file-get-contents'>function.file-get-contents</a>]: failed to open stream: No such file or directory in C:\xampp\htdocs\public\exc\index.php on line 120

Luckily there is a workaround to this issue; PHP allows us to set a custom error handler via the set_error_handler function, from there we can return the exception objects our try..catch blocks desires.

function error_handler($errno, $errstr, $errfile, $errline)
{
	throw new Exception($errstr, $errno);
}
set_error_handler('error_handler');

The set_error_handler supports bit-flags, so if you need to exclude any type of error to be handled like this, simply do like the following:

set_error_handler('error_handler', E_ALL^E_NOTICE);

Hooray now we've got everything throwing exceptions, provided that we include this code at the top of every page, but we're still not completely happy.

Its all good and well that we're getting an exception object, but we've got no idea what type of exceptions are being thrown. Ideally we'd like to have the following:

try
{
	$contents = file_get_contents("somefile.txt");
}
catch(IOException $ex)
{
	echo "Something went wrong with the file";
}
catch(Exception $ex)
{
	echo $ex;
}

Achieving this would require quite a bit more work, since majority of PHP functions simply throw the default exception type. Which means we need to write custom exceptions classes and the means to trigger them.

Instead of calling file_get_contents directly like in the example, one would create a wrapper class for handling files, which would throw custom exceptions. Alternatively one could attempt to parse error messages and throw exceptions via the global error handler (not all that great).

Have a look at the following example of what one can do, firstly our custom exception class (IOException) and then our wrapper class (File). Once we invoke File::ReadAllText("somefile.txt"), we receive an IOException, instead of the default exception type.

Notice the @ sign infront of the file_get_contents function, this tells PHP to suppress errors and not to display them. Also notice $php_errormsg, this is a variable available within scope of the current executing code, containing the last triggered error.

Note that $php_errormsg only gets created if "track_errors" is set to on in your configuration file or if we ini_set("track_errors","on") it before our executing code.

class IOException extends Exception
{
	public $fileName;
}

class File
{
	public static $fileName;

	private static function throwException($php_errormsg)
	{
		$customException = new IOException($php_errormsg);
		$customException->fileName = self::$fileName;
		throw $customException;
	}

	public static function ReadAllText($fileName)
	{
		self::$fileName = $fileName;
		return @file_get_contents($fileName)
			or self::throwException($php_errormsg);
	}
}

Obviously one should always try to avoid exceptions as far as possible and handle issues even before they happen. Certain exceptions still require very specific ways of how they might need to be handled however.

---

2009-08-15: Regarding the point I made here about creating different exception classes according to the type of exception.

The current way PHP implements exceptions (one exception to rule them all), one can fall into the trap where you swallow all exceptions - including the unforseen ones - that should have been unhandled and logically terminate execution of your script. (Since its unforseen, it can open your script up to all kinds of security issues, other issues etc)

Hence one would need specific exception types and avoid a catch-all and swallow all situation.