rfc:spl-improvements:exceptions
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
rfc:spl-improvements:exceptions [2012/02/24 23:14] – [Provide Examples] levim | rfc:spl-improvements:exceptions [2017/09/22 13:28] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
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:// | + | By name, people often think of underflow and overflow as mathematical overflows; you did some addition and overflowed |
- | * Descriptions | + | |
- | ==== Logic and Runtime Exceptions ==== | + | |
- | === What is a LogicException? | + | UnderflowException |
- | A LogicException | + | OverflowException |
- | " | + | |
- | **Known subclasses:** | + | I propose that we create three new exceptions: |
- | * [[http:// | + | |
- | * [[http:// | + | |
- | * [[http:// | + | |
- | * [[http:// | + | |
- | * [[http:// | + | |
+ | * 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 |
- | " | + | |
- | + | ||
- | **Known subclasses: | + | |
- | * [[http:// | + | |
- | * [[http:// | + | |
- | * [[http:// | + | |
- | * [[http:// | + | |
- | * [[http:// | + | |
- | ==== OutOfRange and OutOfBounds ==== | + | |
- | + | ||
- | The name " | + | |
- | + | ||
- | Consider | + | |
- | ==== Domain and InvalidArgument ==== | + | |
- | + | ||
- | It is not always clear when each should be used. Consider the following situation where we define a function that does integer division: | + | |
- | <code php> | + | |
- | function intDivide($dividend, | + | |
- | //add error handling | + | |
- | + | ||
- | return $dividend / $divisor; | + | |
- | } | + | |
- | + | ||
- | intDivide(1, | + | |
- | intDivide(1, | + | |
- | </ | + | |
- | 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? | + | |
- | ===== Proposed Solutions ===== | + | |
- | + | ||
- | ==== Provide Inheritance Hierarchies ==== | + | |
- | + | ||
- | In the [[http://www.php.net/manual/en/ | + | |
- | + | ||
- | Exception | + | |
- | LogicException | + | |
- | BadFunctionCallException | + | |
- | BadMethodCallException | + | |
- | DomainException | + | |
- | InvalidArgumentException | + | |
- | LengthException | + | |
- | OutOfRangeException | + | |
- | RuntimeException | + | |
- | OutOfBoundsException | + | |
- | OverflowException | + | |
- | RangeException | + | |
- | UnderflowException | + | |
- | UnexpectedValueException | + | |
- | + | ||
- | Fortunately, | + | |
- | ==== Provide Examples ==== | + | |
- | + | ||
- | Every exception needs an example of how to use it, giving preference to examples taken from the SPL data-structures. | + | |
- | + | ||
- | ==== Clarify Exception Usage ==== | + | |
- | + | ||
- | === DomainException === | + | |
- | + | ||
- | DomainException should be used when a variable of the correct type has been provided but is not part of the defined data domain. | + | |
- | + | ||
- | === InvalidArgumentException === | + | |
- | + | ||
- | InvalidArgumentException should be used when a variable of the incorrect type has been provided in a function or a method. | + | |
- | + | ||
- | === OutOfRangeException and OutOfBoundsException === | + | |
- | + | ||
- | Something needs to change here. Their name represent the same thing. | + | |
- | + | ||
- | * OutOfRangeException should be deprecated and should not be used. If something is the incorrect type, then range does not apply. | + | |
- | * 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. | + |
rfc/spl-improvements/exceptions.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1