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.

By name, people often think of underflow and overflow as mathematical overflows; you did some addition and overflowed the size of an integer, for example. However, their definitions and usage are quite different.

UnderflowException is really defined as an exception that occurs when you call a method on an object that can not be used because the object is 'empty'. Example: calling pop on an empty stack.

OverflowException is really defined as an exception that occurs when you call a method on an object that can not be used because the object is 'full'. Example: attempting to add another index in an SplFixedArray.

I propose that we create three new exceptions:

• StateException extends RuntimeException
  • EmptyException extends StateException
  • FullException extends StateException

This provides a general state exception for users to use (this has been requested). It additionally provides the semantic meaning of the current OverflowException and UnderflowException. We would then have OverflowException be an alias of FullException and UnderflowException be an alias of EmptyException. We may consider deprecating Overflow and Underflow exceptions. These measures are fully BC (unless there are bugs with aliases and exceptions, but simple tests I conducted showed expected behavior).

A WIP for the state exceptions: https://github.com/morrisonlevi/php-src/tree/StateExceptions