(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.
error_handler
Una llamada de retorno con la siguiente firma.
Se podría pasar NULL en su lugar para reiniciar este gestor a su estado predeterminado.
$errno
, string $errstr
[, string $errfile
[, int $errline
[, array $errcontext
]]] )errnoerrno, contiene el
nivel del error ocasionado, como un valor de tipo integer.
errstrerrstr, contiene el
mensaje de error, como cadena.
errfileerrfile,
que contiene el nombre de archivo que ocasionó el error, como cadena.
errlineerrline,
que contiene el número de línea donde ocurrió el error, como valor de tipo integer.
errcontexterrcontext,
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.
|
| 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.
|
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;
}
/* 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 />