set-error-handler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: cbfc5d5d55d682c185583561295462a6d5ca0ea1 Maintainer: PhilDaiguille Status: ready -->
<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>
  <simpara>
   Define una función de usuario (<parameter>callback</parameter>) para
   gestionar los errores de un script.
   El gestor que estaba activo hasta ese momento se guarda en una pila interna
   de gestores de errores, de la cual <function>restore_error_handler</function>
   lo vuelve a extraer.
  </simpara>
  <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>
      <simpara>
       Si se proporciona &null;, no queda activo ningún gestor definido por el
       usuario y los errores vuelven al gestor de errores interno.
       El gestor que estaba activo hasta ese momento sigue guardado en la pila y
       puede recuperarse con <function>restore_error_handler</function>.
       De lo contrario, el gestor es una función de retorno con la siguiente firma:
      </simpara>
      <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>
  <para>
   <example>
    <title>Llamada al gestor anterior desde el nuevo</title>
    <simpara>
     El valor devuelto por <function>set_error_handler</function> es el gestor
     que estaba activo hasta ese momento. Llamarlo desde el nuevo gestor
     conserva el comportamiento existente y le añade el nuevo. Esto solo
     funciona si ese gestor es una función definida por el usuario; se devuelve
     &null; cuando el gestor activo era el interno.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
function logging_handler(int $errno, string $errstr): bool
{
    echo "registrado: $errstr\n";
    return true;
}

set_error_handler('logging_handler');

$previous = set_error_handler(function (int $errno, string $errstr) use (&$previous): bool {
    echo "contado: $errstr\n";
    return $previous !== null ? $previous($errno, $errstr) : false;
});

trigger_error("ha ocurrido algo", E_USER_WARNING);

restore_error_handler();
trigger_error("ahora solo registrado", E_USER_WARNING);

restore_error_handler();
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
contado: ha ocurrido algo
registrado: ha ocurrido algo
registrado: ahora solo registrado
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <caution>
   <simpara>
    No se debe volver al gestor anterior pasando de nuevo a
    <function>set_error_handler</function> el valor que esta devolvió.
    Al hacerlo se añade una entrada más a la pila en lugar de retirar una, por
    lo que la pila crece sin límite en los bucles y en los procesos de larga
    duración, y <parameter>error_levels</parameter> se reinicia a
    <constant>E_ALL</constant>, ampliando de forma silenciosa el rango de
    errores que recibe el gestor restaurado.
    <function>restore_error_handler</function> es la forma prevista de volver
    al gestor anterior.
   </simpara>
  </caution>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><exceptionname>ErrorException</exceptionname></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>
 </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
-->