/bundle/PIV/doc/set-error-handler.txt
Plain Text | 208 lines | 168 code | 40 blank | 0 comment | 0 complexity | 8efcb214dfdbf3f17afb1e62f83599e7 MD5 | raw file
Possible License(s): AGPL-1.0
- *set_error_handler* -- Sets a user-defined error handler function
- mixed set_error_handler(callback error_handler [, int error_types])~
- Sets a user function ({error_handler}) to handle errors in a script.
- This function can be used for defining your own way of handling errors during
- runtime, for example in applications in which you need to do cleanup of
- data/files when a critical error happens, or when you need to trigger an error
- under certain conditions (using |trigger_error|).
- It is important to remember that the standard PHP error handler is completely
- bypassed for the error types specified by {error_types} unless the callback
- function returns FALSE. |error_reporting| settings will have no effect and
- your error handler will be called regardless - however you are still able to
- read the current value of error_reporting and act appropriately. Of particular
- note is that this value will be 0 if the statement that caused the error was
- prepended by the @ error-control operator.
- Also note that it is your responsibility to |die| if necessary. If the
- error-handler function returns, script execution will continue with the next
- statement after the one that caused an error.
- The following error types cannot be handled with a user defined function:
- E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR,
- E_COMPILE_WARNING, and most of E_STRICT raised in the file where
- |set_error_handler| is called.
- If errors occur before the script is executed (e.g. on file uploads) the
- custom error handler cannot be called since it is not registered at that time.
- {error_handler} The user function needs to accept two parameters: the error
- code, and a string describing the error. Then there are three optional
- parameters that may be supplied: the filename in which the error occurred, the
- line number in which the error occurred, and the context in which the error
- occurred (an array that points to the active symbol table at the point the
- error occurred). The function can be shown as:
- mixed (callback error_handler [, int error_types, int errno, string errstr [, string errfile [, int errline [, array errcontext]]]])~
- {errno} The first parameter, {errno}, contains the level of the error raised,
- as an integer.
- {errstr} The second parameter, {errstr}, contains the error message, as a
- string.
- {errfile} The third parameter is optional, {errfile}, which contains the
- filename that the error was raised in, as a string.
- {errline} The fourth parameter is optional, {errline}, which contains the line
- number the error was raised at, as an integer.
- {errcontext} The fifth parameter is optional, {errcontext}, which is an array
- that points to the active symbol table at the point the error occurred. In
- other words, {errcontext} will contain an array of every variable that existed
- in the scope the error was triggered in. User error handler must not modify
- error context.
- If the function returns FALSE then the normal error handler continues.
- {error_types} Can be used to mask the triggering of the {error_handler}
- function just like the error_reporting ini setting controls which errors are
- shown. Without this mask set the {error_handler} will be called for every
- error regardless to the setting of the error_reporting setting.
- Returns a string containing the previously defined error handler (if any). If
- the built-in error handler is used NULL is returned. NULL is also returned in
- case of an error such as an invalid callback. If the previous error handler
- was a class method, this function will return an indexed array with the class
- and the method name.
- Version Description 5.2.0 The error handler must return FALSE to populate
- $php_errormsg. 5.0.0 The {error_types} parameter was introduced. 4.3.0 Instead
- of a function name, an array containing an object reference and a method name
- can also be supplied as the {error_handler}. 4.0.2 Three optional parameters
- for the {error_handler} user function was introduced. These are the filename,
- the line number, and the context.
- Error handling with |set_error_handler| and |trigger_error| The example below
- shows the handling of internal exceptions by triggering errors and handling
- them with a user defined function:
- <?php >
- // error handler function
- function myErrorHandler($errno, $errstr, $errfile, $errline)
- {
- if (!(error_reporting() & $errno)) {
- // This error code is not included in error_reporting
- return;
- }
-
- switch ($errno) {
- case E_USER_ERROR:
- echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
- echo " Fatal error on line $errline in file $errfile";
- echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
- echo "Aborting...<br />\n";
- exit(1);
- break;
-
- case E_USER_WARNING:
- echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
- break;
-
- case E_USER_NOTICE:
- echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
- break;
-
- default:
- echo "Unknown error type: [$errno] $errstr<br />\n";
- break;
- }
-
- /* Don't execute PHP internal error handler */
- return true;
- }
-
- // function to test the error handling
- function scale_by_log($vect, $scale)
- {
- if (!is_numeric($scale) || $scale <= 0) {
- trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
- }
-
- if (!is_array($vect)) {
- trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
- return null;
- }
-
- $temp = array();
- foreach($vect as $pos => $value) {
- if (!is_numeric($value)) {
- trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
- $value = 0;
- }
- $temp[$pos] = log($scale) * $value;
- }
-
- return $temp;
- }
-
- // set to the user defined error handler
- $old_error_handler = set_error_handler("myErrorHandler");
-
- // trigger some errors, first define a mixed array with a non-numeric item
- echo "vector a\n";
- $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
- print_r($a);
-
- // now generate second array
- echo "----\nvector b - a notice (b = log(PI) * a)\n";
- /* Value at position $pos is not a number, using 0 (zero) */
- $b = scale_by_log($a, M_PI);
- print_r($b);
-
- // this is trouble, we pass a string instead of an array
- echo "----\nvector c - a warning\n";
- /* Incorrect input vector, array of values expected */
- $c = scale_by_log("not array", 2.3);
- var_dump($c); // NULL
-
- // this is a critical error, log of zero or negative number is undefined
- echo "----\nvector d - fatal error\n";
- /* log(x) for x <= 0 is undefined, you used: scale = $scale" */
- $d = scale_by_log($a, -2.5);
- var_dump($d); // Never reached
- ?>
- The above example will output something similar to:
- vector a
- Array
- (
- [0] => 2
- [1] => 3
- [2] => foo
- [3] => 5.5
- [4] => 43.3
- [5] => 21.11
- )
- ----
- vector b - a notice (b = log(PI) * a)
- <b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
- Array
- (
- [0] => 2.2894597716988
- [1] => 3.4341896575482
- [2] => 0
- [3] => 6.2960143721717
- [4] => 49.566804057279
- [5] => 24.165247890281
- )
- ----
- vector c - a warning
- <b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
- NULL
- ----
- vector d - fatal error
- <b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
- Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
- Aborting...<br />
- ErrorException |error_reporting| |restore_error_handler| |trigger_error| error
- level constants information about the callback type
- vim:ft=help: