This is an old revision of the document!
SPL Improvements: Exceptions
- Version: 1.0
- Date: 2012-02-24
- Author: Levi Morrison levim@php.net
- Status: Work-in-progress
- Special thanks: NikiC, ircmaxell
Introduction
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.
Problems
General Documentation Issues
- There are no examples that show when to throw the specific exception. Dawid Krysiak lamented this in a comment.
- Descriptions are too short.
Logic and Runtime Exceptions
What is a LogicException?
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:
What is a RuntimeEexception?
A RuntimeException is currently documented as: “Exception thrown if an error which can only be found on runtime occurs.”
Known subclasses:
OutOfRange and OutOfBounds
Domain and Range
InvalidArgument
Proposed Solutions
Provide Inheritance Hierarchies
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.
Provide Examples
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.