OutOfRangeException vs. OutOfBoundsException

Question

PHP defines two SPL exceptions for invalid keys:

OutOfRangeException: Exception thrown when an illegal index was requested. This represents errors that should be detected at compile time.

OutOfBoundsException: Exception thrown if a value is not a valid key. This represents errors that cannot be detected at compile time.

As PHP isn't a compiled language the distinction between compile-time and run-time seems strange and thus I am finding it hard to understand which exception to use when.

Currently my understanding is that one should throw...
... OutOfRangeException if the key is fundamentally and inherently malformed, e.g. if an array is passed as a key.
... OutOfBoundsException if the key is generally okay, but isn't in some boundaries, e.g. if 100 is passed but 50 is the maximum key.

Is that understanding correct?

Answer 1

While PHP doesn't have a classic "compile time" (or a compiler that do a lot of static checks for that matter) I'd treat "compile time" as "rather static stuff I did wrong when writing the code" and "run time" as "my logic, input or validation was off at some point".

So my suggestion would be to treat it like this:

"Compile Time" / "OutOfRangeException": The error can always be fixed in the source code without or with very little logic.

I always take numbers from 1-10 and you put in 11

---

"Run Time" / "OutOfBoundsException": The error is due to wrong use at runtime.

You created me and told me to take values from 1 to 5 then you put in 7. Doesn't compute

or

You request an index that is not there because you didn't put it there like you should

---

Sample:

I'd expect an SplFixedArray to throw an OutOfBoundsException because it's size is dynamic and can chance at runtime while I'd expect something like a Calender::getMonthName to throw and OutOfRangeException because the number of month are definitely fixed at "compile/write" time.

Array object sample:

Say $array is an object that implements ArrayAccess you could throw an OutOfBoundsException in these circumstances:

$array['bar'];
$array[7];

As the values are what you could expect for ArrayAccess but it doesn't make sense in the case of an SplFixedArray(5). Alternatives would be DomainException or maybe RangeException

An OutOfRangeException in these cases:

$calendar->getMonth(15);

As putting an array or a new class there is definitely some bigger logic flaw in the code that usually results from a simple "oh, i put in the wrong variable" error by a programmer. An (maybe preferable) alternative would be UnexpectedValueException and good old InvalidArgumentException.

For cases like:

$array[array()];
$array[new StdClass];

some of the alternative exceptions seem more fitting.

Comparisons with the Java world on which exception to use when are not always applicable as Java Developers have an additions issue to deal with.

Checked/Unchecked exceptions. With many people arguing that everything that isn't a runtime exception has very limited use in Java / should not be used much internally) those names have lost some of their original meaning and intent.

Answer 2

My own take on this is:

LogicException

use for any mistakes the developer did, e.g. mistakes when programming/assembling the application. Those will hopefully be catched when the developer is running his/her UnitTests (which would then be the equivalent of Compile Time). Those exceptions should never occur on the production site as they are errors in the software as such.

RuntimeException:

use for any mistakes the user did or that result from invalid data put in the application at runtime. These are errors that might be anticipatable but not fully preventable by UnitTests, e.g. those can happen on a production site. Those exceptions could be stemming from incorrect usage or programming errors.

OutOfBounds

is IMO effectively what Wikipedia defines as Range of an Array in Range in Computer Programming, namely:

When an array is numerically indexed, its range is the upper and lower bound of the array. Depending on the environment, a warning, a fatal error, or unpredictable behavior will occur if the program attempts to access an array element that is outside the range.

In other words, when you have an array with indices [0,1,2] anything but [0,1,2] is out of bounds. Note that Bounds can also apply to other data types as well, e.g. trying to access the 7th character in a 5 character string would also be OutOfBounds.

OutOfRange:

this one is a tough cookie. In C++ OutOfRange is a generic exception extending LogicException (just like in PHP). I am not sure if the example given is easily translatable to PHP code though or my definition of Compile time above. Mainly because no one would first init a new Vector(10) and the immediately try to access it at(20).

In Java OutOfRange seems to refer to Range in the mathematical sense

The range of a function is the possible y values of a function that result when we substitute all the possible x-values into the function.

One reference I could find has it extending RuntimeException though, so I guess looking into other languages wont help to solve this mystery. There is also an open bug report about the SPL Exceptions in general, stating that

• OutOfRangeException (value is out of range) is LogicException, should be: RuntimeException

But if this is correct, then how is OutOfRange different from DomainException? And if your own definition is correct, then how is OutOfRange different from InvalidArgumentException?

To cut a long story short: I dont know what OutOfRangeException is supposed to be for.

Answer 3

The answer to your question is quite elusive to me also. However, here are some things to think about:

• If an array is passed in when we are expecting a valid array key, we also have InvalidArgumentException because it is not the proper argument type.
• We could also throw a DomainException because arrays are not in the domain for array keys.
• In php, you generally can't detect types at compile time because of late static binding. They purposefully delay binding of variables to runtime.

How I handle this situation:

• Throw an InvalidArgumentException if a variable is passed in to any function where it the argument is not the correct type. I still do this when working with arrays.
• Throw an InvalidArgumentException if null was passed in when it shouldn't be. This one really could be a lot of things because null isn't typed. To keep error code checking simple, I simply stick with the invalid argument.
• Throw OutOfBoundsException when an index is not in the correct range, just as you suggested.
• Throw BadFunctionCallException if a user-supplied function as a parameter does not have the correct form. If your structure inside is an array, it makes sense that they could pass in a function to modify it, so this comes up occasionally.

Generally, I can use just these three exceptions to represent all errors that occur outside of special resources (Network and database connections would be special resources). The third one seems to have been cropping up more often, but primarily I've just dealt with the former two.

Answer 4

It is quite simple:

OutOfRange mean "Your requested key is not within the index of a set defined in code."

OutOfBounds means "Your requested key is not within the index of a set defined by loaded configuration."