set_error_handler

Synopsis

Returns

Name of the previous error handler; NULL if the previous error handler was PHP's built-in handler

Description

set_error_handler() allows a user-defined function to be used as a custom error handler for errors triggered with trigger_error() and errors of the E_NOTICE, E_WARNING, and E_ERROR level.

Custom error handlers provide a simple way to separate your error-handling code from the code that triggers the error.

The user-defined function that handles the triggered errors can be as simple or elaborate as desired. The function is passed two arguments. The first argument is the level of the triggered error (E_USER_WARNING, E_USER_NOTICE, etc.). The second argument contains the error message.

Three optional arguments were added in PHP 4.0.2. The first is the name of the file in which the error was triggered. If the error was triggered within an included file, the name of the included file will be used.

The second optional argument is the line number on which the error was triggered. If the error was triggered within an included or required file, the line number returned will be from the included file.

The final optional argument is an array that contains all of the variables that are set in the scope in which the error was triggered. This information is quite useful for debugging or for performing conditional handling of errors based on environment state when the error occurred.

What the function does with these arguments is entirely up to the programmer. See the following examples.

Version

PHP Version: 4.0.1+ (Major enhancements in 4.0.2+)

See also

To log an error message

error_log()

The log_errors and error_log directives in the php.ini file.

To throw an error

trigger_error()

To restore the last error handler

restore_error_handler()

Example

<?php
# Create a custom error handler that roughly mimics PHP's built-in error handler

# Set error reporting to the highest level
error_reporting (E_ALL);

# Uncomment the line below to reduce the level of error reporting
# error_reporting (E_ALL & ~ (E_NOTICE | E_USER_NOTICE));

# Create the function that handles the errors
function error_handler ($error_level, $error_message, $file, $line) {

    $EXIT = FALSE;

    # Only handle the errors specified by the error_reporting directive or function
    # Ensure that we should be displaying and/or logging errors
    if ( ! ($error_level & error_reporting ()) || ! (ini_get ('display_errors') || ini_get ('log_errors')))
        return;

    # Give the error level a name
    # Include the bitmask value for reference
    # Set a switch indicating whether the error level should make the script exit
    switch ($error_level) {
        case E_NOTICE:
        case E_USER_NOTICE:
            $error_type = 'Notice';
            break;

        case E_WARNING:
        case E_USER_WARNING:
            $error_type = 'Warning';
            break;

        case E_ERROR:
        case E_USER_ERROR:
            $error_type = 'Fatal Error';
            $EXIT = TRUE;
            break;

        # Handle the possibility of new error constants being added
        default:
            $error_type = 'Unknown';
            $EXIT = TRUE;
            break;
    }

    if (ini_get ('display_errors'))
        printf ("<b>%s</b>: %s in <b>%s</b> on line <b>%d</b><br /><br />\n", $error_type, $error_message, $file, $line);

    if (ini_get ('log_errors'))
        error_log (sprintf ("%s: %s in %s on line %d", $error_type, $error_message, $file, $line));

    if (TRUE == $EXIT)
        exit;
}

# Use the function as the current error handler
set_error_handler ('error_handler');

# Trigger some errors to test the handler
trigger_error ('Trigger error was called with a simple error message');

# Use an undefined variable
print $var; 

trigger_error ('Trigger a warning', E_USER_WARNING);

# Try to connect to a MySQL database server
mysql_connect ('localhost', 'user', 'pass');

trigger_error ('Trigger a fatal error', E_USER_ERROR);
?>