<?xml version="1.0" encoding="utf-8"?>
 <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>send an error message somewhere</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     Sends an error message to the web server's error log, a
     <acronym>TCP</acronym> port or to a file.  The first parameter,
     <parameter>message</parameter>, is the error message that should
     be logged.  The second parameter,
     <parameter>message_type</parameter> says where the message should
     go:
     <table>
      <title><function>error_log</function> log types</title>
      <tgroup cols="2">
       <tbody>
    <row>
     <entry>0</entry>
     <entry>
      <parameter>message</parameter> is sent to PHP's system
      logger, using the Operating System's system logging
      mechanism or a file, depending on what the <link
      linkend="ini.error-log">error_log</link> configuration
      directive is set to.
     </entry>
    </row>
    <row>
     <entry>1</entry>
     <entry>
      <parameter>message</parameter> is sent by email to the
      address in the <parameter>destination</parameter> parameter.
      This is the only message type where the fourth parameter,
      <parameter>extra_headers</parameter> is used.  This message
      type uses the same internal function as
      <function>mail</function> does.
     </entry>
    </row>
    <row>
     <entry>2</entry>
     <entry>
      <parameter>message</parameter> is sent through the PHP debugging
      connection.  This option is only available if <link
      linkend="install.configure.enable-debugger">remote debugging has
      been enabled</link>.  In this case, the
      <parameter>destination</parameter> parameter specifies the host
      name or IP address and optionally, port number, of the socket
      receiving the debug information.
     </entry>
    </row>
    <row>
     <entry>3</entry>
     <entry>
      <parameter>message</parameter> is appended to the file
      <parameter>destination</parameter>.
     </entry>
    </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     <example role="php">
      <title><function>error_log</function> examples</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>set which PHP errors are reported</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>error_reporting</methodname>
      <methodparam choice="opt"><type>int</type><parameter>level</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sets PHP's error reporting level and returns the old level.  The
     error reporting level is either a bitmask, or named constant. Using
     named constants is strongly encouraged to ensure compatibility for
     future versions. As error levels are added, the range of integers
     increases, so older integer-based error levels will not always
     behave as expected.
     <example role="php">
      <title>Error Integer changes</title>
      <programlisting role="php">
error_reporting (55);   // PHP 3 equivalent to E_ALL ^ E_NOTICE

/* ...in PHP 4, '55' would mean (E_ERROR | E_WARNING | E_PARSE |
E_CORE_ERROR | E_CORE_WARNING) */

error_reporting (2039); // PHP 4 equivalent to E_ALL ^ E_NOTICE

error_reporting (E_ALL ^ E_NOTICE); // The same in both PHP 3 and 4
      </programlisting>
     </example>
     Follow the links for the internal values to get their meanings:
     <table>
      <title><function>error_reporting</function> bit values</title>
      <tgroup cols="2">
       <thead>
	<row>
	 <entry>constant</entry>
	 <entry>value</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>
	<row>
	 <entry>64</entry>
	 <entry>
	  <link linkend="internal.e-compile-error">E_COMPILE_ERROR</link>
	 </entry>
	</row>
	<row>
	 <entry>128</entry>
	 <entry>
	  <link linkend="internal.e-compile-warning">E_COMPILE_WARNING</link>
	 </entry>
	</row>
	<row>
	 <entry>256</entry>
	 <entry>
	  <link linkend="internal.e-user-error">E_USER_ERROR</link>
	 </entry>
	</row>
	<row>
	 <entry>512</entry>
	 <entry>
	  <link linkend="internal.e-user-warning">E_USER_WARNING</link>
	 </entry>
	</row>
	<row>
	 <entry>1024</entry>
	 <entry>
	  <link linkend="internal.e-user-error">E_USER_NOTICE</link>
	 </entry>
	</row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     <example role="php">
      <title><function>error_reporting</function> examples</title>
      <programlisting role="php">
error_reporting(0);
/* Turn off all reporting */

error_reporting (7); // Old syntax, PHP 2/3
error_reporting  (E_ERROR | E_WARNING | E_PARSE); // New syntax for PHP 3/4
/* Good to use for simple running errors  */

error_reporting  (15); // Old syntax, PHP 2/3
error_reporting (E_ERROR | E_WARNING | E_PARSE | E_NOTICE); // New syntax for PHP 3/4
/*  good for code authoring to report uninitialized or (possibly mis-spelled) variables */

error_reporting (63); // Old syntax, PHP 2/3
error_reporting (E_ALL); // New syntax for PHP 3/4
/* report all PHP errors */
      </programlisting>
     </example>
    </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. From PHP 4.0.2, an additional 3 optional
     parameters are supplied: the filename in which the error occured, the
     line number in which the error occured, and the context in which the
     error occured (an array that points to the active symbol table at the
     point the error occurred).
    </para>
    <para>
     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 - PHP 4 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, $errfile, $errline) {
  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;.$errline.&quot; of file &quot;.$errfile;
    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 36 of file trigger_error.php, PHP 4.0.2 (Linux)&lt;br&gt;
Aborting...&lt;br&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     It is important to remember that the standard PHP error handler is completely
     bypassed. <function>error_reporting</function> settings will have no effect
     and your error handler will be called regardless - however you are still
     able to read the current value of <function>error_reporting</function> and
     act appropriately. Of particular note is that this value will be 0 if the
     statement that caused the error was prepended by the
     <link linkend="language.operators.errorcontrol">@ error-control
     operator</link>.
    </para>
    <para>
     Also note that it is your responsibility to <function>die</function> if
     necessary. If the error-handler function returns, script execution
     will continue with the next statement after the one that caused an error.
    </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>). It only works with the E_USER
     family of constants, and will default to <constant>E_USER_NOTICE</constant>.
    </para>
    <para>
      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:
-->