set_error_handler
Manual de PHP
AnteriorSiguiente

set_error_handler

(PHP 4 >= 4.0.1, PHP 5)

set_error_handler --  Establece una funci贸n de gesti贸n de errores definida por el usuario

Descripci贸n

mixed set_error_handler ( callback gestor_errores [, int tipos_error] )

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.

Lista de par谩metros

gestor_errores

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:

gestor ( int num_err, string cadena_err [, string archivo_err [, int linea_err [, array contexto_err]]] )

num_err

El primer par谩metro, num_err, contiene el nivel del error generado, como un entero.

cadena_err

El segundo par谩metro, cadena_err, contiene el mensaje de error, como una cadena.

archivo_err

El tercer par谩metro es opcional, archivo_err, el cual contiene el nombre del archivo en el que se gener贸 el error, como una cadena.

linea_err

El cuarto par谩metro es opcional, linea_err, el cual contiene el n煤mero de l铆nea en la que se gener贸 el error, como un entero.

contexto_err

El quinto par谩metro es opcional, contexto_err, el cual es una matriz que apunta a la tabla activa de s铆mbolos en el punto en el que ocurri贸 el error. En otras palabras, contexto_err contendr谩 una matriz de todas las variables que existieron en el contexto en el que ocurri贸 el error. El gestor de errores definido por el usuario no debe modificar el contexto del error.

tipos_error

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.

Valores retornados

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.

Registro de cambios

Versi贸nDescripci贸n
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.

Ejemplos

Ejemplo 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
// definir el nivel de reporte de errores para este script
error_reporting(E_USER_ERROR | E_USER_WARNING | E_USER_NOTICE);

// funcion de gestion 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 linea $linea_err del 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;
  }
}

// funcion para probar la gestion de errores
function escalar_por_log($vect, $escala)
{
  if (!is_numeric($escala) || $escala <= 0) {
    trigger_error("log(x) para x <= 0 es indefinido, usted uso: escala = $escala", E_USER_ERROR);
  }

  if (!is_array($vect)) {
    trigger_error("Vector de entrada incorrecto, se esperan valores de matriz", E_USER_WARNING);
    return null;
  }

  for ($i=0; $i<count($vect); $i++) {
    if (!is_numeric($vect[$i]))
      trigger_error("El valor en la posicion $i no es un numero, se usa 0 (cero)", E_USER_NOTICE);
      $temp[$i] = log($escala) * $vect[$i];
    }
    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 item no-numerico
echo "vector a\n";
$a = array(2,3, "foo", 5.5, 43.3, 21.11);
print_r($a);

// ahora generar una segunda matriz, generando una advertencia
echo "----\nvector b - a advertencia (b = log(PI) * a)\n";
$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 - un error\n";
$c = escalar_por_log("no es matriz", 2.3);
var_dump($c);

// este es un error critico, log de cero o un numero negativo es indefinido
echo "----\nvector d - error fatal\n";
$d = escalar_por_log($a, -2.5);

?>

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 - a advertencia (b = log(PI) * a)
<b>Mi NOTICIA</b> [1024] El valor en la posicion 2 no es un numero, 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 - un error
<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 uso: escala = -2.5<br />
  Error fatal en la linea 32 del archivo generar_error.php, PHP 5.0.4 (Linux)<br />
Abortando...<br />

Ver tambi茅n

error_reporting()
restore_error_handler()
trigger_error()
constantes de nivel de error
information about the callback type

AnteriorInicioSiguiente
restore_exception_handlerSubirset_exception_handler