/phpdoc/doc/set-error-handler.txt

set_error_handler -- Sets a user-defined error handler function

  mixed set_error_handler(callback error_handler [, int error_types])~

Sets a user function ({error_handler}) to handle errors in a script.

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 |trigger_error|).

It is important to remember that the standard PHP error handler is completely
bypassed. |error_reporting| settings will have no effect and your error
handler will be called regardless - however you are still able to read the
current value of error_reporting and act appropriately. Of particular note is
that this value will be 0 if the statement that caused the error was prepended
by the @ error-control operator.

Also note that it is your responsibility to |die| if necessary. If the
error-handler function returns, script execution will continue with the next
statement after the one that caused an error.

The following error types cannot be handled with a user defined function:
E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR,
E_COMPILE_WARNING, and most of E_STRICT raised in the file where
|set_error_handler| is called.

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.

{error_handler} 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:

  mixed (callback error_handler [, int error_types, int errno, string errstr [, string errfile [, int errline [, array errcontext]]]])~

{errno} The first parameter, {errno}, contains the level of the error raised,
as an integer.

{errstr} The second parameter, {errstr}, contains the error message, as a
string.

{errfile} The third parameter is optional, {errfile}, which contains the
filename that the error was raised in, as a string.

{errline} The fourth parameter is optional, {errline}, which contains the line
number the error was raised at, as an integer.

{errcontext} The fifth parameter is optional, {errcontext}, which is an array
that points to the active symbol table at the point the error occurred. In
other words, {errcontext} 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.

If the function returns FALSE then the normal error handler continues.

{error_types} Can be used to mask the triggering of the {error_handler}
function just like the error_reporting ini setting controls which errors are
shown. Without this mask set the {error_handler} will be called for every
error regardless to the setting of the error_reporting setting.

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.

Version Description 5.2.0 The error handler must return FALSE to populate
$php_errormsg. 5.0.0 The {error_types} parameter was introduced. 4.3.0 Instead
of a function name, an array containing an object reference and a method name
can also be supplied as the {error_handler}. 4.0.2 Three optional parameters
for the {error_handler} user function was introduced. These are the filename,
the line number, and the context.

Error handling with |set_error_handler| and |trigger_error| The example below
shows the handling of internal exceptions by triggering errors and handling
them with a user defined function:

<?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
?>

The above example will output something similar to:

  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 />



ErrorException |error_reporting| |restore_error_handler| |trigger_error| error
level constants information about the callback type

vim:ft=help: