XXXI. Funciones de Gestión de Errores y Registros
Estas son funciones que trabajan en la gestión de errores y
registros. Le permiten definir sus propias reglas de
gestión de errores, asi como modificar el modo en que los
errores son registrados. Esto le permite modificar y mejorar el
reporte de errores para que se adapte a sus necesidades.
Con las funciones de registro, puede enviar mensajes directamente
a otras máquinas, a un correo electrónico (¡o
correo electrónico a una puerta de enlace con un
buscapersonas!), a bitácoras del sistema, etc., de modo que
puede registrar y monitorear selectivamente las partes más
importantes de sus aplicaciones y sitios web.
Las funciones de reporte de errores le permiten personalizar el
nivel y tipo de retroalimentación de errores que PHP
entrega, desde noticias simples a funciones personalizadas
devueltas durante los errores.
No se necesitan bibliotecas externas
para construir esta extensión No se necesita ninguna instalación
para usar estas funciones, son parte del núcleo de
PHP. El comportamiento de estas
funciones está afectado por los valores definidos en
php.ini.
Tabla 1. Opciones de Configuración de Errores y
Registro | Nombre | Por defecto | Modificable | Cambios |
|---|
| error_reporting | NULL | PHP_INI_ALL | | | display_errors | "1" | PHP_INI_ALL | | | display_startup_errors | "0" | PHP_INI_ALL | Disponible desde PHP 4.0.3. | | log_errors | "0" | PHP_INI_ALL | | | log_errors_max_len | "1024" | PHP_INI_ALL | Disponible desde PHP 4.3.0. | | ignore_repeated_errors | "0" | PHP_INI_ALL | Disponible desde PHP 4.3.0. | | ignore_repeated_source | "0" | PHP_INI_ALL | Disponible desde PHP 4.3.0. | | report_memleaks | "1" | PHP_INI_ALL | Disponible desde PHP 4.3.0. | | track_errors | "0" | PHP_INI_ALL | | | html_errors | "1" | PHP_INI_ALL | PHP_INI_SYSTEM en PHP <= 4.2.3. Disponible desde PHP
4.0.2. | | docref_root | "" | PHP_INI_ALL | Disponible desde PHP 4.3.0. | | docref_ext | "" | PHP_INI_ALL | Disponible desde PHP 4.3.2. | | error_prepend_string | NULL | PHP_INI_ALL | | | error_append_string | NULL | PHP_INI_ALL | | | error_log | NULL | PHP_INI_ALL | | | warn_plus_overloading | NULL | PHP_INI?? | |
For further details and definitions of the
PHP_INI_* constants, see the Apéndice H.
A continuación se
presenta una corta explicación de las directivas de
configuración.
- error_reporting
integer
Establece el nivel de reporte de errores. Este parámetro
es, o bien un entero que representa un campo de bit, o
constantes con nombre. Los niveles de error_reporting y las
constantes están descritas en Constantes Predefinidas, y
en php.ini. Para definir este valor en tiempo de
ejecución, use la función
error_reporting(). Vea también la
directiva display_errors.
En PHP 4 y PHP 5, el valor predeterminado es E_ALL &
~E_NOTICE. Este valor no muestra errores de nivel
E_NOTICE. Puede que usted quiera mostrarlos
durante su actividad de desarrollo.
Nota:
Al habilitar E_NOTICE durante el
desarrollo de software tiene algunos beneficios. Para
propósitos de depuración: los mensajes NOTICE le
advertirán sobre posibles fallos en su
código. Por ejemplo, se le advertirá sobre el uso
de valores no-asignados. Es extremadamente útil para
encontrar errores ortográficos y ahorrar tiempo de
depuración. Los mensajes NOTICE le advertirán
sobre el uso de un estilo incorrecto. Por ejemplo,
$matriz[item] está mejor escrito como $matriz['item'] ya
que PHP intenta darle a "item" un tratamiento de constante. Si
no es una constante, PHP asume que es un índice de tipo
cadena para la matriz.
Nota:
En PHP 5, un nuevo nivel de error,
E_STRICT, se encuentra disponible. Dado
que E_STRICT no se incluye en
E_ALL, usted debe habilitar
explícitamente este tipo de nivel de error. Habilitar
E_STRICT durante el desarrollo tiene
algunos beneficios. Los mensajes STRICT le ayudarán a
usar los últimos y más grandiosos métodos
sugeridos para escribir código, por ejemplo, le
advertirá sobre el uso de funciones obsoletas.
En PHP 3, el valor por defecto es (E_ERROR | E_WARNING
| E_PARSE), lo que en la práctica representa lo
mismo. Note, sin embargo, que dado que las constantes en el
archivo php3.ini de PHP 3 no son
soportadas, el valor de error_reporting allí debe ser
numérico; por lo tanto, es 7.
- display_errors
boolean
Este parámetro determina si los errores deben ser puestos
en pantalla como parte de la salida o si deben ser ocultados al
usuario.
Nota:
Es una característica de apoyo para su proceso de
desarrollo y no debería ser usada nunca en sistemas en
producción (p.ej. sistemas conectados a internet).
Nota:
Aunque display_errors puede ser definido en tiempo de
ejecución (con ini_set()), no
tendrá ningún efecto si el script contiene
errores fatales. Esto se debe a que la acción de tiempo
de ejecución deseada no se alcanza a ejecutar.
- display_startup_errors
boolean
Aun cuando display_errors esté encendido, los errores que
ocurren durante la secuencia de arranque de PHP no son
desplegados. Es muy recomendable mantener display_startup_errors
apagado, excepto en tiempos de depuración.
- log_errors
boolean
Indica si los mensajes de error de un script deben ser
registrados en la bitácora de errores del servidor o
error_log. Esta
opción es por lo tanto espocífica al servidor.
Nota:
Es altamente recomendable que use registro de errores en lugar
de despliegue de errores en sitios web en producción.
- log_errors_max_len
integer
Establece la longitud máxima de log_errors en bytes. En
error_log se añade
información sobre la fuente. El valor por defecto es
1024, y un valor de 0 permite que no se aplique ninguna longitud
máxima en absoluto. Esta longitud se aplica
también a los errores almacenados en el registro, a los
errores que se despliegan y a $php_errormsg.
Cuando se usa un número
entero, el valor del mismo es medido en bytes. También se
puede usar la notación reducida tal como se describe en esta FAQ. - ignore_repeated_errors
boolean
No registrar mensajes repetidos. Los errores repetidos deben
ocurrir en el mismo archivo, en la misma línea hasta que
el parámetro ignore_repeated_source
sea establecido como true.
- ignore_repeated_source
boolean
Ignorar la fuente de mensaje cuando se ignoran los mensajes
repetidos. Cuando este parámetro está encendido,
no se registrará errores con mensajes repetidos desde
diferentes fuentes de archivos.
- report_memleaks
boolean
Si este parámetro está apagado, entonces las fugas
de memoria no serán mostradas (en stdout o en el
registro). Este valor sólo tiene efecto en una
compilación de depuración, y si error_reporting incluye
E_WARNING en la lista permitida.
- track_errors
boolean
Cuando está habilitado, el último mensaje de error
estará siempre presente en la variable $php_errormsg.
- html_errors
boolean
Permite deshabilitar las etiquetas HTML en los mensajes de
error. El nuevo formato para los errores en HTML produce
mensajes con enlaces que dirigen al usuario a una página
que describe el error o función que ha causado el
error. Estas referencias son afectadas por docref_root y docref_ext.
- docref_root
string
El nuevo formato de error contiene una referencia hacia una
página que describe el error o la función que ha
causado el error. En el caso de páginas de un manual,
usted puede descargar el manual en su idioma y establecer esta
directiva ini como la URL de su copia local. Si su copia local
del manual puede encontrarse bajo '/manual/' entonces puede usar
simplemente
docref_root=/manual/. Adicionalmente debe
establecer un valor de docref_ext que coincida con las
extensiones de archivo de su copia;
docref_ext=.html. Es posible usar
referencias externas. Por ejemplo, puede usar
docref_root=http://manual/en/ o
docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon
&url=http%3A%2F%2Fwww.php.net%2F".
Por lo general usted querrá que el valor de docref_root
finalice con una barra '/'. Pero observe el segundo ejemplo
mencionado anteriormente, el cual no tiene una barra final, ni
la necesita.
Nota:
Esta es una característica de apoyo para su desarrollo
ya que permite consultar la descripción de una
función fácilmente. Sin embargo, nunca debe ser
utilizada en sistemas en producción (p.ej. sistema
conectados a internet).
- docref_ext
string
Vea docref_root.
Nota:
El valor de docref_ext debe comenzar con un punto '.'.
- error_prepend_string
string
Cadena a mostrar antes de un mensaje de error.
- error_append_string
string
Cadena a mostrar después de un mensaje de error.
- error_log
string
Nombre del archivo en donde deberían registrarse los
errores del script. El archivo debe tener permisos de escritura
para el usuario del servidor web. Si se utiliza el valor
especial syslog, los errores son enviados al
gestor de registros del sistema. En Unix, esto quiere decir
syslog(3) y en Windows NT quiere decir el "event log". El gestor
de registro de actividades no está soportado bajo Windows
95. Vea también: syslog().
- warn_plus_overloading
boolean
Si se habilita, esta opción hace que PHP genere una
advertencia cuando se utilice un operador más
(+) con cadenas. Esto facilita la labor de
encontrar scripts que necesitan ser reescritos para hacer uso
del concatenador de cadenas en su lugar (.).
Las constantes listadas
aqui están siempre disponibles a través del
"núcleo PHP". Nota:
Es posible usar estos nombres de constantes en php.ini pero no
por fuera de PHP, como en httpd.conf, en donde debería
usar los valores de máscara de bits en su lugar.
Tabla 2. Errores y Registro | Valor | Constante | Descripción | Nota |
|---|
| 1 |
E_ERROR
(integer)
|
Errores fatales en tiempo de ejecución. Estos indican
errores de los que no es posible recuperarse, tales como
problemas de asignación de memoria. Se detiene la
ejecución del script.
| | | 2 |
E_WARNING
(integer)
|
Advertencias en tiempo de ejecución (errores
no-fatales). La ejecución del script no se interrumpe.
| | | 4 |
E_PARSE
(integer)
|
Errores de intérprete en tiempo de
compilación. Esto tipo de errores deberían ser
generados únicamente por el interprete.
| | | 8 |
E_NOTICE
(integer)
|
Anotaciones en tiempo de ejecución. Indican que el script
se ha topado con algo que puede indicar la presencia de un
error, pero que también podría ocurrir en el curso
normal de la ejecución de un script.
| | | 16 |
E_CORE_ERROR
(integer)
|
Errores fatales que ocurren durante el arranque inicial de
PHP. Es como un E_ERROR, excepto que es
generado por el núcleo de PHP.
| a partir de PHP 4 | | 32 |
E_CORE_WARNING
(integer)
|
Advertencias (errores no-fatales) que ocurren durante el
arranque inicial de PHP. Es como
un E_WARNING, excepto que es generado por
el núcleo de PHP.
| a partir de PHP 4 | | 64 |
E_COMPILE_ERROR
(integer)
|
Errores fatales en tiempo de compilación. Es como un
E_ERROR, excepto que es generado por el
Motor de Scripting de Zend.
| a partir de PHP 4 | | 128 |
E_COMPILE_WARNING
(integer)
|
Advertencias en tiempo de compilación (errores no
fatales). Es como un E_WARNING, excepto que
es generado por el Motor de Scripting de Zend.
| a partir de PHP 4 | | 256 |
E_USER_ERROR
(integer)
|
Mensaje de error generado por el usuario. Es como un
E_ERROR, excepto que es generado desde
código PHP usando la función
trigger_error().
| a partir de PHP 4 | | 512 |
E_USER_WARNING
(integer)
|
Mensaje de advertencia generado por el usuario. Es como un
E_WARNING, excepto que es generado desde
código PHP usando la función
trigger_error().
| a partir de PHP 4 | | 1024 |
E_USER_NOTICE
(integer)
|
Anotación generada por el usuario. Es como un
E_NOTICE, excepto que es generado desde
código PHP usando la función
trigger_error().
| a partir de PHP 4 | | 2047 |
E_ALL
(integer)
|
Todos los errores y advertencias, en la medida en que sean
soportados, excepto por el nivel E_STRICT.
| | | 2048 |
E_STRICT
(integer)
|
Noticias de tiempo de ejecución. Habilite este valor para
hacer que PHP sugiera cambios en su código que
velarán por la mejor interoperabilidad y por mantener la
compatibilidad de su código.
| a partir de PHP 5 |
Los valores referidos anteriormente (ya sean numéricos o
simbólicos) son usados para construir una máscara de
bits que indica cuáles errores reportar. Puede usar los
operadores bit a
bit para combinar estos valores o excluir
explícitamente ciertos tipos de errores. Sin embargo, note
que únicamente '|', '~', '!', '^' y '&' serán
entendidos desde php.ini, y que ningún operador bit a bit
será interpretado correctamente
desde php3.ini.
A continuación podemos apreciar un ejemplo del uso de las
capacidades de gestión de errores que vienen con
PHP. Definimos una función de manipulación de errores
que registra la información en un archivo (usando un formato
XML), y envía un correo electrónico al desarrollador
en caso de que un error crítico en la lógica del
software ocurra.
Ejemplo 1. Uso de gestión de errores en un script
<?php
// haremos nuestra propia manipulación de errores
error_reporting(0);
// funcion de gestion de errores definida por el usuario
function gestorDeErroresDeUsuario($num_err, $mens_err, $nombre_archivo,
$num_linea, $vars)
{
// marca de fecha/hora para el registro de error
$dt = date("Y-m-d H:i:s (T)");
// definir una matriz asociativa de cadenas de error
// en realidad las unicas entradas que deberiamos
// considerar son E_WARNING, E_NOTICE, E_USER_ERROR,
// E_USER_WARNING y E_USER_NOTICE
$tipo_error = array (
E_ERROR => "Error",
E_WARNING => "Advertencia",
E_PARSE => "Error de Intérprete",
E_NOTICE => "Anotación",
E_CORE_ERROR => "Error de Núcleo",
E_CORE_WARNING => "Advertencia de Núcleo",
E_COMPILE_ERROR => "Error de Compilación",
E_COMPILE_WARNING => "Advertencia de Compilación",
E_USER_ERROR => "Error de Usuario",
E_USER_WARNING => "Advertencia de Usuario",
E_USER_NOTICE => "Anotación de Usuario",
E_STRICT => "Anotación de tiempo de ejecución"
);
// conjunto de errores de los cuales se almacenara un rastreo
$errores_de_usuario = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
$err = "<errorentry>\n";
$err .= "\t<datetime>" . $dt . "</datetime>\n";
$err .= "\t<errornum>" . $num_err . "</errornum>\n";
$err .= "\t<errortype>" . $tipo_error[$num_err] . "</errortype>\n";
$err .= "\t<errormsg>" . $mens_err . "</errormsg>\n";
$err .= "\t<scriptname>" . $nombre_archivo . "</scriptname>\n";
$err .= "\t<scriptlinenum>" . $num_linea . "</scriptlinenum>\n";
if (in_array($num_err, $errores_de_usuario)) {
$err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
}
$err .= "</errorentry>\n\n";
// para efectos de debug
// echo $err;
// guardar en el registro de errores, y enviar un correo
// electrónico si hay un error crítico de usuario
error_log($err, 3, "/usr/local/php4/error.log");
if ($num_err == E_USER_ERROR) {
mail("phpdev@example.com", "Error Crítico de Usuario", $err);
}
}
function distancia($vect1, $vect2)
{
if (!is_array($vect1) || !is_array($vect2)) {
trigger_error("Parámetros incorrectos, se esperan matrices", E_USER_ERROR);
return NULL;
}
if (count($vect1) != count($vect2)) {
trigger_error("Los vectores deben ser del mismo tamaño", E_USER_ERROR);
return NULL;
}
for ($i=0; $i<count($vect1); $i++) {
$c1 = $vect1[$i]; $c2 = $vect2[$i];
$d = 0.0;
if (!is_numeric($c1)) {
trigger_error("La coordenada $i en el vector 1 no es un ".
"número, se usará cero",
E_USER_WARNING);
$c1 = 0.0;
}
if (!is_numeric($c2)) {
trigger_error("La coordenada $i en el vector 2 no es un".
"número, se usará cero",
E_USER_WARNING);
$c2 = 0.0;
}
$d += $c2*$c2 - $c1*$c1;
}
return sqrt($d);
}
$gestor_de_errores_anterior = set_error_handler("gestorDeErroresDeUsuario");
// constante indefinida, se genera una advertencia
$t = NO_ESTOY_DEFINIDA;
// definir algunos "vectores"
$a = array(2, 3, "foo");
$b = array(5.5, 4.3, -1.6);
$c = array(1, -3);
// generar un error de usuario
$t1 = distance($c, $b) . "\n";
// generar otro error de usuario
$t2 = distance($b, "no soy una matriz") . "\n";
// generar una advertencia
$t3 = distance($a, $b) . "\n";
?>
|
|
|
