<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: 21ce7d7f4f9f6f241f3e09e7f0a5be5c504d90d2 Maintainer: PhilDaiguille Status: ready -->

<!-- Reviewed: no -->

<refentry xml:id="function.set-error-handler" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>set_error_handler</refname>

<refpurpose>Especifica una función de usuario como gestor de errores</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>callable</type><type>null</type></type><methodname>set_error_handler</methodname>

<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>error_levels</parameter><initializer><constant>E_ALL</constant></initializer></methodparam>

</methodsynopsis>

<para>

<function>set_error_handler</function> selecciona la función de usuario

<parameter>callback</parameter> para gestionar errores en un script.

</para>

<para>

Esta función puede ser utilizada para definir gestores de errores personalizados durante la ejecución,

por ejemplo en aplicaciones que necesitan limpiar archivos/datos cuando ocurre un error crítico

o cuando un error es generado en respuesta a ciertas condiciones

(utilizando la función <function>trigger_error</function>).

</para>

<para>

Debe recordarse que la función estándar de tratamiento de errores

de PHP es completamente ignorada para los errores de tipos

especificados por <parameter>error_levels</parameter> a menos que la función de retorno devuelva &false;.

Los parámetros de la función <function>error_reporting</function> no tendrán efecto

y el gestor de errores será llamado en cualquier caso. Sin embargo, siempre es posible

leer el valor actual de la configuración de

<link linkend="ini.error-reporting">error_reporting</link> y

hacer que la función de gestión de errores reaccione en consecuencia.

</para>

<para>

También debe notarse que es responsabilidad del gestor de errores detener

la ejecución del script si es necesario llamando a la función <function>exit</function>. Si la función del gestor de errores devuelve,

la ejecución del script continuará con la instrucción siguiente a la que causó el error.

</para>

<para>

Los siguientes tipos de errores no pueden ser gestionados con esta función:

<constant>E_ERROR</constant>, <constant>E_PARSE</constant>,

<constant>E_CORE_ERROR</constant>, <constant>E_CORE_WARNING</constant>,

<constant>E_COMPILE_ERROR</constant>,

<constant>E_COMPILE_WARNING</constant> independientemente de dónde sean generados,

así como la mayoría de los

<constant>E_STRICT</constant> del archivo en el cual

<function>set_error_handler</function> es llamado.

</para>

<para>

Si un error ocurre antes de que el script sea ejecutado (por ejemplo

una descarga de archivo), el gestor de errores personalizado no podrá

ser llamado, ya que aún no está registrado.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>callback</parameter></term>

<listitem>

<para>

Si &null; es proporcionado, el gestor es reestablecido a su estado por defecto.

De lo contrario, el gestor es una función de retorno con la siguiente firma:

</para>

<para>

<methodsynopsis>

<type>bool</type><methodname><replaceable>handler</replaceable></methodname>

<methodparam><type>int</type><parameter>errno</parameter></methodparam>

<methodparam><type>string</type><parameter>errstr</parameter></methodparam>

<methodparam choice="opt"><type>string</type><parameter>errfile</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>errline</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>errcontext</parameter></methodparam>

</methodsynopsis>

<variablelist>

<varlistentry>

<term><parameter>errno</parameter></term>

<listitem>

<simpara>

El primer parámetro <parameter>errno</parameter>, será pasado el

nivel de error, en forma de entero.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errstr</parameter></term>

<listitem>

<simpara>

El segundo parámetro <parameter>errstr</parameter>, será pasado el

mensaje de error, en forma de string.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errfile</parameter></term>

<listitem>

<simpara>

Si el cierre acepta un tercer parámetro, <parameter>errfile</parameter>,

será pasado el nombre del archivo en el cual el error fue identificado, en forma de string.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errline</parameter></term>

<listitem>

<simpara>

Si el cierre acepta un cuarto parámetro, <parameter>errline</parameter>,

será pasado el número de línea en la cual el error fue identificado, en forma de entero.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errcontext</parameter></term>

<listitem>

<simpara>

Si el cierre acepta un quinto parámetro, <parameter>errcontext</parameter>,

será pasado como un array que apunta a la tabla de símbolos activos en

el momento en que el error ocurrió. En otras palabras, <parameter>errcontext</parameter>

contiene un array con todas las variables que existían cuando

el error fue generado.

Los gestores de errores de usuario no deben modificar el contexto de error.

</simpara>

<warning xmlns="http://docbook.org/ns/docbook">

<simpara>

Este parámetro es <emphasis>OBSOLETO</emphasis> a partir de PHP 7.2.0,

y <emphasis>ELIMINADO</emphasis> a partir de PHP 8.0.0. Si la

función definida este parámetro sin valor por defecto, un error de

"too few arguments" será generado al llamarla.

</simpara>

</warning>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

Si la función devuelve &false;, entonces el gestor de errores normal continúa.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>error_levels</parameter></term>

<listitem>

<para>

Sirve como máscara para llamar a la función

<parameter>callback</parameter> de la misma forma que la opción de

configuración <link linkend="ini.error-reporting">error_reporting</link>

controla los errores que son mostrados. Sin la máscara,

<parameter>callback</parameter> será llamado para todos los errores,

independientemente del valor de

<link linkend="ini.error-reporting">error_reporting</link>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Devuelve el último gestor de errores (si existe) en forma de <type>callable</type>.

Si el gestor de errores interno es utilizado, &null; es devuelto.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>errcontext</parameter> ha sido eliminado, y ya no será pasado a los cierres de usuario.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

<parameter>errcontext</parameter> se ha vuelto obsoleto.

El uso de este parámetro emite una notificación <constant>E_DEPRECATED</constant>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Gestor de errores con <function>set_error_handler</function> y

<function>trigger_error</function></title>

<para>

El ejemplo siguiente ilustra la intercepción de errores internos con

generación de error y su explotación en una función de usuario:

</para>

<programlisting role="php">

<![CDATA[

<?php

// Gestor de errores

function myErrorHandler($errno, $errstr, $errfile, $errline)

{

if (!(error_reporting() & $errno)) {

// Este código de error no está incluido en error_reporting(), por lo tanto continúa

// hasta el gestor de errores estándar de PHP

return false;

}

// $errstr debe ser posiblemente escapado:

$errstr = htmlspecialchars($errstr);

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 "Detención...<br />\n";

exit(1);

case E_USER_WARNING:

echo "<b>MI ALERTA</b> [$errno] $errstr<br />\n";

break;

case E_USER_NOTICE:

echo "<b>MI AVISO</b> [$errno] $errstr<br />\n";

break;

default:

echo "Tipo de error desconocido: [$errno] $errstr<br />\n";

break;

}

/* No ejecutar el gestor interno de PHP */

return true;

}

// Función para probar la gestión de error

function scale_by_log($vect, $scale)

{

if (!is_numeric($scale) || $scale <= 0) {

trigger_error("log(x) para x <= 0 es indefinido, usted usó: scale = $scale", E_USER_ERROR);

}

if (!is_array($vect)) {

trigger_error("Tipo de entrada incorrecto, se esperaba un array de valores", E_USER_WARNING);

return null;

}

$temp = array();

foreach($vect as $pos => $value) {

if (!is_numeric($value)) {

trigger_error("El valor en la posición $pos no es un número, se utiliza 0 (cero)", E_USER_NOTICE);

$value = 0;

}

$temp[$pos] = log($scale) * $value;

}

return $temp;

}

// Configuración del gestor de errores

$old_error_handler = set_error_handler("myErrorHandler");

// Generación de algunos errores. Comencemos creando un array

echo "vector a\n";

$a = array(2, 3, "foo", 5.5, 43.3, 21.11);

print_r($a);

// Generemos ahora un segundo array

echo "----\nvector b - un aviso (b = log(PI) * a)\n";

/* Valor en la posición $pos no es un número, se utiliza 0 (cero) */

$b = scale_by_log($a, M_PI);

print_r($b);

// Esto es un problema, hemos utilizado una cadena en lugar de un array

echo "----\nvector c - una advertencia\n";

/* Tipo de entrada incorrecto, se esperaba un array de valores */

$c = scale_by_log("no un array", 2.3);

var_dump($c); // NULL

// Esto es un error crítico: el logaritmo de cero o de un número negativo es indefinido

echo "----\nvector d - error fatal\n";

/* log(x) para x <= 0 es indefinido, usted usó: scale = $scale" */

$d = scale_by_log($a, -2.5);

var_dump($d); // Nunca alcanzado

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

vector a

Array

(

[0] => 2

[1] => 3

[2] => foo

[3] => 5.5

[4] => 43.3

[5] => 21.11

)

----

vector b - un aviso (b = log(PI) * a)

<b>MI AVISO</b> [1024] El valor en la posición 2 no es un número, se utiliza 0 (cero)<br />

Array

(

[0] => 2.2894597716988

[1] => 3.4341896575482

[2] => 0

[3] => 6.2960143721717

[4] => 49.566804057279

[5] => 24.165247890281

)

----

vector c - una advertencia

<b>MI ALERTA</b> [512] Entrada incorrecta, se esperaba un array de valores<br />

NULL

----

vector d - error fatal

<b>MI ERROR</b> [256] log(x) para x <= 0 es indefinido, usted usó: scale = -2.5<br />

Error fatal en la línea 36 en el archivo trigger_error.php, PHP 4.0.2 (Linux)<br />

Abandono...<br />

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><classname>ErrorException</classname></member>

<member><function>error_reporting</function></member>

<member><function>restore_error_handler</function></member>

<member><function>get_error_handler</function></member>

<member><function>trigger_error</function></member>

<member><link linkend="errorfunc.constants">Constantes de nivel de error</link></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->