php-doc-en/reference/errorfunc/functions/set-error-handler.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.31 $ -->
<!-- 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 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></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. <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.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </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), or &null; 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>
 </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.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
// set the error reporting level for this script
error_reporting(E_USER_ERROR | E_USER_WARNING | E_USER_NOTICE);

// 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 in line $errline of 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 "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", E_USER_ERROR);
  }

  if (!is_array($vect)) {
    trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
    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)", E_USER_NOTICE);
      $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>
    &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 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>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <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:"../../../../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
-->