set_error_handler
(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
Sets a user-defined error handler function
Description
Sets a user function (callback) to handle errors in a script. The handler that was active until then is saved on an internal stack of error handlers, from which restore_error_handler() pops it back.
This function can be used to define custom error handlers during runtime, for example in applications which need to do file/data cleanup when a critical error happens, or when triggering an error in response to 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_levels unless the callback function returns false. error_reporting() settings will have no effect and the error handler will be called regardless - however, it's still possible to read the current value of error_reporting and act appropriately.
Also note that it is the handler's responsibility to stop the script's execution if necessary by calling exit(). 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 independent of where they were raised, 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
callbackIf null is passed, no user-defined handler is left active and errors fall back to the built-in error handler. The handler that was active until then is still saved on the stack and can be brought back with
restore_error_handler(). Otherwise, the handler is a callback with the following signature:handler(int $errno, string $errstr, [string $errfile], [int $errline], [array $errcontext]): boolerrnoThe first parameter,
errno, will be passed the level of the error raised, as an integer.errstrThe second parameter,
errstr, will be passed the error message, as a string.errfileIf the callback accepts a third parameter,
errfile, it will be passed the filename that the error was raised in, as a string.errlineIf the callback accepts a fourth parameter,
errline, it will be passed the line number where the error was raised, as an integer.errcontextIf the callback accepts a fifth parameter,
errcontext, it will be passed an array that points to the active symbol table at the point the error occurred. In other words,errcontextwill contain an array of every variable that existed in the scope the error was triggered in. User error handlers must not modify the error context.WarningThis parameter has been DEPRECATED as of PHP 7.2.0, and REMOVED as of PHP 8.0.0. If the function defines this parameter without a default, an error of "too few arguments" will be raised when it is called.
If the function returns false then the normal error handler continues.
error_levelsCan be used to mask the triggering of the
callbackfunction just like the error_reporting ini setting controls which errors are shown. Without this mask set thecallbackwill be called for every error regardless to the setting of the error_reporting setting.
Return Values
Returns the previously defined error handler (if any) as a callable. If the built-in error handler is used null is returned.
Changelog
| Version | Description |
|---|---|
| 8.0.0 | errcontext was removed, and will no longer be passed to user callbacks. |
| 7.2.0 | errcontext became deprecated. Usage of this parameter now emits an E_DEPRECATED notice. |
Examples
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;
}
// $errstr may need to be escaped:
$errstr = htmlspecialchars($errstr);
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);
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 />Calling the previous handler from the new one
The return value of set_error_handler() is the handler that was active until then. Calling it from the new handler keeps the existing behaviour while adding to it. This only works if that handler is a user defined function; null is returned when the built-in one was active.
<?php
function logging_handler(int $errno, string $errstr): bool
{
echo "logged: $errstr\n";
return true;
}
set_error_handler('logging_handler');
$previous = set_error_handler(function (int $errno, string $errstr) use (&$previous): bool {
echo "counted: $errstr\n";
return $previous !== null ? $previous($errno, $errstr) : false;
});
trigger_error("something happened", E_USER_WARNING);
restore_error_handler();
trigger_error("only logged now", E_USER_WARNING);
restore_error_handler();
?>The above example will output:
counted: something happened
logged: something happened
logged: only logged nowNotes
Do not revert to the previous handler by passing the return value of set_error_handler() back to it. Doing so pushes a further entry onto the stack instead of removing one, so the stack grows without bound in loops and long-running processes, and error_levels is reset to E_ALL, silently widening the range of errors the restored handler receives. restore_error_handler() is the intended way to revert to the previous handler.