<?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>Sendet eine Fehlermeldung</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</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>
     Sendet eine Fehlermeldung an das Log-File des Webservers, einen
     <acronym>TCP</acronym> Port oder eine Datei. Der erste Parameter,
     <parameter>message</parameter>, ist die Fehlermeldung, die
     mitgeschrieben werden soll.  Der zweite Parameter,
     <parameter>message_type</parameter> gibt an, wo die Meldung
     abgelegt werden soll:
     <table>
      <title><function>error_log</function> Typem</title>
      <tgroup cols="2">
       <tbody>
	<row>
	 <entry>0</entry>
	 <entry>
	  <parameter>Message</parameter> wird mit Hilfe des internen
	  Log-Systems des Betriebssystemes oder einer Datei
	  geschrieben, je nachdem, wie <link
	  linkend="ini.error-log">error_log</link> eingestellt ist.
	 </entry>
	</row>
	<row>
	 <entry>1</entry>
	 <entry>
	  <parameter>Message</parameter> wird via Email an die Adresse
	  gesendet, die mit <parameter>destination</parameter>
	  amnngegeben wurde.  Dies ist der einzige Punkt, bei dem der
	  vierte Parameter <parameter>extra_headers</parameter>
	  verwendet wird.  Die Nachricht verwendet die selbe interne
	  Funktion wie <function>mail</function>.
	 </entry>
	</row>
	<row>
	 <entry>2</entry>
	 <entry>
	  <parameter>Message</parameter> wird ber den PHP-Debugger
	  gesendet. Diese Option ist nur verfgbar, wenn <link
	  linkend="install.configure.enable-debugger">der Debugger gestartet
	  wurde</link>. Ist das der Fall, so wird mit dem
	  <parameter>destination</parameter> Parameter der Hostname
	  oder die IP-Adresse gesetzt. Optional auch der Port, unter
	  dem der Debugger luft.
	 </entry>
	</row>
	<row>
	 <entry>3</entry>
	 <entry>
	  <parameter>Message</parameter> wird an die Datei angefgt,
	  die mit <parameter>destination</parameter> angegeben wurde.
	 </entry>
	</row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     <example>
      <title><function>error_log</function> Beispiele</title>
      <programlisting role="php">
// Server sendet eine Nachricht an den Administrator,
// da keine Verbindung zur Datenbank mglich ist.
if (!Ora_Logon($username, $password)) {
    error_log ("Oracle database not available!", 0);
}

// Server sendet eine Nachricht an den Administrator, da FOO langsam ausgeht
if (!($foo = allocate_new_foo()) {
    error_log ("Big trouble, we're all out of FOOs!", 1,
               "operator@mydomain.com");
}

// AndereMglichkeiten, error_log() aufzurufen:
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>
     Gibt an, wie PHP-Fehlermeldungen gezeigt werden
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>error_reporting</methodname>
      <methodparam choice="opt"><type>int</type><parameter>level</parameter></methodparam>
     </methodsynopsis>
    <para>
     Setzt die Stufe von PHP's Fehlermeldungen. Diese Stufe ist der
     Fehlermeldung hngt von den folgenden Werten ab.  (Hinter den
     folgenden Links verbirgt sich die Bedeutung der internen Werte):
     <table>
      <title><function>error_reporting</function> Werte</title>
      <tgroup cols="2">
       <thead>
	<row>
	 <entry>Werte</entry>
	 <entry>interne Namen</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>, 
     <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:
-->