Debug.php

Go to the documentation of this file.

<?php
class MWDebug {

    protected static $log = array();

    protected static $debug = array();

    protected static $query = array();

    protected static $enabled = false;

    protected static $deprecationWarnings = array();

    public static function init() {
        self::$enabled = true;
    }

    public static function addModules( OutputPage $out ) {
        if ( self::$enabled ) {
            $out->addModules( 'mediawiki.debug.init' );
        }
    }

    public static function log( $str ) {
        if ( !self::$enabled ) {
            return;
        }

        self::$log[] = array(
            'msg' => htmlspecialchars( $str ),
            'type' => 'log',
            'caller' => wfGetCaller(),
        );
    }

    public static function getLog() {
        return self::$log;
    }

    public static function clearLog() {
        self::$log = array();
        self::$deprecationWarnings = array();
    }

    public static function warning( $msg, $callerOffset = 1, $level = E_USER_NOTICE, $log = 'auto' ) {
        global $wgDevelopmentWarnings;

        if ( $log === 'auto' && !$wgDevelopmentWarnings ) {
            $log = 'debug';
        }

        if ( $log === 'debug' ) {
            $level = false;
        }

        $callerDescription = self::getCallerDescription( $callerOffset );

        self::sendWarning( $msg, $callerDescription, $level );

        if ( self::$enabled ) {
            self::$log[] = array(
                'msg' => htmlspecialchars( $msg ),
                'type' => 'warn',
                'caller' => $callerDescription['func'],
            );
        }
    }

    public static function deprecated( $function, $version = false, $component = false, $callerOffset = 2 ) {
        $callerDescription = self::getCallerDescription( $callerOffset );
        $callerFunc = $callerDescription['func'];

        $sendToLog = true;

        // Check to see if there already was a warning about this function
        if ( isset( self::$deprecationWarnings[$function][$callerFunc] ) ) {
            return;
        } elseif ( isset( self::$deprecationWarnings[$function] ) ) {
            if ( self::$enabled ) {
                $sendToLog = false;
            } else {
                return;
            }
        }

        self::$deprecationWarnings[$function][$callerFunc] = true;

        if ( $version ) {
            global $wgDeprecationReleaseLimit;
            if ( $wgDeprecationReleaseLimit && $component === false ) {
                # Strip -* off the end of $version so that branches can use the
                # format #.##-branchname to avoid issues if the branch is merged into
                # a version of MediaWiki later than what it was branched from
                $comparableVersion = preg_replace( '/-.*$/', '', $version );

                # If the comparableVersion is larger than our release limit then
                # skip the warning message for the deprecation
                if ( version_compare( $wgDeprecationReleaseLimit, $comparableVersion, '<' ) ) {
                    $sendToLog = false;
                }
            }

            $component = $component === false ? 'MediaWiki' : $component;
            $msg = "Use of $function was deprecated in $component $version.";
        } else {
            $msg = "Use of $function is deprecated.";
        }

        if ( $sendToLog ) {
            global $wgDevelopmentWarnings; // we could have a more specific $wgDeprecationWarnings setting.
            self::sendWarning( $msg, $callerDescription, $wgDevelopmentWarnings ? E_USER_DEPRECATED : false );
        }

        if ( self::$enabled ) {
            $logMsg = htmlspecialchars( $msg ) .
                Html::rawElement( 'div', array( 'class' => 'mw-debug-backtrace' ),
                    Html::element( 'span', array(), 'Backtrace:' ) . wfBacktrace()
                );

            self::$log[] = array(
                'msg' => $logMsg,
                'type' => 'deprecated',
                'caller' => $callerFunc,
            );
        }
    }

    private static function getCallerDescription( $callerOffset ) {
        $callers = wfDebugBacktrace();

        if ( isset( $callers[$callerOffset] ) ) {
            $callerfile = $callers[$callerOffset];
            if ( isset( $callerfile['file'] ) && isset( $callerfile['line'] ) ) {
                $file = $callerfile['file'] . ' at line ' . $callerfile['line'];
            } else {
                $file = '(internal function)';
            }
        } else {
            $file = '(unknown location)';
        }

        if ( isset( $callers[$callerOffset + 1] ) ) {
            $callerfunc = $callers[$callerOffset + 1];
            $func = '';
            if ( isset( $callerfunc['class'] ) ) {
                $func .= $callerfunc['class'] . '::';
            }
            if ( isset( $callerfunc['function'] ) ) {
                $func .= $callerfunc['function'];
            }
        } else {
            $func = 'unknown';
        }

        return array( 'file' => $file, 'func' => $func );
    }

    private static function sendWarning( $msg, $caller, $level ) {
        $msg .= ' [Called from ' . $caller['func'] . ' in ' . $caller['file'] . ']';

        if ( $level !== false ) {
            trigger_error( $msg, $level );
        }

        wfDebug( "$msg\n" );
    }

    public static function debugMsg( $str ) {
        global $wgDebugComments, $wgShowDebug;

        if ( self::$enabled || $wgDebugComments || $wgShowDebug ) {
            self::$debug[] = rtrim( UtfNormal::cleanUp( $str ) );
        }
    }

    public static function query( $sql, $function, $isMaster ) {
        if ( !self::$enabled ) {
            return -1;
        }

        self::$query[] = array(
            'sql' => $sql,
            'function' => $function,
            'master' => (bool)$isMaster,
            'time' => 0.0,
            '_start' => microtime( true ),
        );

        return count( self::$query ) - 1;
    }

    public static function queryTime( $id ) {
        if ( $id === -1 || !self::$enabled ) {
            return;
        }

        self::$query[$id]['time'] = microtime( true ) - self::$query[$id]['_start'];
        unset( self::$query[$id]['_start'] );
    }

    protected static function getFilesIncluded( IContextSource $context ) {
        $files = get_included_files();
        $fileList = array();
        foreach ( $files as $file ) {
            $size = filesize( $file );
            $fileList[] = array(
                'name' => $file,
                'size' => $context->getLanguage()->formatSize( $size ),
            );
        }

        return $fileList;
    }

    public static function getDebugHTML( IContextSource $context ) {
        global $wgDebugComments;

        $html = '';

        if ( self::$enabled ) {
            MWDebug::log( 'MWDebug output complete' );
            $debugInfo = self::getDebugInfo( $context );

            // Cannot use OutputPage::addJsConfigVars because those are already outputted
            // by the time this method is called.
            $html = Html::inlineScript(
                ResourceLoader::makeLoaderConditionalScript(
                    ResourceLoader::makeConfigSetScript( array( 'debugInfo' => $debugInfo ) )
                )
            );
        }

        if ( $wgDebugComments ) {
            $html .= "<!-- Debug output:\n" .
                htmlspecialchars( implode( "\n", self::$debug ) ) .
                "\n\n-->";
        }

        return $html;
    }

    public static function getHTMLDebugLog() {
        global $wgDebugTimestamps, $wgShowDebug;

        if ( !$wgShowDebug ) {
            return '';
        }

        $curIdent = 0;
        $ret = "\n<hr />\n<strong>Debug data:</strong><ul id=\"mw-debug-html\">\n<li>";

        foreach ( self::$debug as $line ) {
            $pre = '';
            if ( $wgDebugTimestamps ) {
                $matches = array();
                if ( preg_match( '/^(\d+\.\d+ {1,3}\d+.\dM\s{2})/', $line, $matches ) ) {
                    $pre = $matches[1];
                    $line = substr( $line, strlen( $pre ) );
                }
            }
            $display = ltrim( $line );
            $ident = strlen( $line ) - strlen( $display );
            $diff = $ident - $curIdent;

            $display = $pre . $display;
            if ( $display == '' ) {
                $display = "\xc2\xa0";
            }

            if ( !$ident && $diff < 0 && substr( $display, 0, 9 ) != 'Entering ' && substr( $display, 0, 8 ) != 'Exiting ' ) {
                $ident = $curIdent;
                $diff = 0;
                $display = '<span style="background:yellow;">' . nl2br( htmlspecialchars( $display ) ) . '</span>';
            } else {
                $display = nl2br( htmlspecialchars( $display ) );
            }

            if ( $diff < 0 ) {
                $ret .= str_repeat( "</li></ul>\n", -$diff ) . "</li><li>\n";
            } elseif ( $diff == 0 ) {
                $ret .= "</li><li>\n";
            } else {
                $ret .= str_repeat( "<ul><li>\n", $diff );
            }
            $ret .= "<tt>$display</tt>\n";

            $curIdent = $ident;
        }

        $ret .= str_repeat( '</li></ul>', $curIdent ) . "</li>\n</ul>\n";

        return $ret;
    }

    public static function appendDebugInfoToApiResult( IContextSource $context, ApiResult $result ) {
        if ( !self::$enabled ) {
            return;
        }

        // output errors as debug info, when display_errors is on
        // this is necessary for all non html output of the api, because that clears all errors first
        $obContents = ob_get_contents();
        if ( $obContents ) {
            $obContentArray = explode( '<br />', $obContents );
            foreach ( $obContentArray as $obContent ) {
                if ( trim( $obContent ) ) {
                    self::debugMsg( Sanitizer::stripAllTags( $obContent ) );
                }
            }
        }

        MWDebug::log( 'MWDebug output complete' );
        $debugInfo = self::getDebugInfo( $context );

        $result->setIndexedTagName( $debugInfo, 'debuginfo' );
        $result->setIndexedTagName( $debugInfo['log'], 'line' );
        $result->setIndexedTagName( $debugInfo['debugLog'], 'msg' );
        $result->setIndexedTagName( $debugInfo['queries'], 'query' );
        $result->setIndexedTagName( $debugInfo['includes'], 'queries' );
        $result->addValue( null, 'debuginfo', $debugInfo );
    }

    public static function getDebugInfo( IContextSource $context ) {
        if ( !self::$enabled ) {
            return array();
        }

        global $wgVersion, $wgRequestTime;
        $request = $context->getRequest();
        return array(
            'mwVersion' => $wgVersion,
            'phpVersion' => PHP_VERSION,
            'gitRevision' => GitInfo::headSHA1(),
            'gitBranch' => GitInfo::currentBranch(),
            'gitViewUrl' => GitInfo::headViewUrl(),
            'time' => microtime( true ) - $wgRequestTime,
            'log' => self::$log,
            'debugLog' => self::$debug,
            'queries' => self::$query,
            'request' => array(
                'method' => $request->getMethod(),
                'url' => $request->getRequestURL(),
                'headers' => $request->getAllHeaders(),
                'params' => $request->getValues(),
            ),
            'memory' => $context->getLanguage()->formatSize( memory_get_usage() ),
            'memoryPeak' => $context->getLanguage()->formatSize( memory_get_peak_usage() ),
            'includes' => self::getFilesIncluded( $context ),
        );
    }
}