rfc:spl-improvements:exceptions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:spl-improvements:exceptions [2012/02/24 21:01] – [Provide Examples from the SPL] levimrfc:spl-improvements:exceptions [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 4: Line 4:
   * Author: Levi Morrison <levim@php.net>   * Author: Levi Morrison <levim@php.net>
   * Status: Work-in-progress   * Status: Work-in-progress
-  * Special thanks: NikiC, ircmaxell+  * Special thanks: NikiC, Anthony Ferrara
  
 ===== Introduction ===== ===== Introduction =====
Line 12: Line 12:
 ===== Problems ===== ===== Problems =====
  
-==== General Documentation Issues ====+==== UnderflowException and OverflowException ====
  
-  * There are no examples that show when to throw the specific exception. [[http://www.php.net/manual/en/spl.exceptions.php#102226|Dawid Krysiak lamented this in a comment]]. +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.
-  * Descriptions are too short. +
-==== Logic and Runtime Exceptions ====+
  
-=== What is a LogicException? ===+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.
  
-A LogicException is currently documented as: +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.
-"Exception that represents error in the program logic. This kind of exceptions should directly lead to a fix in your code."+
  
-**Known subclasses:** +I propose that we create three new exceptions:
-  * [[http://www.php.net/manual/en/class.badfunctioncallexception.php|BadFunctionCallException]] +
-  * [[http://www.php.net/manual/en/class.domainexception.php|DomainException]] +
-  * [[http://www.php.net/manual/en/class.invalidargumentexception.php|InvalidArgumentException]] +
-  * [[http://www.php.net/manual/en/class.lengthexception.php|LengthException]] +
-  * [[http://www.php.net/manual/en/class.outofrangeexception.php|OutOfRangeException]]+
  
 +  * 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).
  
-=== What is a RuntimeEexception? ===+===== Patches =====
  
-A RuntimeException is currently documented as: +A WIP for the state exceptions: https://github.com/morrisonlevi/php-src/tree/StateExceptions
-"Exception thrown if an error which can only be found on runtime occurs." +
- +
-**Known subclasses:** +
-  * [[http://www.php.net/manual/en/class.outofboundsexception.php|OutOfBoundsException]] +
-  * [[http://www.php.net/manual/en/class.overflowexception.php|OverflowException]] +
-  * [[http://www.php.net/manual/en/class.rangeexception.php|RangeException]] +
-  * [[http://www.php.net/manual/en/class.underflowexception.php|UnderflowException]] +
-  * [[http://www.php.net/manual/en/class.unexpectedvalueexception.php|UnexpectedValueException]] +
-==== OutOfRange and OutOfBounds ==== +
- +
-==== Domain and Range ==== +
- +
-==== InvalidArgument ==== +
- +
-===== Proposed Solutions ===== +
- +
-==== Provide Inheritance Hierarchies ==== +
- +
-In the [[http://www.php.net/manual/en/spl.exceptions.php|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, [[http://us3.php.net/manual/en/spl.exceptions.php#102226|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.+
rfc/spl-improvements/exceptions.1330117270.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools