Creating a custom error handler in PHP
To get the terminology straight, we talk about errors being “triggered”, whereas exceptions are “thrown”. The ability to throw and catch exceptions is new to PHP 5, but error handling has been around since PHP 4. In other object-oriented languages, there isn’t really a meaningful difference between errors and exceptions, but the distinction is very important in PHP. Errors can either be catchable or uncatchable, depending on how they’re triggered. Although you can trigger custom errors within your code if the need arises, errors are more commonly triggered by the parser or the PHP engine itself. Exceptions, on the other hand, are always thrown by actual PHP code, and not the underlying engine.
Let’s look at errors that can’t be caught. Parsing errors, the sort that happen when we forget to end a line with a semicolon or put one too many or few braces into our code, these aren’t going to trigger your custom handler function. The code just won’t work. In addition, errors that are thrown by the core, such as memory errors, or errors that can occur during startup, can’t be caught either. And lastly there are some errors, the ones of type ‘E_ERROR’ that just can’t be caught.
In order to handle errors, first you’ll need to create an error-handler function. The function takes 5 arguments, of which 2 are required and the rest are optional.
{show function syntax}
If you want the internal error handler to take over, for instance if your error handler is built to deal with just a few very particular cases, and based on the arguments passed, it’s been called for something different, then just return ‘false’. The internal handler will take over and execution will proceed as if your handler function weren’t there.
Here’s an example error handler:
{code sample}
The biggest change in custom error handling with PHP 5 is that you can now specify the type of error your handler function is intended to deal with, as opposed to just a catch-all for any error that a handler can deal with. This is helpful for dealing with the fact that, once you set a custom error-handler, the error_reporting setting inside php.ini will be ignored, and the custom function will be called for any reportable error type except E_STRICT. However, in PHP 6, E_STRICT will be included by default as well.
Even though the value of the error_reporting configuration isn’t checked before calling a custom error handler, you can still check the setting by calling error_reporting() with no arguments, and then have your own error handler function act appropriately based on that setting. On a related note, if the error-suppression character ‘@’ is placed at the beginning of the statement which triggered the actual error, the value of error_reporting will be 0 (or E_NONE) when checked.
Here’s a custom error_handler that takes the reporting level into consideration:
{code sample}
If you want to have an error handler that will handle any catchable errors in your code, you’ll need to set it near the beginning of your script. Up until the set_error_handler function is called, the default is the only one that gets called.
Let’s look at how this actually works. The following code will trigger an error because … … With the default error handler, the script will output this fairly unhelpful message {show broken page}.
Now, if we instead register this custom error handler function we looked at before
{show code example}
what we get instead is {show helpful error report}
A handy corollary to creating a custom error-handler function is the ability to trigger your own errors in your code. This capability is far less important in PHP 5 with the advent of exception-handling, but it’s still worth looking at.
The syntax is very simple. You just call ‘trigger_error’ with a message and, optionally, an error level. By default, it uses ‘E_USER_NOTICE’.
Here’s the previous example, but using ‘trigger_error’ instead of causing an error normally.
{code sample}
{show output}
Now, if you use exceptions in your code, and somehow have an exception that isn’t caught in a catch block somewhere, this also causes a catchable fatal error. However, rather than rely on setting a custom error handler, since exceptions provide different, and potentially useful debugging information, PHP allows you to set a custom exception handler that only gets called when an exception goes uncaught.
It has a pretty similar syntax to set_error_handler, except that the exception-handler function takes different arguments. Here’s how the function syntax is defined:
{code sample}
And here’s an example of using the custom handler to deal with an uncaught exception:
{code sample}
{show output}
January 16 2010 03:12 pm | Schmategories