php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #53877 SPL exception definitions are too ambiguous
Submitted: 2011-01-29 09:54 UTC Modified: 2011-02-10 13:31 UTC
From: nightstorm at tlen dot pl Assigned: salathe (profile)
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2011-01-29 09:54 UTC] nightstorm at tlen dot pl
Description:
------------
The SPL exception definitions in the official manual are too ambiguous. As I talked to programmers, I noticed that many have problems with understanding, how to use them properly. Furthermore, the older documentation was more precise here and I think the authors should seriously consider writing something more about them.

Here's, what should be added:

LogicException:

 - Description: "Exception that represents error in the program logic. This kind of exceptions should directly leed to a fix in your code."
 - Source: copied from http://www.php.net/~helly/php/ext/spl/classLogicException.html

OutOfRangeException:

 - here, the description is completely wrong and makes no sense, if we look at the class diagram. According to docs.php.net, this class should extend RuntimeException, not LogicException.
 - Valid description: "Exception thrown when an illegal index was requested. This represents errors that should be detected at compile time."
 - Source: copied from http://www.php.net/~helly/php/ext/spl/classOutOfRangeException.html

RangeException:

 - identical case, as OutOfRangeException
 - Valid description: "Exception thrown to indicate range errors during program execution. Normally this means there was an arithmetic error other than under/overflow. This is the runtime version of DomainException."
 - Source: copied from http://www.php.net/~helly/php/ext/spl/classRangeException.html

OutOfBoundsException:

 - "This represents errors that cannot be detected at compile time." should be added, as it is in http://docs.php.net/manual/en/class.outofboundsexception.php

UnexpectedValue:

 - "Typically this happens when a function calls another function and espects the return value to be of a certain type or value not including arithmetic or buffer related errors." should be added, as it is in http://docs.php.net/manual/en/class.unexpectedvalueexception.php

LogicException:

 - The old documentation at http://www.php.net/~helly/php/ext/spl/ and the official one say two completely different things about this exception. Decide: does it mean that the specified length makes no sense (i.e. because it is negative, and length cannot be negative), or that some value has an invalid length, but then - why does it extend LogicException in this case? If it extends, it should be clarified that it should be only used on errors in the program logic, not to validate user data.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2011-01-29 14:24 UTC] salathe@php.net
-Assigned To: +Assigned To: salathe
 [2011-01-29 15:31 UTC] nightstorm at tlen dot pl
Small update: the last point concerns LengthException, not LogicException.
 [2011-02-10 13:31 UTC] vrana@php.net
-Status: Assigned +Status: Closed
 [2011-02-10 13:31 UTC] vrana@php.net
This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.


 [2011-02-10 13:31 UTC] vrana@php.net
Automatic comment from SVN on behalf of vrana
Revision: http://svn.php.net/viewvc/?view=revision&revision=308184
Log: Improve SPL exceptions (doc bug #53877)
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Thu Apr 25 23:01:29 2024 UTC