archived-doc-es/reference/errorfunc/functions/set-error-handler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.6 $ -->
<!-- EN-Revision: 1.33 Maintainer: lboshell Status: ready -->
<!-- splitted from ./en/functions/errorfunc.xml, last change in rev 1.1 -->
<refentry id="function.set-error-handler">
 <refnamediv>
  <refname>set_error_handler</refname>
  <refpurpose>
   Establece una función de gestión de errores definida por el usuario
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>set_error_handler</methodname>
   <methodparam><type>callback</type><parameter>gestor_errores</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>tipos_error</parameter></methodparam>
  </methodsynopsis>
  <para>
   Establece una función de usuario
   (<parameter>gestor_errores</parameter>) para manejar los errores en
   un script.
  </para>
  <para>
   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
   <function>trigger_error</function>).
  </para>
  <para>
   Es importante recordar que el gestor de errores estándar de PHP es
   completamente ignorado. Los parámetros de
   <function>error_reporting</function> no tendrán efecto alguno y su
   gestor de errores será llamado en cualquier circunstancia - sin
   embargo es posible leer el valor actual de <link
   linkend="ini.error-reporting">error_reporting</link> y actuar
   apropiadamente. Es particularmente importante notar que este valor
   será 0 si la sentencia que causó el error fue precedida por el
   <link linkend="language.operators.errorcontrol">operador de control
   de errores @</link>.
  </para>
  <para>
   Note también que es su responsabilidad usar
   <function>die</function> 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.
  </para>
  <para>
   Los siguientes tipos de error no pueden ser gestionados con una
   función definida por el usuario: <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>, y la mayoría de
   <constant>E_STRICT</constant> generados en el archivo en donde
   <function>set_error_handler</function> es llamado.
  </para>
  <para>
   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.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>gestor_errores</parameter></term>
     <listitem>
      <para>
       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:
      </para>
      <para>
       <methodsynopsis>
        <methodname><replaceable>gestor</replaceable></methodname>
        <methodparam><type>int</type><parameter>num_err</parameter></methodparam>
        <methodparam><type>string</type><parameter>cadena_err</parameter></methodparam>
        <methodparam choice="opt"><type>string</type><parameter>archivo_err</parameter></methodparam>
        <methodparam choice="opt"><type>int</type><parameter>linea_err</parameter></methodparam>
        <methodparam choice="opt"><type>array</type><parameter>contexto_err</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>num_err</parameter></term>
         <listitem>
          <simpara>
           El primer parámetro, <parameter>num_err</parameter>,
           contiene el nivel del error generado, como un entero.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>cadena_err</parameter></term>
         <listitem>
          <simpara>
           El segundo parámetro, <parameter>cadena_err</parameter>,
           contiene el mensaje de error, como una cadena.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>archivo_err</parameter></term>
         <listitem>
          <simpara>
           El tercer parámetro es opcional,
           <parameter>archivo_err</parameter>, el cual contiene el
           nombre del archivo en el que se generó el error, como una
           cadena.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>linea_err</parameter></term>
         <listitem>
          <simpara>
           El cuarto parámetro es opcional,
           <parameter>linea_err</parameter>, el cual contiene el
           número de línea en la que se generó el error, como un
           entero.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>contexto_err</parameter></term>
         <listitem>
          <simpara>
           El quinto parámetro es opcional,
           <parameter>contexto_err</parameter>, 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,
           <parameter>contexto_err</parameter> 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.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>tipos_error</parameter></term>
     <listitem>
      <para>
       Puede ser usado para aplicar una máscara a las llamadas de la
       función <parameter>error_handler</parameter> tal y como el
       parámetro ini <link
       linkend="ini.error-reporting">error_reporting</link> controla
       qué errores son mostrados. Sin esta máscara definida, el
       <parameter>gestor_errores</parameter> será llamado para cada
       error sin importar el valor del parámetro <link
       linkend="ini.error-reporting">error_reporting</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   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.
  </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>5.0.0</entry>
       <entry>
        Se introdujo el parámetro
        <parameter>tipos_error</parameter>.
       </entry>
      </row>
      <row>
       <entry>4.3.0</entry>
       <entry>
        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 <parameter>gestor_errores</parameter>.
       </entry>
      </row>
      <row>
       <entry>4.0.2</entry>
       <entry>
        Se introdujeron tres parámetros opcionales para la función de
        usuario <parameter>gestor_errores</parameter>. Estos son el
        nombre de archivo, el número de línea, y el contexto.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Gestión de errores con
    <function>set_error_handler</function> y
    <function>trigger_error</function></title>
    <para>
     El siguiente ejemplo muestra la gestión de excepciones internas
     generando errores y manejándolos con una función definida por el
     usuario:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// definir el nivel de reporte de errores para este script
error_reporting(E_USER_ERROR | E_USER_WARNING | E_USER_NOTICE);

// función de gestión 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 línea $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;
  }
}

// función para probar la gestión de errores
function escalar_por_log($vect, $escala)
{
  if (!is_numeric($escala) || $escala <= 0) {
    trigger_error("log(x) para x <= 0 es indefinido, usted usó: 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 posición $i no es un número, 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 ítem no-numérico
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 crítico, log de cero o un número negativo es indefinido
echo "----\nvector d - error fatal\n";
$d = escalar_por_log($a, -2.5);

?>
]]>
    </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 - a advertencia (b = log(PI) * a)
<b>Mi NOTICIA</b> [1024] El valor en la posición 2 no es un número, 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 usó: escala = -2.5<br />
  Error fatal en la línea 32 del archivo generar_error.php, PHP 5.0.4 (Linux)<br />
Abortando...<br />
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>error_reporting</function></member>
    <member><function>restore_error_handler</function></member>
    <member><function>trigger_error</function></member>
    <member><link linkend="errorfunc.constants">constantes de nivel de
    error</link></member>
    <member>&seealso.callback;</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:"../../../../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
-->