set_error_handler
(PHP 4 >= 4.0.1, PHP 5, PHP 7)
set_error_handler — Sets a user-defined error handler function
Description
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.
Parameters
-
error_handler
-
A callback with the following signature.
NULL
may be passed instead, to reset this handler to its default state. Instead of a function name, an array containing an object reference and a method name can also be supplied.handler ( int$errno
, string$errstr
[, string$errfile
[, int$errline
[, array$errcontext
]]] ) : bool-
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.WarningThis parameter has been DEPRECATED as of PHP 7.2.0. Relying on it is highly discouraged.
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 theerror_handler
will be called for every error regardless to the setting of the error_reporting setting.
Return Values
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.
Changelog
Version | Description |
---|---|
7.2.0 |
errcontext became deprecated. Usage of this parameter now emits an E_DEPRECATED notice.
|
5.5.0 |
error_handler now accepts NULL .
|
5.2.0 |
The error handler must return FALSE to populate
$php_errormsg.
|
Examples
Example #1 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, so let it fall
// through to the standard PHP error handler
return false;
}
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 />
See Also
- ErrorException
- error_reporting() - Sets which PHP errors are reported
- restore_error_handler() - Restores the previous error handler function
- trigger_error() - Generates a user-level error/warning/notice message
- error level constants
- information about the callback type
English translation
You have asked to visit this site in English. For now, only the interface is translated, but not all the content yet.If you want to help me in translations, your contribution is welcome. All you need to do is register on the site, and send me a message asking me to add you to the group of translators, which will give you the opportunity to translate the pages you want. A link at the bottom of each translated page indicates that you are the translator, and has a link to your profile.
Thank you in advance.
Document created the 30/01/2003, last modified the 26/10/2018
Source of the printed document:https://www.gaudry.be/en/php-rf-set-error-handler.html
The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.
References
These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.