Ticket #5669: debug.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');

/**
 * 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_shutdown() - Display the log messages to the user
 *
 * Will display the messages in the theme footer ('wp_footer').
 *
 * @since 2.5
 */
function wp_log_shutdown() {
        // If WP_DEBUG is not defined, then don't process log message
        if( !defined('WP_DEBUG') )
                return;

        global $wp_log_messages, $wp_plugin_log_messages;

        if( !is_array($wp_log_messages) || empty($wp_log_messages) )
                return;

        $log_content = '';

        uasort($wp_log_messages, 'strnatcasecmp');

        $log_content .= apply_filters('wp_log_display_wordpress', '<h1>WordPress Log Messages</h1>');

        $log_content .= apply_filters('wp_log_display_start', '');
        $log_content .= wp_log_display( $wp_log_messages );
        $log_content .= apply_filters('wp_log_display_end', '');

        $log_content .= apply_filters('wp_log_display_plugins', '<h1>Plugin Log Messages</h1>');

        $log_content .= apply_filters('wp_log_display_start', '');
        $log_content .= wp_log_display( $wp_plugin_log_messages );
        $log_content .= apply_filters('wp_log_display_end', '');

        echo $log_content;
}

/**
 * wp_log_display() - Converts log message array to display form
 *
 * @since 2.5
 * @param array $log_messages
 * @return string
 */
function wp_log_display($log_messages) {
        $log_content = '';

        foreach( $wp_log_messages as $type => $log_type ) {
                $log_type = apply_filters('wp_log_type', true, $type);
                $log_type_with_type = apply_filters("wp_log_{$type}_type", true);

                // Catch types that shouldn't have been logged.
                if( false === $log_type || false === $log_type_with_type )
                        continue;

                $log_content .= apply_filters('wp_log_display_type_start', "<h2>{$type}</h2><ul>", $type);

                uasort($log_type, 'strnatcasecmp');

                foreach( $log_type as $severity => $log_messages ) {

                        // Catch severity items that shouldn't be displayed
                        if ( false === apply_filters('wp_log_severity', true, $severity) )
                                continue;

                        $severity_display = wp_log_severity_display_name($severity);
                        $log_content .= apply_filters('wp_log_display_severity_start', '<li>' . $severity_display, $severity, $severity_display);

                        foreach( $log_message_items as $log_message ) {
                                // See if we need to add the backtrace.
                                $log_content .= $log_message[0];
                                $backtrace = apply_filters('wp_log_backtrace', $log_message[1]);
                                
                                // Format the backtrace display
                                $log_content .= "<table>\n<tr><th>file</th><th>line</th><th>function</th><th>args</th></tr>\n";

                                foreach( (array) $backtrace as $backtrace_message ) {
                                        if( 'wp_log' == $backtrace_message['function'] )
                                                continue;

                                        $log_content .= "<tr>\n";
                                        $log_content .= "<td>". $backtrace_message['file'] ."</td>\n";
                                        $log_content .= "<td>". $backtrace_message['line'] ."</td>\n";
                                        $log_content .= "<td>". $backtrace_message['function'] ."</td>\n";
                                        $log_content .= "<td>". implode("<br />\n", $backtrace_message['args']) ."</td>\n";
                                        $log_content .= "</tr>";
                                }

                                $log_content .= "</table>\n";
                        }

                        $log_content .= apply_filters('wp_log_display_severity_end', '</li>');
                }

                $log_content .= apply_filters('wp_log_display_type_end', "</ul>\n\n");
        }

        return $log_content;
}

/**
 * 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 'note';
                case WP_LOG_SEVERITY_LOW: return 'low';
                case WP_LOG_SEVERITY_MEDIUM: return 'medium';
                case WP_LOG_SEVERITY_WARNING: return 'warning';
                case WP_LOG_SEVERITY_HIGH: return 'high';
                case WP_LOG_SEVERITY_ERROR: return 'error';
        }
}

?>