PHP Exception Handling - ErrorException

PHP Exception Handling – DomainException

Next up in our in-depth PHP Exception Handling series we’ll be looking into the domain of the, well, DomainException. The specific scenarios in with a DomainException should be used are varied and somewhat debated, but the current best practice is to throw a DomainException when a value doesn’t adhere to the valid “data domain” of the given context.

In this article we’ll further explore what that means and how the DomainException is typically used by looking at some simple, functional code samples. We’ll also see where the DomainException sits within the PHP Exception Hierarchy. Without further ado, let the games begin!

The Technical Rundown

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?

Although it’s a bit dated at this point, an interesting discussion took place a few years back in the official PHP bug tracker specifically regarding the vagueness of DomainException's purpose. Even many contributing developers of the PHP codebase at the time weren’t entirely sure what the DomainException was intended to accomplish. As mentioned in the introduction, the best explanation at the time (and that persists in the documentation today) is that a DomainException should be thrown when a value is passed to a method that is outside the bounds or “domain” of that data type.

Critically, this scenario is subtlety, yet distinctly, different from when an InvalidArgumentException would be used. An InvalidArgumentException should be thrown when an argument is not of the proper type — for example, trying to pass a string as an argument that expects an int type instead.

Conversely, the DomainException is better suited to handling an argument that is of the proper type, but is otherwise outside of the valid, expected values. In other words, the value is not within the target “domain.”

To see how a DomainException might be used in real world code we have the Publication class, as seen below:

This class contains a few properties, but the critical components are the const PublicationTypes array and the setPublicationType(string $publicationType) method. The latter of these performs a basic logic check to determine if the passed $publicationType value is found within the valid list of PublicationTypes. If so, it sets the instance property value. However, if the passed type cannot be found in the list, a new DomainException is thrown indicating the problem. Again, this isn’t an appropriate scenario for an InvalidArgumentException because the type that was passed is valid (string). Instead, we’re throwing a DomainException because the value itself doesn’t meet our requirements (in this case, it’s missing from the valid types list).

To test this functionality out and make sure everything is working we have two functions, setValidPublicationType() and setInvalidPublicationType():

In the first function we’re using a valid PublicationType of digital. On the other hand, the second Publication call passed an invalid PublicationType of poem. The log output shows just what we expected: The first function behaves fine and the second throws a DomainException our way:

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.