SPL Improvements: Exceptions

• Version: 1.0
• Date: 2012-02-24
• Author: Levi Morrison levim@php.net
• Status: Work-in-progress
• Special thanks: NikiC, Anthony Ferrara

The exceptions defined in the SPL are not very well documented, and their meanings are unclear. This RFC covers known problems and provides some solutions.

• There are no examples that show when to throw the specific exception. Dawid Krysiak lamented this in a comment.
• Descriptions are too short.

A LogicException is currently documented as: “Exception that represents error in the program logic. This kind of exceptions should directly lead to a fix in your code.”

Known subclasses:

• BadFunctionCallException
• DomainException
• InvalidArgumentException
• LengthException
• OutOfRangeException

A RuntimeException is currently documented as: “Exception thrown if an error which can only be found on runtime occurs.”

Known subclasses:

• OutOfBoundsException
• OverflowException
• RangeException
• UnderflowException
• UnexpectedValueException

The name “OutOfRangeException” is misleading. It is mainly used within to the SPL to denote that you have given an incorrect index type. Its name implies that something is out of a defined range, such as the size of an array. That is what OutOfBoundsException was created for.

Consider the situation when you are overloading ArrayAccess to only allow strings for offsets. When a non-string offset is provide, what exception should be thrown? InvalidArgumentException doesn't make sense because you didn't seeming make a function call. The name OutOfRangeException implies that you specified an unknown value of the correct type, and so does OutOfBoundsException.

It is not always clear when each should be used. Consider the following situation where we define a function that does integer division:

function intDivide($dividend, $divisor) {
    //add error handling
 
    return $dividend / $divisor;
} 
 
intDivide(1, new StdClass()); // incorrect type
intDivide(1, 0); //correct type, incorrect value

The first error has to deal with incorrect type, and the second is a correct type but the value is not valid for division. These are clearly different errors. Which is a DomainException and which is an InvalidArgumentException? Are they both DomainExceptions? InvalidArgumentExceptions?

In the overview for SPL exceptions, the table of contents lists all of the exceptions defined in the SPL. This should be changed to list the exception hierarchy:

Exception
  LogicException
    BadFunctionCallException
      BadMethodCallException
    DomainException
    InvalidArgumentException
    LengthException
    OutOfRangeException
  RuntimeException
    OutOfBoundsException
    OverflowException
    RangeException
    UnderflowException
    UnexpectedValueException
    

Fortunately, Dawid Krysiak submitted it as a comment on 02 Feb 2011. It would be helpful to also list the subclasses of each exception on their individual pages.

Every exception needs an example of how to use it, giving preference to examples taken from the SPL data-structures. This will also increase the awareness of the SPL data-structures and where they throw exceptions.

DomainException should be used when a variable of the correct type has been provided but is not part of the defined data domain.

InvalidArgumentException should be used when a variable of the incorrect type has been provided in a function or a method. It should not be used when the type is correct but the value is not, nor should it be used when dealing with array indices.

Something needs to change here. Their names represent the same thing. Either:

• OutOfRangeException should be deprecated and should not be used. If something is the incorrect type, then range does not apply. If it is out of some defined boundaries, OutOfBoundsException should be used.
• OutOfBoundsException should be deprecated and should not be used. OutOfRangeException should now inherit from RuntimeException and be used when a value has a correct type but a value out of the specified range.