PHP Exception Handling - ErrorException

PHP Exception Handling – OverflowException

Moving along through our in-depth PHP Exception Handling series, today we’ll take a closer look at the OverflowException. Unlike most other languages, in PHP the OverflowException is not explicitly related to attempts to use memory space/addresses that are outside the bounds of the memory assigned to the application. Instead, the OverflowException in PHP is focused around a simple concept: Adding an element to a collection that is already full.

Throughout this article we’ll explore the OverflowException by looking at where it resides in the larger PHP Exception Hierarchy. We’ll also look at some fully functional sample code that will illustrate how OverflowExceptions might be used in your own PHP projects, 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 previously discussed, the purpose of the OverflowException — at least, as it pertains to PHP — is to alert the user or application that an element was added to a collection or container that doesn’t have space for that extra item. This could result in a memory overflow, which is the traditional meaning of "overflow" in most languages, but PHP has much broader limitations on what the OverflowException can indicate.

To illustrate, we start with the trusty Book class that we’ve been using in previous code samples.

Take particular notice of the const MAX_CHARACTER_COUNT = 5; statement, which indicates a limit on the allowable number of characters that can be added to a Book instance. Obviously, no such limitation can (or should) exist in reality, but for our example, this will serve nicely.

Now, the addCharacter(Character $character, $key = null) method does just what the name suggests by adding the passed Character parameter to the characters field. However, we want to limit the total allowed characters to five or fewer, so our code checks if the current maximum is reached or exceeded, in which case it throws a new OverflowException, which is the official purpose of this PHP exception:

You can probably guess where this is going. To test this out, we’ve created a new Book instance for The Name of the Wind (one of my personal all time favorites), then created a series of common Characters found throughout the book:

Having done that, we output the $book instance value to the log, to confirm all five initial characters were added:

Just as intended, all Characters were added to the $book object. However, let’s see what happens if we try to add Wilem, the sixth Character to the collection:

Unsurprisingly, this produces the OverflowException we intended, indicating that the number of characters cannot exceed our maximum setting of 5:

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.