PHP Exception Handling - ErrorException

PHP Exception Handling – OutOfRangeException

Travelling along through the deep undergrowth, in the PHP Exception Handling forest we’ve created, today we come to the lush meadow that is the OutOfRangeException. In spite of what you might suspect based on the name, the OutOfRangeException is not thrown when attempting to access an index outside the bounds of an array or other collection object. Instead, an OutOfRangeException is meant to be used for compile time issues, such as trying to access an object that doesn’t make logical sense in the context.

In this article we’ll dig into the OutOfRangeException a bit more, including where it resides in the overall PHP Exception Hierarchy. We’ll also look at some sample code that illustrates just one example of illogical “compile time” code that should cause a OutOfRangeException in the first place, so let’s get going!

The Technical Rundown

All PHP errors implement the Throwable interface, or are extended from another inherited class therein. The full exception hierarchy of this error is:

Full Code Sample

Below is the full code sample we’ll be using in this article. Feel free to use any or all of the code if you wish to follow along.

When Should You Use It?

As briefly discussed in the introduction, the official documentation states that the OutOfRangeException “represents errors that should be detected at compile time.” This presents challenges for many PHP developers, because PHP is an interpreted language (as opposed to a traditional compiled language). That’s not to say that PHP code doesn’t get “compiled” at some point prior to execution — the source code is translated from the written form into opcodes that can be interpreted and executed by the PHP program. However, for the sake of debugging and detecting errors “at compile time,” as the official documentation claims, that’s not something that can be easily accomplished.

Therefore, the interpretation of the OutOfRangeException we’ll be using in our code sample is that such errors should be thrown when indicating a logical fallacy in the code. For example, here we have our trusty little Book class we’ve seen in previous articles:

For the purpose of this exception tutorial we’ve added two new fields, publicationMonth and publicationYear, both of which are integer values. Normally we’d probably use a single publicationDate or publishedAt field that was a DateTime object or similar but, again, for the sake of this example, we’re using numeric values for our date.

Anyway, since we know that there are only twelve months in a year, it would be a illogical to allow a publicationMonth value that is outside the bounds of 1 through 12. Thus, we’ve added a bit of extra code to the setPublicationMonth(int $month) function to check that the passed parameter is within those bounds. If not, an OutOfRangeException is thrown:

To test this out we’ve created a few Books from a couple of cool trilogy series by author Robin Hobb, each with their associated publication month and years:

As expected, executing this code produces the output we’re after:

Uh oh! Everything was working fine until we got the last Book creation of Ship of Destiny. As the OutOfRangeException message indicates, the value we passed of 18 is outside the allowed bounds. This was probably a typo, since the actual publication month was August (or 8), instead.

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.