Doc #63125 [Com]: Wrong Example of Class ErrorException

Edit report at https://bugs.php.net/bug.php?id=63125&edit=1 ID: 63125 Comment by: xianrenb at gmail dot com Reported by: xianrenb at gmail dot com Summary: Wrong Example of Class ErrorException Status: Not a bug Type: Documentation Problem Package: Documentation problem PHP Version: Irrelevant Block user comment: N Private report: N New Comment: And, I would strongly recommend changing the example of ErrorException::getSeverity() in the manual page. The method should return a E_* value. Previous Comments: ------------------------------------------------------------------------ [2012-09-24 00:55:03] 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-22 09:26:55] 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-22 01:52:58] 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-21 10:32:46] googleguy@php.net Closing for now. ------------------------------------------------------------------------ [2012-09-21 10:30:08] 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 ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at https://bugs.php.net/bug.php?id=63125 -- Edit this bug report at https://bugs.php.net/bug.php?id=63125&edit=1