php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #53806 RangeException and OutOfRangeException extend invalid classes
Submitted: 2011-01-21 21:25 UTC Modified: 2012-11-16 18:20 UTC
From: nightstorm at tlen dot pl Assigned: levim (profile)
Status: Closed Package: SPL related
PHP Version: 5.3.5 OS:
Private report: No CVE-ID: None
 [2011-01-21 21:25 UTC] nightstorm at tlen dot pl
Description:
------------
This is a rather minor problem. SPL defines two base exception classes: LogicException for reporting problems with various system/component/class/argument logic and RuntimeException for runtime problems. LogicException is extended by a number of classes:

- DomainException
- InvalidArgumentException
- LengthException (entered length is not a valid length)

RuntimeException is extended by:

- OutOfBoundsException (value out of bounds)
- UnexpectedValueException (value was not expected)
- OverflowException
- UnderflowException

As we see, the problems with tested values are classified as runtime exceptions, and problems with specifying constrains are classified as logic exceptions. However, this is not true in case of RangeException and OutOfRangeException, where the base classes are replaced:

- RangeException (constraint range is invalid) is RuntimeException, should be: LogicException*
- OutOfRangeException (value is out of range) is LogicException, should be: RuntimeException

* - Actually, the first version can be considered as runtime exception, too, if the user has to enter some range, but then it should be clearly pointed out in the documentation. However, the second exception is definitely wrong.

There can be also an issue that I misunderstood the documentation, but in this case the problem should be reclassified as a documentation problem, and concern providing more information about the semantically correct usage of the provided exceptions. Currently, the documentation provides only a single and often very abstract sentence which results in many misunderstandings - if you are interested, I can provide a translation of the discussion I've recently found to show that the way people are using and understanding these classes is very far away from authors' intentions.

So, to sum up: either these classes extend invalid base classes, or the documentation should be MUCH more precise here.

Test script:
---------------
<?php
// Assume we are sending the invalid age, i.e. "10"
try
{
   if($_POST['age'] < 13 || $_POST['age'] > 100)
   {
      throw new OutOfRangeException('The specified age is not within the accepted range 13 to 100 years.');
   }
}
catch(RuntimeException $exception)
{
   echo 'Oops, you entered wrong data. Please correct them!';
}
catch(LogicException $exception)
{
   echo 'There is a problem with the system. Please contact the administrator.';
}

Expected result:
----------------
Oops, you entered wrong data. Please correct them!

Actual result:
--------------
There is a problem with the system. Please contact the administrator.

Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2011-01-29 10:03 UTC] nightstorm at tlen dot pl
I looked more deeply at the problem. If we follow the descriptions in the official manual at docs.php.net, these classes extend invalid classes.

However, I noticed that the descriptions at docs.php.net are all completely wrong, after comparing them to the old documentation at http://www.php.net/~helly/php/ext/spl/ . Here, this documentation correctly describes, why RangeException extends RuntimeException, and OutOfRangeException - LogicException. So this is a documentation problem, and there is a different ticket started for it:

http://bugs.php.net/bug.php?id=53877
 [2012-11-16 18:20 UTC] levim@php.net
-Status: Open +Status: Closed -Type: Bug +Type: Documentation Problem -Assigned To: +Assigned To: levim
 [2012-11-16 18:20 UTC] levim@php.net
The ticket this links to has been fixed and closed.  Closing this one as well.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sat Apr 20 11:01:27 2024 UTC