php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #63125 Wrong Example of Class ErrorException
Submitted: 2012-09-21 05:50 UTC Modified: 2012-09-22 09:26 UTC
From: xianrenb at gmail dot com Assigned:
Status: Not a bug Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2012-09-21 05:50 UTC] xianrenb at gmail dot com
Description:
------------
---
From manual page: http://www.php.net/class.errorexception
---
I believe the example in the manual page as at Sep 21, 2012 is wrong:
1. According to the manual page of set_error_handler(), $errno contains 
the level of the error raised, as an integer. This is the same meaning 
as $severity of class ErrorException.
2. Class ErrorException has property $severity, but class Exception does 
not have the same property. It only makes sense if $severity is set to 
something useful (non-zero), and related to error.
3. $severity has a default value of 1, which is the same value as 
E_ERROR, while $code has a default value of 0.
4. Most notes contributed by other PHP users, if not all, use 
ErrorException in the same way as in the expected result suggested.

Expected result:
----------------
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:
--------------
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-21 10:30 UTC] googleguy@php.net
To address your concerns in order:

1. The phrase "error level" throughout the PHP documentation is ubiquitous with E_* error 
constants, as in E_ALL, E_ERROR, E_PARSE, E_STRICT, etc... The error handler expects this 
value as an integer. So for example an E_ERROR constant has an integer value of 1, whereas 
an E_STRICT may have an integer value of 2048 (depending on which version of PHP you're 
using). These integer values, however, do not necessarily depict the "severity" of an 
error. At least not in any obvious way, in terms of their value.

For example, E_STRICT has a larger integer value than E_USER_ERROR and even E_PARSE. This 
doesn't mean E_STRICT is necessarily more severe than E_PARSE. If anything an E_PARSE 
error is very severe since it's fatal where as an E_USER_ERROR is not. These error level 
constants have values that are meaningful to the PHP error handler, and not necessarily 
going to be meaningful to your Exception handler.

2. As for this it's completely up to you what you set $severity or $code to in your 
ErrorException class. Here the documentation is just passing the $errorno from the error 
handler to the $code property in the ErrorException class in the event you'd like to use 
it in your Exception handler. As you pointed out Exception Class does not have a $severity 
property, but it does have a $code property that can carry error codes. Here the idea 
would be to set $severity to something for what would normally translate to fatal errors 
and probably not set it for non-fatal errors like E_NOTICE, E_WARNING, etc..

3. By default all Exceptions are fatal unless caught. It's still up to you to decide 
whether or not you'd like your Exception to carry a severity that is a 1:1 translation of 
the error code passed from the error handler. This is not a requirement since it doesn't 
actually end up affecting the behavior of ErrorException.

4. This doesn't mean there is a bug in the documentation.

Thanks
 [2012-09-21 10:32 UTC] googleguy@php.net
-Status: Open +Status: Not a bug
 [2012-09-21 10:32 UTC] googleguy@php.net
Closing for now.
 [2012-09-22 01:52 UTC] xianrenb at gmail dot com
I would like to respond to the reply
[2012-09-21 10:30 UTC] googleguy@php.net:
1. No matter whether E_* values depicts the severity of an error, the 
default value of $severity is 1, and it is equal to value E_ERROR. One 
user may use the E_* values to represent the severity of an error, as 
many note contributors do. If one user wants to use another system to 
represent the severity of an error, he may choose to do so. However, 
$severity should not be a constant for all kinds of errors.
2. If E_* values are not related to severity of an error, how could
one determine the severity of an error by using set_error_handler() 
(without class ErrorException)? It is clear that E_* values are
closely related to severity of an error.
3. Do you mean that it is a wrong decision to introduce $severity in 
class ErrorException? If one have to use the class in a custom way, he 
could simply extend it and add any property he wants. Class 
ErrorException is not a custom class. Propery $severity should be 
closely related to error. Setting it with a value of 0 simply means 
$severity is not related to error. It would be misleading to use such
an example.
4. It is clear that the default value of $severity is 1, but not 0.
What is the meaning of setting a zero value in the example, while the 
default value is 1? If one could explain, it should be stated in the 
documentation as well.
5. Do you mean both versions would be ok as an example? I don't think 
so. If I could leave my comments on the manual page, I think most 
PHP users would buy my idea. People reading the documentation would 
simply have a question why my version and most users' contributions
are different from the example in the manual.
 [2012-09-22 09:26 UTC] googleguy@php.net
The fact that the default value of $severity in ErrorException class happens to 
be equal to the 
integer value of E_ERROR is merely coincidental.

You may feel free to set the $severity property of ErrorException to whichever 
value you'd like 
if that suits your needs. You may feel free to provide examples in the user 
contributed notes 
that demonstrates something you feel the documentation is lacking.

However, submitting a note that states the documentation is incorrect to set 
$severity to 
something other than the $errno returned by the error_handler is what will be 
misleading.

I'll be happy to change the example to use the default value of 1 for the 
$severity property, but 
your note was deleted because it states that the documentation is providing 
information which 
would contradict some underlying behavior in the ErrorException class, which is 
not true and as 
such the note was removed.

If other users would like to provide examples that happen to set the $severity 
property to some 
other value than the one provided in the example on the documentation page that 
is completely 
optional. The point of user contributed notes is to fill in the gaps where the 
documentation is 
lacking and in this case the documentation isn't really lacking anything in that 
example.

This would be the equivalent of contributing a user note that states the example 
on the Exception 
Class page is wrong because sets the $message property of Exception to "Error" 
instead of 
"Exception". This property is for the user-space code to set/handle. It doesn't 
affect the actual 
behavior of the class in both cases and it is, after all, just an example. 
Surely everyone can 
come up with a number of examples to use the same class in many many different 
ways and there are 
only so many examples necessary in the documentation itself. Which is why we 
have user 
contributed notes.


Cheers! :)
 [2012-09-24 00:55 UTC] xianrenb at gmail dot com
I would like to respond to the reply
[2012-09-22 09:26 UTC] googleguy@php.net:

I have checked the source code (as at Sep 23, 2012),
https://github.com/php/php-src/blob/master/Zend/zend_exceptions.c
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;

It is clear that my points are correct: $severity has a default value
of E_ERROR.

I would strongly recommend changing the example, as well as the
default value of the $severity parameter in the contructor of the
class ErrorException to E_ERROR instead of 1 to avoid any future
confusion.
 [2012-09-24 01:05 UTC] xianrenb at gmail dot com
And, I would strongly recommend changing the example of 
ErrorException::getSeverity() in the manual page. The method should 
return a E_* value.
 
PHP Copyright © 2001-2020 The PHP Group
All rights reserved.
Last updated: Mon Mar 30 13:01:25 2020 UTC