(PHP 4 >= 4.0.1, PHP 5)
set_error_handler — Establece una función de gestión de errores definida por el usuario
Establece una función de usuario (gestor_errores ) para manejar los errores en un script.
Esta función puede ser usada para definir su propia forma de gestionar errores en tiempo de ejecución, por ejemplo en aplicaciones en las que necesita efectuar limpieza de datos/archivos cuando ocurre en error crítico, o cuando necesita generar un error bajo ciertas condiciones (usando trigger_error()).
Es importante recordar que el gestor de errores estándar de PHP es completamente ignorado. Los parámetros de error_reporting() no tendrán efecto alguno y su gestor de errores será llamado en cualquier circunstancia - sin embargo es posible leer el valor actual de error_reporting y actuar apropiadamente. Es particularmente importante notar que este valor será 0 si la sentencia que causó el error fue precedida por el operador de control de errores @.
Note también que es su responsabilidad usar die() si es necesario. Si la función de gestión de errores retorna, la ejecución del script continuará con la siguiente sentencia después de aquélla que causó el error.
Los siguientes tipos de error no pueden ser gestionados 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 generados en el archivo en donde set_error_handler() es llamado.
Si ocurren errores antes de que el script es ejecutado (p.ej. cuando se cargan archivos desde una página web) el gestor de errores personalizado no puede ser llamado ya que no está registrado en ese momento.
La función de usuario necesita aceptar dos parámetros: el código de error, y una cadena que describa el error. Luego hay tres parámetros opcionales que pueden entregarse: el nombre del 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 activa de símbolos en el punto en el que ocurrió el error). La función puede mostrarse como:
Si la función devuelve FALSE entonces el gestor de errores normal continúa.
Puede ser usado para aplicar una máscara a las llamadas de la función error_handler tal y como el parámetro ini error_reporting controla qué errores son mostrados. Sin esta máscara definida, el gestor_errores será llamado para cada error sin importar el valor del parámetro error_reporting.
Devuelve una cadena que contiene el gestor de errores previamente definido (si lo hay), o NULL en caso de error. Si el gestor previo era un método de clase, esta función devolverá una matriz indexada con la clase y el nombre del método.
| Versión | Descripción |
|---|---|
| 5.2.0 | El gestor de errores debe devolver FALSE para poblar $php_errormsg. |
| 5.0.0 | Se introdujo el parámetro tipos_error . |
| 4.3.0 | En lugar de un nombre de función, también es posible entregar una matriz que contenga una referencia a objeto y un nombre de método como valor de gestor_errores . |
| 4.0.2 | Se introdujeron tres parámetros opcionales para la función de usuario gestor_errores . Estos son el nombre de archivo, el número de línea, y el contexto. |
Example#1 Gestión de errores con set_error_handler() y trigger_error()
El siguiente ejemplo muestra la gestión de excepciones internas generando errores y manejándolos con una función definida por el usuario:
<?php
// función de gestión de errores
function miGestorErrores($num_err, $cadena_err, $archivo_err, $linea_err)
{
switch ($num_err) {
case E_USER_ERROR:
echo "<b>Mi ERROR</b> [$num_err] $cadena_err<br />\n";
echo " Error fatal en la línea $linea_err en el archivo $archivo_err";
echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
echo "Abortando...<br />\n";
exit(1);
break;
case E_USER_WARNING:
echo "<b>Mi ADVERTENCIA</b> [$num_err] $cadena_err<br />\n";
break;
case E_USER_NOTICE:
echo "<b>Mi NOTICIA</b> [$num_err] $cadena_err<br />\n";
break;
default:
echo "Tipo de error desconocido: [$num_err] $cadena_err<br />\n";
break;
}
/* No ejecutar el gestor de errores interno de PHP */
return true;
}
// función para probar la gestión de errores
function escalar_por_log($vect, $escala)
{
if (!is_numeric($escala) || $escala <= 0) {
trigger_error("log(x) para x <= 0 es indefinido, usted usó: escala = $escala", E_USER_ERROR);
}
if (!is_array($vect)) {
trigger_error("Vector de entrada incorrecto, se espera 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($escala) * $valor;
}
return $temp;
}
// establecer el gestor de errores definido
$gestor_errores_anterior = set_error_handler("miGestorErrores");
// generar algunos errores, primero definir una matriz mezclada con un ítem no-numérico
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);
// ahora generar una segunda matriz
echo "----\nvector b - una noticia (b = log(PI) * a)\n";
/* El valor en la posición $pos no es un número, usando 0 (cero) */
$b = escalar_por_log($a, M_PI);
print_r($b);
// esto es un problema, pasamos una cadena en lugar de una matriz
echo "----\nvector c - una advertencia\n";
/* Vector de entrada incorrecto, se espera una matriz de valores */
$c = escalar_por_log("no es matriz", 2.3);
var_dump($c); // NULL
// este es un error crítico, log de cero o un número negativo es indefinido
echo "----\nvector d - error fatal\n";
/* log(x) para x <= 0 es indefinido, usted usó: escala = $escala" */
$d = escalar_por_log($a, -2.5);
var_dump($d); // Nunca se alcanza
?>
El resultado del ejemplo seria algo similar a:
vector a Array ( [0] => 2 [1] => 3 [2] => foo [3] => 5.5 [4] => 43.3 [5] => 21.11 ) ---- vector b - una noticia (b = log(PI) * a) <b>Mi NOTICIA</b> [1024] El valor en la posición 2 no es un número, se usa 0 (cero)<br /> Array ( [0] => 2.2894597717 [1] => 3.43418965755 [2] => 0 [3] => 6.29601437217 [4] => 49.5668040573 [5] => 24.1652478903 ) ---- vector c - una advertencia <b>Mi ADVERTENCIA</b> [512] Vector de entrada incorrecto, se esperan valores de matriz<br /> NULL ---- vector d - error fatal <b>Mi ERROR</b> [256] log(x) para x <= 0 es indefinido, usted usó: escala = -2.5<br /> Error fatal en la línea 32 del archivo generar_error.php, PHP 5.0.4 (Linux)<br /> Abortando...<br />