php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #63157 Wrong Documentation of Class ErrorException
Submitted: 2012-09-25 01:04 UTC Modified: 2015-01-16 20:18 UTC
Votes:1
Avg. Score:5.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: xianrenb at gmail dot com Assigned:
Status: Duplicate Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2012-09-25 01:04 UTC] xianrenb at gmail dot com
Description:
------------
---
From manual page: http://www.php.net/class.errorexception
---
I think doc bug #63125 (https://bugs.php.net/bug.php?id=63125) was 
closed as "Not a bug" without proper reasons, so I have to open a new 
bug.
Please see the comments I made in the above bug report.
I think the documentation should match the source code, as in 
https://github.com/php/php-src/blob/master/Zend/zend_exceptions.c (24 
Sep, 2012), 
lines 221~228:
/* {{{ proto ErrorException::__construct(string message, int code, int 
severity [, string filename [, int lineno [, Exception previous]]])
   ErrorException constructor */
ZEND_METHOD(error_exception, __construct)
{
	char  *message = NULL, *filename = NULL;
	long   code = 0, severity = E_ERROR, lineno;
	zval  *object, *previous = NULL;
	int    argc = ZEND_NUM_ARGS(), message_len, filename_len;

Expected result:
----------------
Class synopsis documented as:
ErrorException extends Exception {
/* Properties */
protected int $severity ;
/* Methods */
public __construct ([ string $message = "" [, int $code = 0 [, int 
$severity = E_ERROR [, string $filename = __FILE__ [, int $lineno = 
__LINE__ [, Exception $previous = NULL ]]]]]] )
final public int getSeverity ( void )
/* Inherited methods */
final public string Exception::getMessage ( void )
final public Exception Exception::getPrevious ( void )
final public mixed Exception::getCode ( void )
final public string Exception::getFile ( void )
final public int Exception::getLine ( void )
final public array Exception::getTrace ( void )
final public string Exception::getTraceAsString ( void )
public string Exception::__toString ( void )
final private void Exception::__clone ( void )
}

Example documented as:
<?php
function exception_error_handler($errno, $errstr, $errfile, $errline ) {
    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
}
set_error_handler("exception_error_handler");

/* Trigger exception */
strpos();
?>


Actual result:
--------------
Class synopsis documented as:
ErrorException extends Exception {
/* Properties */
protected int $severity ;
/* Methods */
public __construct ([ string $message = "" [, int $code = 0 [, int 
$severity = 1 [, string $filename = __FILE__ [, int $lineno = __LINE__ 
[, Exception $previous = NULL ]]]]]] )
final public int getSeverity ( void )
/* Inherited methods */
final public string Exception::getMessage ( void )
final public Exception Exception::getPrevious ( void )
final public mixed Exception::getCode ( void )
final public string Exception::getFile ( void )
final public int Exception::getLine ( void )
final public array Exception::getTrace ( void )
final public string Exception::getTraceAsString ( void )
public string Exception::__toString ( void )
final private void Exception::__clone ( void )
}

Example documented as:
<?php
function exception_error_handler($errno, $errstr, $errfile, $errline ) {
    throw new ErrorException($errstr, $errno, 0, $errfile, $errline);
}
set_error_handler("exception_error_handler");

/* Trigger exception */
strpos();
?>


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2012-09-26 02:42 UTC] xianrenb at gmail dot com
One may believe an instance of class ErrorException with $severity
being 20 is more severe than another instance with $severity being 10, 
and argue that $severity of class ErrorException has nothing to do
with those error level constants, but I think this happens just
because the class is documented in a way that is not matching the
source code.

Please consider the case of using set_error_handler() without using 
class ErrorException. How could one determine the severity of an
error? The only solution is to compare the $errno with error level
constants, i.e. E_* values. These error level constants are built-in
constants provided by the PHP system. If one wants to use his own
system of determining the severity of an error, he has to define those 
constants somewhere. It is very clear that those are custom things,
and it is very strange to do so.

ErrorException is not a custom class. Anything dealing with it should 
use what the PHP system provides. In other words, it only makes sense
to use $severity of class ErrorException by comparing it with error 
level constants provided by the PHP system. And the source code says
the default value of $severity is E_ERROR.

It should be noted that larger value of $severity does not mean the 
error is more severe. The same thinking should apply to error level 
constants. However, $severity should represent the severity level of
an error, which could be determined by comparing $severity with error
level constants.
 [2013-01-20 01:10 UTC] xianrenb at gmail dot com
I think a related doc bug #63158 (https://bugs.php.net/bug.php?id=63158) was 
closed as "Not a bug" without a proper reason.
 [2015-01-16 18:12 UTC] danack@php.net
-Status: Open +Status: Feedback
 [2015-01-16 18:12 UTC] danack@php.net
Hi,

It is not clear what you are trying to report. Are you trying to say that the behaviour of the code is not good, or that the documentation does not reflect what the code does?


Also 'Actual result' vs 'expected result' is only useful for code examples. If you think the documentation needs changing, please just specify the words that need changing.



This code seems to be working fine and as expected for me:

<?php


try {
    throw new ErrorException("Exception message", 0, 75);
} catch(ErrorException $e) {
    echo "This exception severity is: " . $e->getSeverity() . "\n";
}

try {
    throw new ErrorException("Exception message", 0);
} catch(ErrorException $e) {
    if ($e->getSeverity() == E_ERROR) {
        echo "Severity was same value as E_ERROR.";
    }
}

// Output
// This exception severity is: 75
// Severity was same value as E_ERROR.
 [2015-01-16 20:18 UTC] salathe@php.net
-Status: Feedback +Status: Duplicate
 [2015-01-16 20:18 UTC] salathe@php.net
Marking as duplicate of the closed bug #66362

The history goes as follows:

 - 2008-04-14 Example added [1] using $errno for ErrorException::$severity property
 - 2012-07-19 Example changed to use $errno for for ErrorException::$code
 - 2012-09-21 Bug #63125 raised, requesting the example be changed back
 - 2012-09-21 Bug #63125 closed as "not a bug" by author of change from July
 - 2012-09-25 Bug #63157 (this bug!) raised instead of re-opening #63125
 - 2013-12-27 Bug #66362 raised addressing the same issue
 - 2013-12-29 Change from 2012-07-19 was reverted and #66362 closed
 - 2015-01-16 Bug #63157 (this bug!) closed as dupe of #66362 :)


[1] http://svn.php.net/viewvc?view=revision&revision=257500
 
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Mon Sep 27 23:03:36 2021 UTC