PHP Exception Handling - ErrorException

PHP Exception Handling – RangeException

Moving along through our detailed PHP Exception Handling series, today we’ll be going over the RangeException. The RangeException is similar to the DomainException, which we covered previously. In essence, the DomainException is used when input values (such as method arguments) are invalid and don’t fit the context or domain of the current code. On the other hand, RangeExceptions are ideal when output values are invalid, or otherwise don’t make sense.

In this article we’ll examine the RangeException by first looking at where it resides in the overall PHP Exception Hierarchy. We’ll then take a look at some functional code samples that illustrate the difference between DomainExceptions and RangeExceptions, and show how RangeExceptions should be used in your own code, so let’s get to it!

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 we saw in our previous PHP Exception Handling – DomainException article, we integrated the DomainException into the input of a value called PublicationType for our Publication class. Specifically, when the setPublicationType(string $publicationType = null) method is called, if the $publicationType parameter isn’t a valid value, a new DomainException is thrown to indicate to the client that something needs to be changed.

To explore the RangeException, we’ve extended this example a bit by continuing with the Publication class, which extends the Book class:

In addition to the data checking within setPublicationType(string $publicationType = null), we now have data validation going on in the getPublicationType() method. Here, we ensure that the current value of the publicationType property is found within the Publication::PublicationTypes array and, if not, a new RangeException is thrown. As discussed in the introduction, this distinction between an input and an output value is what differentiates the use of DomainException from RangeException. In this case, we’re ensuring that the publicationType property value is valid before outputting it as a result of the getPublicationType() method.

To test this and show how RangeExceptions differ from DomainExceptions in practice, we have three test methods, starting with setValidPublicationDate():

Invoking this method works as expected, since the digital publicationType value is valid. The new Publication is created and output to the log:

Next we have the setInvalidPublicationType() method, which passes an invalid publicationType of poem to the setPublicationType(string $publicationType = null) method within the Publication class constructor:

As we saw earlier, since this invalid publicationType is an input value, we should expect a DomainException to be thrown, which is confirmed by the output we see:

Finally, let’s invoke the assignPublicationType() method, which initially sets a valid publicationType of novel, but then directly modifies the publicationType property to a value of epic, before trying to retrieve this now-invalid value via getPublicationType():

It’s worth noting that this specific example is somewhat contrived, because normally we’d have other defenses setup to combat direct modification of the publicationType property. For example, it would be set to private visibility (instead of its current public setting), which would normally force client code to use the setPublicationType(string $publicationType = null) method to make changes.

At any rate, directly changing the publicationType property and then trying to retrieve it throws a RangeException, as expected, indicating that that the output value we’re trying to retrieve is invalid:

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.