<?xml version="1.0" encoding="iso-8859-1"?>
 <reference id="ref.errorfunc">
  <title>Error Handling and Logging Functions</title>
  <titleabbrev>Errors and Logging</titleabbrev>

  <partintro>
   <para>
    These are functions dealing with error handling and logging. They
    allow you to define your own error handling rules, as well as modify
    the way the errors can be logged. This allows you to change and
    enhance error reporting to suit your needs.
   </para>
   <para> 
    With the logging functions, you can send messages directly to other
    machines, to an email (or email to pager gateway!), to system logs,
    etc., so you can selectively log and monitor the most important parts
    of your applications and websites.
   </para>
   <para> 
    The error reporting functions allow you to customize what level and
    kind of error feedback is given, ranging from simple notices to customized
    functions returned during errors. 
   </para>
  </partintro>

  <refentry id="function.error-log">
   <refnamediv>
    <refname>error_log</refname>
    <refpurpose>env&iacute;a un mensaje de error a alg&uacute;n lugar</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>error_log</methodname>
     <methodparam><type>string</type><parameter>message</parameter></methodparam>
     <methodparam><type>int</type><parameter>message_type</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>destination</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>extra_headers</parameter></methodparam>
     </methodsynopsis>
    <para>
     Env&iacute;a un mensaje de error al log de errores del servidor web, a 
     un puerto <acronym>TCP</acronym> o a un fichero. El primer par&aacute;metro,
     <parameter>message</parameter> (mensaje), es el mensaje de error 
     que debe ser registrado. El segundo par&aacute;metro, <parameter>message_type</parameter> 
     (tipo de mensaje) indica el lugar al que debe dirigirse:
     <table>
      <title><function>error_log</function> tipos de log</title>
      <tgroup cols="2">
       <tbody>
	<row>
	 <entry>0</entry>
	 <entry>
	  <parameter>message</parameter> es enviado al registro de sistema 
          de PHP, utilizando el mecanismo de registro de sistema del Sistema
          Operativo, o a un fichero, dependiendo del valor de la directiva de
          configuraci&oacute;n <link linkend="ini.error-log">error_log</link>
	 </entry>
	</row>
	<row>
	 <entry>1</entry>
	 <entry>
	  <parameter>message</parameter> es enviado por correo electr&oacute;nico 
          a la direcci&oacute;n del par&aacute;metro <parameter>destination</parameter> 
          (destino). Este es el &uacute;nico tipo de mensaje donde se utiliza 
          el cuarto par&aacute;metro, <parameter>extra_headers</parameter>. Este 
          tipo de mensaje utiliza la misma funcionalidad interna que 
          <function>mail</function> realiza.
	 </entry>
	</row>
	<row>
	 <entry>2</entry>
	 <entry>
	  <parameter>message</parameter> es enviado a trav&eacute;s de la conexi&oacute;n
          de depuraci&oacute;n de PHP. Esta opci&oacute;n est&aacute; disponible s&oacute;lo si 
	  <link linkend="enable-debugger">la depuraci&oacute;n remota ha sido 
          activada</link>. En este caso el par&aacute;metro 
          <parameter>destination</parameter> especifica el nombre de host
          o direcci&oacute;n IP y, opcionalmente, el n&uacute;mero de puerto del
          socket que recibe la informaci&oacute;n de depuraci&oacute;n.
	 </entry>
	</row>
	<row>
	 <entry>3</entry>
	 <entry>
	  <parameter>message</parameter> es a&ntilde;adido al fichero 
	  <parameter>destination</parameter>.
	 </entry>
	</row>
       </tbody>
      </tgroup>
     </table></para>
    <para>
     <example>
      <title><function>error_log</function> ejemplos</title>
      <programlisting role="php">
// Send notification through the server log if we can not
// connect to the database.
if (!Ora_Logon($username, $password)) {
    error_log("Oracle database not available!", 0);
}

// Notify administrator by email if we run out of FOO
if (!($foo = allocate_new_foo()) {
    error_log("Big trouble, we're all out of FOOs!", 1,
              "operator@mydomain.com");
}

// other ways of calling error_log():
error_log("You messed up!", 2, "127.0.0.1:7000");
error_log("You messed up!", 2, "loghost");
error_log("You messed up!", 3, "/var/tmp/my-errors.log");
</programlisting>
     </example></para>
   </refsect1>
  </refentry>

  <refentry id="function.error-reporting">
   <refnamediv>
    <refname>error_reporting</refname>
    <refpurpose>establece que errores PHP son registrados</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>error_reporting</methodname>
     <methodparam choice="opt"><type>int</type><parameter>level</parameter></methodparam>
     </methodsynopsis>
    <para>
     Establece el nivel de registro de los errores PHP y devuelve el nivel
     anterior. El nivel de registro es una m&aacute;scara de bits de los valores
     siguientes (siga los enlaces a los valores internos para obtener sus
     significados):
     <table>
      <title><function>error_reporting</function> valores de bit</title>
      <tgroup cols="2">
       <thead>
	<row>
	 <entry>valor</entry>
	 <entry>nombre interno</entry>
	</row>
       </thead>
       <tbody>
	<row>
	 <entry>1</entry>
	 <entry><link linkend="internal.e-error">E_ERROR</link></entry>
	</row>
	<row>
	 <entry>2</entry>
	 <entry><link linkend="internal.e-warning">E_WARNING</link></entry>
	</row>
	<row>
	 <entry>4</entry>
	 <entry><link linkend="internal.e-parse">E_PARSE</link></entry>
	</row>
	<row>
	 <entry>8</entry>
	 <entry><link linkend="internal.e-notice">E_NOTICE</link></entry>
	</row>
	<row>
	 <entry>16</entry>
	 <entry><link linkend="internal.e-core-error">E_CORE_ERROR</link></entry>
	</row>
	<row>
	 <entry>32</entry>
	 <entry><link linkend="internal.e-core-warning">E_CORE_WARNING</link></entry>
	</row>
       </tbody>
      </tgroup>
     </table></para>
   </refsect1>
  </refentry>

  <refentry id="function.restore-error-handler">
   <refnamediv>
    <refname>restore_error_handler</refname>
    <refpurpose>
     Restores the previous error handler function
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>restore_error_handler</methodname>
      <void/>
     </methodsynopsis>
    <para>
     Used after changing the error handler function using
     <function>set_error_handler</function>, to revert to the previous error
     handler (which could be the built-in or a user defined function)
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>trigger_error</function>, <function>user_error</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.set-error-handler">
   <refnamediv>
    <refname>set_error_handler</refname>
    <refpurpose>
     Sets a user-defined error handler function.  
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>set_error_handler</methodname>
      <methodparam><type>string</type><parameter>error_handler</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sets a user function (<parameter>error_handler</parameter>) to handle
     errors in a script.  Returns the previously defined error handler (if
     any), or &false; on error.  This function can be used for defining your own
     way of handling errors during runtime, for example in applications in
     which you need to do cleanup of data/files when a critical error happens,
     or when you need to trigger an error under certain conditions (using
     <function>trigger_error</function>)
    </para>
    <para>
     The user function needs to accept 2 parameters: the error code, and a
     string describing the error. The example below shows the handling of 
     internal execptions by triggering errors and handling them with a user
     defined function:
     <example>
      <title>
       Error handling with <function>set_error_handler</function> and
       <function>trigger_error</function>
      </title>
      <programlisting role="php">
&lt;?php

// redefine the user error constants - PHP4 only
define (FATAL,E_USER_ERROR);
define (ERROR,E_USER_WARNING);
define (WARNING,E_USER_NOTICE);

// set the error reporting level for this script
error_reporting  (FATAL + ERROR + WARNING);

// error handler function
function myErrorHandler ($errno, $errstr) {
    switch ($errno) {
    case FATAL:
    echo &quot;&lt;b&gt;FATAL&lt;/b&gt; [$errno] $errstr&lt;br&gt;\n&quot;;
    echo &quot;  Fatal error in line &quot;.__LINE__.&quot; of file &quot;.__FILE__;
    echo &quot;, PHP &quot;.PHP_VERSION.&quot; (&quot;.PHP_OS.&quot;)&lt;br&gt;\n&quot;;
    echo &quot;Aborting...&lt;br&gt;\n&quot;;
    exit -1;
    break;
    case ERROR:
    echo &quot;&lt;b&gt;ERROR&lt;/b&gt; [$errno] $errstr&lt;br&gt;\n&quot;;
    break;
    case WARNING:
    echo &quot;&lt;b&gt;WARNING&lt;/b&gt; [$errno] $errstr&lt;br&gt;\n&quot;;
    break;
    default:
    echo &quot;Unkown error type: [$errno] $errstr&lt;br&gt;\n&quot;;
    break;
    }
}

// function to test the error handling
function scale_by_log ($vect, $scale) {
    if ( !is_numeric($scale) || $scale &lt;= 0 )
    trigger_error(&quot;log(x) for x &lt;= 0 is undefined, you used: scale = $scale&quot;, 
      FATAL);
    if (!is_array($vect)) {
    trigger_error(&quot;Incorrect input vector, array of values expected&quot;, ERROR);
    return null;
    }
    for ($i=0; $i&lt;count($vect); $i++) {
    if (!is_numeric($vect[$i]))
    trigger_error(&quot;Value at position $i is not a number, using 0 (zero)&quot;, 
      WARNING);
    $temp[$i] = log($scale) * $vect[$i];
    }
    return $temp;
}

// set to the user defined error handler
$old_error_handler = set_error_handler(&quot;myErrorHandler&quot;);

// trigger some errors, first define a mixed array with a non-numeric item
echo &quot;vector a\n&quot;;
$a = array(2,3,&quot;foo&quot;,5.5,43.3,21.11);
print_r($a);

// now generate second array, generating a warning
echo &quot;----\nvector b - a warning (b = log(PI) * a)\n&quot;;
$b = scale_by_log($a, M_PI);
print_r($b);

// this is trouble, we pass a string instead of an array
echo &quot;----\nvector c - an error\n&quot;;
$c = scale_by_log(&quot;not array&quot;,2.3);
var_dump($c);

// this is a critical error, log of zero or negative number is undefined
echo &quot;----\nvector d - fatal error\n&quot;;
$d = scale_by_log($a, -2.5);

?&gt;
      </programlisting>
     </example>
     And when you run this sample script, the output will be
     <informalexample>
      <programlisting>
vector a
Array
(
    [0] =&gt; 2
    [1] =&gt; 3
    [2] =&gt; foo
    [3] =&gt; 5.5
    [4] =&gt; 43.3
    [5] =&gt; 21.11
)
----
vector b - a warning (b = log(PI) * a)
&lt;b&gt;WARNING&lt;/b&gt; [1024] Value at position 2 is not a number, using 0 (zero)&lt;br&gt;
Array
(
    [0] =&gt; 2.2894597716988
    [1] =&gt; 3.4341896575482
    [2] =&gt; 0
    [3] =&gt; 6.2960143721717
    [4] =&gt; 49.566804057279
    [5] =&gt; 24.165247890281
)
----
vector c - an error
&lt;b&gt;ERROR&lt;/b&gt; [512] Incorrect input vector, array of values expected&lt;br&gt;
NULL
----
vector d - fatal error
&lt;b&gt;FATAL&lt;/b&gt; [256] log(x) for x &lt;= 0 is undefined, you used: scale = -2.5&lt;br&gt;
  Fatal error in line 16 of file trigger_error.php, PHP 4.0.1pl2 (Linux)&lt;br&gt;
Aborting...&lt;br&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>restore_error_handler</function>,
     <function>trigger_error</function>, <function>user_error</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.trigger-error">
   <refnamediv>
    <refname>trigger_error</refname>
    <refpurpose>
     Generates a user-level error/warning/notice message
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>trigger_error</methodname>
      <methodparam><type>string</type><parameter>error_msg</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>error_type</parameter></methodparam>
     </methodsynopsis>
    <para>
     Used to trigger a user error condition, it can be used by in conjunction
     with the built-in error handler, or with a user defined function that has
     been set as the new error handler
     (<function>set_error_handler</function>). This function is useful when
     you need to generate a particular response to an exception at runtime.
     For example:
     <informalexample>
      <programlisting>
if (assert ($divisor == 0))
   trigger_error ("Cannot divide by zero", E_USER_ERROR);
      </programlisting>
     </informalexample>
     <note>
     <para>
     See <function>set_error_handler</function> for a more extensive example.
     </para>
     </note>
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>restore_error_handler</function>, 
     <function>user_error</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.user-error">
   <refnamediv>
    <refname>user_error</refname>
    <refpurpose>
     Generates a user-level error/warning/notice message
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>user_error</methodname>
      <methodparam><type>string</type><parameter>error_msg</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>error_type</parameter></methodparam>
     </methodsynopsis>
    <para>
     This is an alias for the function <function>trigger_error</function>.
    </para>
    <para>
     See also <function>error_reporting</function>,
     <function>set_error_handler</function>,
     <function>restore_error_handler</function>, and
     <function>trigger_error</function>
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- 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:
-->