(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
set_error_handler — Establecer una función de gestión de errores definida por el usuario
Establece una función de usuario (error_handler
) para manejar los errores de un script.
Esta función se puede usar para definir su propia forma de manejar los errores en tiempo de ejecución, por ejemplo en aplicaciones en las que se necesita hacer una limpieza de datos/archivos cuando ocurre un error crítico, o cuando se necesita provocar un error bajo ciertas condiciones (usando trigger_error()).
Es importante recordar que el gestor de errores estándar de PHP es completamente evitado por los tipos de errores especificados por error_types
a menos que la función de llamada de retorno devuelva false
. La configuración de error_reporting() no tendrá efecto y su gestor de errores será llamado de todas formas - aunque aún es capaz de leer el valor actual de error_reporting y actuar de manera apropiada. En particular, observe que este valor será 0 si a la sentencia que causó el error se le añadió al principio el operador de control de errores @ .
También observe que es su responsabilidad realizar un die() si fuera necesario. Si la función de gestión de errores devuelve, la ejecución del script continuará con la siguiente sentencia después de la que causó el error.
Los siguientes tipos de errores no pueden ser manejados con una función definida por el usuario: E_ERROR
, E_PARSE
, E_CORE_ERROR
, E_CORE_WARNING
, E_COMPILE_ERROR
, E_COMPILE_WARNING
, y la mayoría de E_STRICT
ocasionados en el archivo desde donde se llamó a set_error_handler().
Si sucede algún error antes de que el script sea ejecutado (p.ej. en la carga de archivos) el gestor de errores personalizado no podrá ser llamado ya que no está registrado en ese momento.
error_handler
Una llamada de retorno con la siguiente signatura. Se podría pasar null
en su lugar para reiniciar este gestor a su estado predeterminado. También se puede proporcionar un nombre de una función, un array que contenga una referencia a un objeto y un nombre de un método.
errno
errno
, contiene el nivel del error ocasionado, como un valor de tipo integer. errstr
errstr
, contiene el mensaje de error, como cadena. errfile
errfile
, que contiene el nombre de archivo que ocasionó el error, como cadena. errline
errline
, que contiene el número de línea donde ocurrió el error, como valor de tipo integer. errcontext
errcontext
, el cuál es una matriz que apunta a la tabla de símbolos activa en el punto donde ocurrió el error. En otras palabras, errcontext
contendrá una matriz con cada variable que existe en el ámbito donde el error fue provocado. El gestor de errores de usuario no debe modificar el contexto del error. Si la función devuelve false
se continúa con el gestor de errores normal.
error_types
Se puede usar para enmascarar la provocación de la función error_handler
al igual que la configuración error_reporting ini controla los errores que se muestran. Sin esta máscara establecida error_handler
será llamada para cada error sin tener en cuenta la configuración de error_reporting.
Devuelve una cadena que contiene el gestor de errores definido anteriormente (si lo hay). Si se usa el gestor de errores interno se devuelve null
. null
también es devuelto en caso de un error como una llamada de retorno no válida. Si el gestor de errores anterior era un método de una clase, esta función devolverá una matriz indexada con los nombres de las clases y métodos.
Versión | Descripción |
---|---|
5.5.0 | error_handler ahora acepta null . |
5.2.0 | El gestor de errores debe devolver false para rellenar $php_errormsg. |
Ejemplo #1 Manejo de errores con set_error_handler() y trigger_error()
El ejemplo de abajo muestra el manejo de excepciones internas mediante la provocación de errores y tratándolos con una función definida por el usuario:
<?php
// función de gestión de errores
function miGestorDeErrores($errno, $errstr, $errfile, $errline)
{
if (!(error_reporting() & $errno)) {
// Este código de error no está incluido en error_reporting
return;
}
switch ($errno) {
case E_USER_ERROR:
echo "<b>Mi ERROR</b> [$errno] $errstr<br />\n";
echo " Error fatal en la línea $errline en el archivo $errfile";
echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
echo "Abortando...<br />\n";
exit(1);
break;
case E_USER_WARNING:
echo "<b>Mi WARNING</b> [$errno] $errstr<br />\n";
break;
case E_USER_NOTICE:
echo "<b>Mi NOTICE</b> [$errno] $errstr<br />\n";
break;
default:
echo "Tipo de error desconocido: [$errno] $errstr<br />\n";
break;
}
return true;
}
// función para probar el manejo de errores
function scale_by_log($vect, $scale)
{
if (!is_numeric($scale) || $scale <= 0) {
trigger_error("log(x) para x <= 0 no está definido, usó: scale = $scale", E_USER_ERROR);
}
if (!is_array($vect)) {
trigger_error("Vector de entrada incorrecto, se esperaba una matriz de valores", E_USER_WARNING);
return null;
}
$temp = array();
foreach($vect as $pos => $valor) {
if (!is_numeric($valor)) {
trigger_error("El valor en la posición $pos no es un número, usando 0 (cero)", E_USER_NOTICE);
$valor = 0;
}
$temp[$pos] = log($scale) * $valor;
}
return $temp;
}
// establecer el gestro de errores definido por el usuario
$gestor_errores_antiguo = set_error_handler("miGestorDeErrores");
// provocar algunos errores, primero definimos una matriz mixta con un elemento no numérico
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);
// ahora generamos una segunda matriz
echo "----\nvector b - a notice (b = log(PI) * a)\n";
$b = scale_by_log($a, M_PI);
print_r($b);
// esto es un problema, pasamos una cadena en vez de una matriz
echo "----\nvector c - a warning\n";
$c = scale_by_log("no array", 2.3);
var_dump($c); // NULL
// esto es un error crítico, log de cero o de un número negativo es indefinido
echo "----\nvector d - fatal error\n";
$d = scale_by_log($a, -2.5);
var_dump($d); // Nunca se alcanza
?>
El resultado del ejemplo sería algo similar a:
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>Mi NOTICE</b> [1024] El valor en la posición 2 no es un número, usando 0 (cero)<br /> Array ( [0] => 2.2894597716988 [1] => 3.4341896575482 [2] => 0 [3] => 6.2960143721717 [4] => 49.566804057279 [5] => 24.165247890281 ) ---- vector c - a warning <b>Mi WARNING</b> [512] Vector de entrada incorrecto, se esperaba una matriz de valores<br /> NULL ---- vector d - fatal error <b>Mi ERROR</b> [256] log(x) para x <= 0 no está definido, usó: scale = -2.5<br /> Error fatal en la línea 35 en el archivo trigger_error.php, PHP 5.2.1 (FreeBSD)<br /> Abortando...<br />