(PHP 4 >= 4.0.1, PHP 5)
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 neceista 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.
La función de usuario necesita aceptar dos parámetros: el código del error, y una cadena describiendo el error. Hay tres parámetros opcionales que pueden ser proporcionados: el nombre de archivo en el que ocurrió el error, el número de línea en el que ocurrió el error, y el contexto en el que ocurrió el error (una matriz que apunta a la tabla de símbolos activa en el punto donde ocurrió el error). La función se puede mostrar como:
Si la función devuelve FALSE se continúa con el gestor de errores normal.
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.2.0 | El gestor de errores debe devolver FALSE para rellenar $php_errormsg. |
5.0.0 | Se introdujo el parámetro error_types. |
4.3.0 | También se puede proporcionar una matriz que contiene una referencia a un objeto y un nombre de método, en vez el nombre de una función, como error_handler. |
4.0.2 | Se introdujeron tres parámetros opcionales para la función de usuario error_handler. Son el nombre de archivo, el número de línea, y el contexto. |
Example #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;
}
/* No ejecutar el gestor de errores interno de PHP */
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";
/* Value at position $pos is not a number, using 0 (zero) */
$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";
/* Vector de entrada incorrecto, se esperaba una matriz de valores */
$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";
/* log(x) para x <= 0 no está definido, usó: scale = $scale */
$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 />