PHP Exception Handling - ErrorException

PHP Exception Handling – ErrorException

Moving along through our detailed PHP Exception Handling series, today we’ll dive into the PHP ErrorException class. In the most basic sense, the PHP ErrorException is meant to be explicitly thrown when you want to catch and handle errors that would otherwise be ignored, such as Notices or Warnings.

In this article we’ll explore the ErrorException in a bit more detail by first looking at where it resides in the PHP Exception Hierarchy. We’ll also take a look at a number of different scenarios that combine various error_handling severity levels with custom error handler functions, to see how ErrorExceptions are typically caught and thrown, so let’s get going!

The Technical Rundown

  • All PHP errors implement the Throwable interface, or are extended from another inherited class therein.
  • Exception implements the Throwable interface.
  • ErrorException extends the Exception class.

When Should You Use It?

As mentioned in the introduction, the ErrorException class can be used when an exception should be created (and handled) as if it were a normal Exception-inherited class object. One possible scenario is when PHP issues a Warning. During execution, PHP will effectively ignore Warnings and continue execution as normal, depending on how the code is configured to handle errors. However, this may not always be desirable, as oftentimes a Warning is an indication of a failure that should redirect current script execution, if not halt the script entirely (as a fatal error would normally do).

For example, consider trying to access a file via the file_get_contents(string $filename) function. As indicated by the documentation, “an E_WARNING level error is generated if filename cannot be found, maxlength is less than zero, or if seeking to the specified offset in the stream fails.” The function itself also returns a false boolean value if reading the data/file failed for some reason. Here we’ll try to access an invalid file:

Which produces the following default output to the console (without halting execution):

In this situation, we want to actually produce an Exception, as opposed to just a Warning, when the passed file path cannot be found. Therefore, we need to make use of ErrorException. Below is the full code sample. Following this code we’ll break down the functions and logic to see exactly what’s going on and how ErrorExceptions can be used in various error handling scenarios:

For these examples we’ll stick with the file_get_contents() method. We want to react to the Warnings it produces by throwing and catching an ErrorException, when appropriate. So, we begin with the getFileContents(string $path) function, which is a simple wrapper for file_get_contents() and some basic error handling:

We’re going to make use of the built-in set_error_handler() function, which allows us to set a user-defined error handling function. We’ve specified two different error handler functions to serve this purpose — one that checks if the current error_reporting level allows the passed error to be handled, and the other, which ignores the error_reporting configuration entirely. In both cases, we ensure that our error handler throws a new ErrorException and passes the original values to it, so we can use this in the try-catch blocks elsewhere in the code:

We then combine these calls within the accessInvalidFile($errorLevel, $handlerFunc = null) method, which configures the error_handling level and sets the error handler function (if applicable), before calling getFileContents(string $path) with an invalid file name passed in:

With everything setup we can call accessInvalidFile() with assorted error reporting levels and handler functions passed to it, and see how changes here alter the behavior of our invalid file retrieval attempt:

As you can see, we’re calling accessInvalidFile() for each of the three most common error_reporting levels: E_ERROR, E_WARNING, and E_NOTICE. Within each error reporting level we also make a call with no error handler, a call with a basic error handler, and then a call with the advanced handler that checks against error_reporting severity levels.

The goal here is to see how these different configurations affect the output that PHP produces when a Warning occurs. We begin with the output set using an E_ERROR reporting level:

The first thing to notice is that, without an error handler function specified, no output is produced. This makes sense, since we’re not including the E_WARNING reporting level flag, so the Warning that is created is ignored.

On the other hand, the basic error handler does grab the Warning and convert it into a thrown ErrorException, which we’re then able to catch. However, since the advanced error handler checks if error_reporting is configured to handle the E_WARNING severity level of the passed error, no ErrorException is thrown during the final call.

Next let’s look at the E_WARNING outputs:

It shouldn’t come as much surprise that all three of the E_WARNING reporting level calls produce an output. Since the underlying error is itself a Warning, the call without an error handler just passes along that Warning to the console. Meanwhile, the basic error handler works as we saw before, while the advanced handler confirms that the E_WARNING flag passed to error_reporting is equivalent to the error’s severity level, so it also throws an exception.

Finally, we have the E_NOTICE call outputs:

These are identical to the outputs from E_ERROR calls, since the logic is the same: The Warning doesn’t qualify as an E_NOTICE, so there’s no match for the advanced error handler, nor the non-error handler call.

Check out the Airbrake-PHP library, designed to quickly and easily integrate into any PHP project, giving you and your team access to real-time error monitoring and reporting throughout your application’s entire life cycle. With automatic, instantaneous error and exception notifications at your fingertips, you’ll be constantly aware of your application’s health, including any issues that may arise. Best of all, with Airbrake’s robust web dashboard cataloging every error that occurs, you and your team can immediately dive into the exact details of what went wrong, making it easy to quickly recognize and resolve problems.