<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<!-- 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>
     Sets a user-defined error handler function.  
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>set_error_handler</methodname>
      <methodparam><type>callback</type><parameter>error_handler</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>error_types</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sets a user function (<parameter>error_handler</parameter>) to handle
     errors in a script. Returns a string containing the previously defined
     error handler (if any), or &false; on error. If the previous handler
     was a class method, this function will return an indexed array with
     the class and the method name.
    </para>
    <para>
     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 second parameter <parameter>error_types</parameter> was introduced in
     PHP 5 and can be used to mask the triggering of the
     <parameter>error_handler</parameter> function just like the <link
     linkend="ini.error-reporting">error_reporting</link> ini setting controls
     which errors are shown. Without this mask set the
     <parameter>error_handler</parameter> will be called for every error
     regardless to the setting of the <link
     linkend="ini.error-reporting">error_reporting</link> setting.
    </para>
    <para>
     The user function needs to accept two parameters: the error code, and a
     string describing the error. From PHP 4.0.2, three optional
     parameters are supplied: the filename in which the error occurred, the
     line number in which the error occurred, and the context in which the
     error occurred (an array that points to the active symbol table at the
     point the error occurred).  The function can be shown as:
     <methodsynopsis>
      <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>
         The first parameter, <replaceable>errno</replaceable>, contains the
         level of the error raised, as an integer.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>errstr</parameter></term>
       <listitem>
        <simpara>
         The second parameter, <parameter>errstr</parameter>, contains the
         error message, as a string.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>errfile</parameter></term>
       <listitem>
        <simpara>
         The third parameter is optional, <parameter>errfile</parameter>,
         which contains the filename that the error was raised in, as a string.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>errline</parameter></term>
       <listitem>
        <simpara>
         The fourth parameter is optional, <parameter>errline</parameter>,
         which contains the line number the error was raised at, as an integer.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>errcontext</parameter></term>
       <listitem>
        <simpara>
         The fifth parameter is optional, <parameter>errcontext</parameter>,
         which is an array that points to the active symbol table at the point
         the error occurred.  In other words, <parameter>errcontext</parameter>
         will contain an array of every variable that existed in the scope the
         error was triggered in.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>    
    </para>
    <note>
     <simpara>
      Instead of a function name, an array containing an object reference and
      a method name can also be supplied. (Since PHP 4.3.0)
     </simpara>
    </note>
    <note>
     <para>
      The following error types cannot be handled with a user defined
      function: <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>, and
      <constant>E_STRICT</constant>.
     </para>
    </note>
    <para>
     The example below shows the handling of internal exceptions 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">
<![CDATA[
<?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 "<b>FATAL</b> [$errno] $errstr<br />\n";
    echo "  Fatal error in line $errline of file $errfile";
    echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
    echo "Aborting...<br />\n";
    exit(1);
    break;
  case ERROR:
    echo "<b>ERROR</b> [$errno] $errstr<br />\n";
    break;
  case WARNING:
    echo "<b>WARNING</b> [$errno] $errstr<br />\n";
    break;
  default:
    echo "Unkown error type: [$errno] $errstr<br />\n";
    break;
  }
}

// function to test the error handling
function scale_by_log($vect, $scale) 
{
  if (!is_numeric($scale) || $scale <= 0) {
    trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale",
      FATAL);
  }

  if (!is_array($vect)) {
    trigger_error("Incorrect input vector, array of values expected", ERROR);
    return null;
  }

  for ($i=0; $i<count($vect); $i++) {
    if (!is_numeric($vect[$i]))
      trigger_error("Value at position $i is not a number, using 0 (zero)", 
        WARNING);
    $temp[$i] = log($scale) * $vect[$i];
  }
  return $temp;
}

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

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

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

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

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

?>
]]>
      </programlisting>
      <para>
       And when you run this sample script, the output will be:
      </para>
      <screen>
<![CDATA[
vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a warning (b = log(PI) * a)
<b>WARNING</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - an error
<b>ERROR</b> [512] Incorrect input vector, array of values expected<br />
NULL
----
vector d - fatal error
<b>FATAL</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
  Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)<br />
Aborting...<br />
]]>
      </screen>
     </example>
    </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 <link linkend="ini.error-reporting">error_reporting</link> 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>
    <note>
     <para>
     If errors occur before the script is executed (e.g. on file uploads) the custom
     error handler cannot be called since it is not registered at that time.
     </para>
    </note>
    <note>
     <para>
      The second parameter <parameter>error_types</parameter> was introduced
      in PHP 5.
     </para>
    </note>
    <para>
     See also <function>error_reporting</function>,
     <function>restore_error_handler</function>,
     <function>trigger_error</function>, and
     <link linkend="errorfunc.constants">error level constants</link>.
    </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
-->