Ticket #5669: debug.3.php

<?php
/**
 * WordPress Logging API
 *
 * This pluggable file can be replaced by plugins
 * by enabling WP_DEBUG and having a file in
 * wp-content folder named "debug.php".
 *
 * There are also filters which allow a basic
 * plugin to halt displaying certain types and
 * severity levels of logging messages. There are
 * also filters for customizing how the logging
 * messages are displayed in the footer of a page.
 *
 * The reason you would want to replace this file
 * is if you want to log messages to files or to
 * a database (barring a failed connection to the
 * database).
 *
 * @since 2.5
 * @package WordPress
 */

/**
 * Notice Severity for use in wp_log() third parameter.
 *
 * The notice severity are basic notices that let the user
 * know what WordPress is doing. They aren't WordPress
 * problems and should not be used for WordPress problems.
 *
 * An example, would be to note that WordPress is shutting
 * down and when WordPress starts up. Usually, these notes
 * will be disabled by debuggers seeking higher problems
 * and enabled by debuggers seeking more fine tuned
 * locations of problems.
 *
 * @since 2.5
 */
define('WP_LOG_SEVERITY_NOTE', 1);

/**
 * Low Severity level for use in wp_log third parameter.
 *
 * Low severity levels are reserved for areas that might
 * cause problems or areas that WordPress considers that
 * the user should look over in more depth.
 *
 * @since 2.5
 */
define('WP_LOG_SEVERITY_LOW', 2);

/**
 * Medium Severity level for use in wp_log third parameter.
 *
 * Medium severity levels are reserved for areas that
 * WordPres considers to be problems, but ignores or fixes
 * for the user anyway. The problem could cause problems,
 * but have a lower risk for causing damage.
 *
 * The user might want to consider taking action to resolve
 * the issue in the future, but generally are nothing to
 * worry about.
 *
 * @since 2.5
 */
define('WP_LOG_SEVERITY_MEDIUM', 4);

/**
 * Warning Severity level for use in wp_log third parameter.
 *
 * The user should seek to resolve the problem area as
 * quickly as possible as the problem poses some problem
 * area that should be addressed by the user. The problem
 * generally didn't cause any problem for the issuer and
 * was able to continue execution.
 *
 * @since 2.5
 */
define('WP_LOG_SEVERITY_WARNING', 8);

/**
 * High Severity level for use in wp_log third parameter.
 *
 * The issuer was able to continue execution or halted
 * execution, but did not bring down WordPress in the
 * process. WordPress was able to continue but the failed
 * process will continue to fail, unless the user does
 * something to fix the problem.
 *
 * The user should also report the problem to the
 * party that maintains the issuer process.
 *
 * @since 2.5
 */
define('WP_LOG_SEVERITY_HIGH', 16);

/**
 * Error Severity level for use in wp_log third parameter.
 *
 * The issuer halted the execution of its process and
 * took down the WordPress process as a result. The user
 * should report the problem to the maintainer of the
 * process which issued the error.
 *
 * @since 2.5
 */
define('WP_LOG_SEVERITY_ERROR', 32);

/**
 * XMLRPC logging constant
 *
 * Used for readability of XMLRPC messages.
 *
 * @since 2.5
 */
define('WP_LOG_XMLRPC', 'xmlrpc');

/**
 * WordPress Object Cache logging constant
 *
 * Used for readability of Object Cache messages.
 *
 * @since 2.5
 */
define('WP_LOG_CACHE', 'cache');

/**
 * WordPress Database logging constant
 *
 * Used for readability of WordPress Database messages.
 *
 * @since 2.5
 */
define('WP_LOG_DATABASE', 'wpdb');

/**
 * WordPress plugins logging constant
 *
 * @since 2.5
 */
define('WP_LOG_PLUGIN', 'plugin');

/**
 * PHP Errors logging constant
 *
 * @since 2.5
 */
define('WP_LOG_PHP_ERROR', 'php_error');

/**
 * PHP 5 Exceptions logging constant
 *
 * @since 2.5
 */
define('WP_LOG_EXCEPTIONS', 'exceptions');

/**
 * wp_log() - Log a message based on severity of the problem.
 *
 * @since 2.5
 * @global array $wp_log_messages Stores all of the log messages
 * @uses has_filter() Checks to see if filters exist for preventing logging.
 * @uses apply_filters() Calls 'wp_log_severity' to see if the severity
 *        should be logged.
 * @uses apply_filters() Calls 'wp_log_type' to see if type should be logged.
 * @uses apply_filters() Calls 'wp_log_$type_type' to see if a specific type
 *        should be logged.
 *
 * @param string $type The area which the message was logged.
 * @param string $message The message to display to the user about the problem.
 * @param int $severity Severity level of the log message
 * @return bool False if failed to log message, true if message was logged.
 */
function wp_log($type, $message, $severity) {

    // If WP_DEBUG is not defined, then don't process log message
    if( !defined('WP_DEBUG') )
        return false;

    global $wp_log_messages;

    if( !is_array( $wp_log_messages ) )
        $wp_log_messages = array();

    // Allow for a plugin (if plugin API is loaded) to prevent logging severities
    if( function_exists('has_filter') ) {
        if( has_filter('wp_log_severity') )
            if ( false === apply_filters('wp_log_severity', true, $severity) )
                return false;

        if( has_filter('wp_log_type') || has_filter("wp_log_{$type}_type") ) {
            $log_type = apply_filters('wp_log_type', true, $type);
            $log_type_with_type = apply_filters("wp_log_{$type}_type", true);

            if( false === $log_type || false === $log_type_with_type )
                return false;
        }
    }

    $wp_log_messages[$type][$severity][] = array( $message, debug_backtrace() );

    return true;
}

/**
 * wp_plugin_log() - Logs plugin messages by severity and plugin name
 *
 * This is supposed to be used by plugin problems and assigns the log
 * messages to a general type with the plugin name that will be referenced
 * later.
 *
 * @param string $plugin Plugin Name
 * @param string $message Message to give the user about the plugin problem
 * @param int|string $severity Plugin log message severity of the problem
 * @return bool False if log message was not logged and true if message was logged.
 */
function wp_plugin_log($plugin, $message, $severity) {

    // If WP_DEBUG is not defined, then don't process log message
    if( !defined('WP_DEBUG') )
        return false;

    global $wp_plugin_log_messages;

    if( !is_array( $wp_log_messages ) )
        $wp_log_messages = array();

    $wp_plugin_log_messages[$plugin][$severity][] = array( $message, debug_backtrace() );

    return true;
}

/**
 * wp_log_severity_display_name() - Converts numeric severity to string
 *
 * @param int $severity
 * @return string Name of the severity
 */
function wp_log_severity_display_name($severity) {
    switch($severity) {
        case WP_LOG_SEVERITY_NOTE:        return _c('note|severity_note');
        case WP_LOG_SEVERITY_LOW:        return _c('low|severity_note');
        case WP_LOG_SEVERITY_MEDIUM:    return _c('medium|severity_note');
        case WP_LOG_SEVERITY_WARNING:    return _c('warning|severity_note');
        case WP_LOG_SEVERITY_HIGH:        return _c('high|severity_note');
        case WP_LOG_SEVERITY_ERROR:        return _c('error|severity_note');
    }
}

/**
 * wp_log_error_handler() - Handle Errors thrown
 *
 * @param int $iError
 * @param string $strError
 * @param string $strFile
 * @param string $strLine
 * @param array $arrContext
 * @return bool
 */
function wp_log_error_handler($iError, $strError, $strFile, $strLine, $arrContext) {

    // If WP_DEBUG is not defined, then don't process error message
    if( !defined('WP_DEBUG') )
        return false;

    global $wp_log_messages;

    if( defined('E_RECOVERABLE_ERROR') && E_RECOVERABLE_ERROR === $iError ) {
        $wp_log_messages[WP_LOG_PHP_ERROR][WP_LOG_SEVERITY_HIGH][] = array(
            $strError,
            array_merge(
                array(array(
                'file' => $strFile,
                'line' => $strLine,
                'function' => '',
                'args' => array()
                )),
                (array) debug_backtrace()
            )
        );
        return true;
    }

    switch( $iError ) {
        case E_ERROR:
            $wp_log_messages[WP_LOG_PHP_ERROR][WP_LOG_SEVERITY_ERROR][] = array(
                $strError,
                array_merge(
                    array(array(
                    'file' => $strFile,
                    'line' => $strLine,
                    'function' => '',
                    'args' => array()
                    )),
                    (array) debug_backtrace()
                )
            );
            wp_log_shutdown();
            wp_die();
            break;

        case E_USER_ERROR:
            $wp_log_messages[WP_LOG_PHP_ERROR][WP_LOG_SEVERITY_HIGH][] = array(
                $strError,
                array_merge(
                    array(array(
                    'file' => $strFile,
                    'line' => $strLine,
                    'function' => '',
                    'args' => array()
                    )),
                    (array) debug_backtrace()
                )
            );
            var_dump($wp_log_messages);
            break;

        case E_USER_WARNING:
        case E_WARNING:
            $wp_log_messages[WP_LOG_PHP_ERROR][WP_LOG_SEVERITY_WARNING][] = array(
                $strError,
                array_merge(
                    array(array(
                    'file' => $strFile,
                    'line' => $strLine,
                    'function' => '',
                    'args' => array()
                    )),
                    (array) debug_backtrace()
                )
            );
            break;

        case E_USER_NOTICE:
        case E_NOTICE:
            $wp_log_messages[WP_LOG_PHP_ERROR][WP_LOG_SEVERITY_LOW][] = array(
                $strError,
                array_merge(
                    array(array(
                    'file' => $strFile,
                    'line' => $strLine,
                    'function' => '',
                    'args' => array()
                    )),
                    (array) debug_backtrace()
                )
            );
            break;
        default:
            return false;
    }

    return true;
}

set_error_handler( 'wp_log_error_handler', E_ALL );

/**
 * wp_log_exception_handler() - Handle Exceptions thrown
 *
 * @param Exception $exception Exception 
 */
function wp_log_exception_handler($exception) {
    wp_log(WP_LOG_EXCEPTIONS, $exception->getMessage(), WP_LOG_SEVERITY_HIGH);
}

if( function_exists('set_exception_handler') )
    set_exception_handler('wp_log_exception_handler');

?>