set_error_handler()

set_error_handler() — Sets a user-defined error handler function.

Built-in function of PHP 8.5. The manual lists it as available in PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8. This page is the reference card: signature, parameters and return value, plus the changelog and the example the manual provides.

What it does

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()).

Signature

set_error_handler(?callable $callback, int $error_levels = E_ALL): ?callable handler(int $errno, string $errstr, string $errfile = ?, int $errline = ?, array $errcontext = ?): bool

Parameters

Parameter	Type	What it takes
$callback	?callable	function handler( int $errno, string $errstr, string $errfile = ?, int $errline = ?, array $errcontext = ?): bool errno The first parameter, errno, will be passed the level of the error raised, as an integer. errstr The second parameter, errstr, will be passed the error message, as a string. errfile If the callback accepts a third parameter, errfile, it will be passed the filename that the error was raised in, as a ...
$error_levels	int	Can be used to mask the triggering of the callback function just like the error_reporting ini setting controls which errors are shown. Without this mask set the callback will be called for every error regardless to the setting of the error_reporting setting.

Return value

Returns the previously defined error handler (if any) as a callable. If the built-in error handler is used null is returned.

Example

A runnable snippet:

// 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 "My ERROR [$errno] $errstr \n"; echo " Fatal error on line $errline in file $errfile"; echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ") \n"; echo "Aborting... \n"; exit(1); case E_USER_WARNING: echo "My WARNING [$errno] $errstr \n"; break; case E_USER_NOTICE: echo "My NOTICE [$errno] $errstr \n"; break; default: echo "Unknown error type: [$errno] $errstr \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

Output:

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) My NOTICE [1024] Value at position 2 is not a number, using 0 (zero) Array ( [0] => 2.2894597716988 [1] => 3.4341896575482 [2] => 0 [3] => 6.2960143721717 [4] => 49.566804057279 [5] => 24.165247890281 ) ---- vector c - a warning My WARNING [512] Incorrect input vector, array of values expected NULL ---- vector d - fatal error My ERROR [256] log(x) for x <= 0 is undefined, you used: scale = -2.5 Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD) Aborting...

Changelog

Version	Change
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.