set_error_handler

(PHP 4 >= 4.0.1, PHP 5)

set_error_handler — Establecer una función de gestión de errores definida por el usuario

Descripción

mixed set_error_handler ( callable $error_handler [, int $error_types = E_ALL | E_STRICT ] )

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.

Parámetros

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. También se puede proporcionar un nombre de una función, un array que contenga una referencia a un objeto y un nombre deun método.

bool handler ( int $errno , string $errstr [, string $errfile [, int $errline [, array $errcontext ]]] )
errno
El primer parámetro, errno, contiene el nivel del error ocasionado, como un valor de tipo integer.
errstr
El segundo parámetro, errstr, contiene el mensaje de error, como cadena.
errfile
El tercer parámetro es opcional, errfile, que contiene el nombre de archivo que ocasionó el error, como cadena.
errline
El cuarto parámetro es opcional, errline, que contiene el número de línea donde ocurrió el error, como valor de tipo integer.
errcontext
El quinto parámetro es opcional, 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.

Valores devueltos

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.

Historial de cambios

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.

Ejemplos

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 />

Ver también