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: 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. Previous Comments: ------------------------------------------------------------------------ [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 ------------------------------------------------------------------------ [2012-09-21 05:50:27] 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(); ?> ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=63125&edit=1