<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<refentry xml:id="function.set-error-handler" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>set_error_handler</refname>
  <refpurpose>Sets a user-defined error handler function</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <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><initializer>E_ALL | E_STRICT</initializer></methodparam>
  </methodsynopsis>
  <para>
   Sets a user function (<parameter>error_handler</parameter>) to handle
   errors in a script.
  </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>
   It is important to remember that the standard PHP error handler is completely
   bypassed for the error types specified by <parameter>error_types</parameter> 
   unless the callback function returns &false;.
   <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>
  <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
   most of <constant>E_STRICT</constant> raised in the file where
   <function>set_error_handler</function> is called.
  </para>
  <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>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>error_handler</parameter></term>
     <listitem>
      <para>
       The user function needs to accept two parameters: the error code, and a
       string describing the error. Then there are three optional parameters 
       that may be 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:
      </para>
      <para>
       <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, <parameter>errno</parameter>, 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.
           User error handler must not modify error context.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       If the function returns &false; then the normal error handler continues.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>error_types</parameter></term>
     <listitem>
      <para>
       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>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a string containing the previously defined error handler (if any). If
   the built-in error handler is used &null; is returned. &null; is also returned
   in case of an error such as an invalid callback. If the previous error handler
   was a class method, this function will return an indexed array with the class
   and the method name.
  </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.2.0</entry>
       <entry>
        The error handler must return &false; to populate
        <varname>$php_errormsg</varname>.
       </entry>
      </row>
      <row>
       <entry>5.0.0</entry>
       <entry>
        The <parameter>error_types</parameter> parameter was introduced.
       </entry>
      </row>
      <row>
       <entry>4.3.0</entry>
       <entry>
        Instead of a function name, an array containing an object reference 
        and a method name can also be supplied as the
        <parameter>error_handler</parameter>.
       </entry>
      </row>
      <row>
       <entry>4.0.2</entry>
       <entry>
        Three optional parameters for the <parameter>error_handler</parameter>
        user function was introduced. These are the filename, the line number, 
        and the context.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Error handling with <function>set_error_handler</function> and <function>trigger_error</function></title>
    <para>
     The example below shows the handling of internal exceptions by
     triggering errors and handling them with a user defined function:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// error handler function
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
    switch ($errno) {
    case E_USER_ERROR:
        echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
        echo "  Fatal error on line $errline in file $errfile";
        echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
        echo "Aborting...<br />\n";
        exit(1);
        break;

    case E_USER_WARNING:
        echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
        break;

    case E_USER_NOTICE:
        echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
        break;

    default:
        echo "Unknown error type: [$errno] $errstr<br />\n";
        break;
    }

    /* Don't execute PHP internal error handler */
    return true;
}

// 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", E_USER_ERROR);
    }

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

    $temp = array();
    foreach($vect as $pos => $value) {
        if (!is_numeric($value)) {
            trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
            $value = 0;
        }
        $temp[$pos] = log($scale) * $value;
    }

    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
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b = scale_by_log($a, M_PI);
print_r($b);

// this is trouble, we pass a string instead of an array
echo "----\nvector c - a warning\n";
/* Incorrect input vector, array of values expected */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL

// this is a critical error, log of zero or negative number is undefined
echo "----\nvector d - fatal error\n";
/* log(x) for x <= 0 is undefined, you used: scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // Never reached
?>
]]>
    </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 notice (b = log(PI) * a)
<b>My NOTICE</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 - a warning
<b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
NULL
----
vector d - fatal error
<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
  Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Aborting...<br />
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><classname>ErrorException</classname></member>
    <member><function>error_reporting</function></member>
    <member><function>restore_error_handler</function></member>
    <member><function>trigger_error</function></member>
    <member><link linkend="errorfunc.constants">error level constants</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:"~/.phpdoc/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
-->