includes/debug/Debug.php

   1 <?php
   2
   3 /**
   4  * New debugger system that outputs a toolbar on page view
   5  *
   6  * By default, most methods do nothing ( self::$enabled = false ). You have
   7  * to explicitly call MWDebug::init() to enabled them.
   8  *
   9  * @todo Profiler support
  10  */
  11 class MWDebug {
  12
  13         /**
  14          * Log lines
  15          *
  16          * @var array
  17          */
  18         protected static $log = array();
  19
  20         /**
  21          * Debug messages from wfDebug()
  22          *
  23          * @var array
  24          */
  25         protected static $debug = array();
  26
  27         /**
  28          * Queries
  29          *
  30          * @var array
  31          */
  32         protected static $query = array();
  33
  34         /**
  35          * Is the debugger enabled?
  36          *
  37          * @var bool
  38          */
  39         protected static $enabled = false;
  40
  41         /**
  42          * Array of functions that have already been warned, formatted
  43          * function-caller to prevent a buttload of warnings
  44          *
  45          * @var array
  46          */
  47         protected static $deprecationWarnings = array();
  48
  49         /**
  50          * Enabled the debugger and load resource module.
  51          * This is called by Setup.php when $wgDebugToolbar is true.
  52          */
  53         public static function init() {
  54                 self::$enabled = true;
  55         }
  56
  57         /**
  58          * Add ResourceLoader modules to the OutputPage object if debugging is
  59          * enabled.
  60          *
  61          * @param $out OutputPage
  62          */
  63         public static function addModules( OutputPage $out ) {
  64                 if ( self::$enabled ) {
  65                         $out->addModules( 'mediawiki.debug.init' );
  66                 }
  67         }
  68
  69         /**
  70          * Adds a line to the log
  71          *
  72          * @todo Add support for passing objects
  73          *
  74          * @param $str string
  75          */
  76         public static function log( $str ) {
  77                 if ( !self::$enabled ) {
  78                         return;
  79                 }
  80
  81                 self::$log[] = array(
  82                         'msg' => htmlspecialchars( $str ),
  83                         'type' => 'log',
  84                         'caller' => wfGetCaller(),
  85                 );
  86         }
  87
  88         /**
  89          * Returns internal log array
  90          * @return array
  91          */
  92         public static function getLog() {
  93                 return self::$log;
  94         }
  95
  96         /**
  97          * Clears internal log array and deprecation tracking
  98          */
  99         public static function clearLog() {
 100                 self::$log = array();
 101                 self::$deprecationWarnings = array();
 102         }
 103
 104         /**
 105          * Adds a warning entry to the log
 106          *
 107          * @param $msg
 108          * @param int $callerOffset
 109          * @return mixed
 110          */
 111         public static function warning( $msg, $callerOffset = 1 ) {
 112                 if ( !self::$enabled ) {
 113                         return;
 114                 }
 115
 116                 // Check to see if there was already a deprecation notice, so not to
 117                 // get a duplicate warning
 118                 $logCount = count( self::$log );
 119                 if ( $logCount ) {
 120                         $lastLog = self::$log[ $logCount - 1 ];
 121                         if ( $lastLog['type'] == 'deprecated' && $lastLog['caller'] == wfGetCaller( $callerOffset + 1 ) ) {
 122                                 return;
 123                         }
 124                 }
 125
 126                 self::$log[] = array(
 127                         'msg' => htmlspecialchars( $msg ),
 128                         'type' => 'warn',
 129                         'caller' => wfGetCaller( $callerOffset ),
 130                 );
 131         }
 132
 133         /**
 134          * Adds a depreciation entry to the log, along with a backtrace
 135          *
 136          * @param $function
 137          * @param $version
 138          * @param $component
 139          * @return mixed
 140          */
 141         public static function deprecated( $function, $version, $component ) {
 142                 if ( !self::$enabled ) {
 143                         return;
 144                 }
 145
 146                 // Chain: This function -> wfDeprecated -> deprecatedFunction -> caller
 147                 $caller = wfGetCaller( 4 );
 148
 149                 // Check to see if there already was a warning about this function
 150                 $functionString = "$function-$caller";
 151                 if ( in_array( $functionString, self::$deprecationWarnings ) ) {
 152                         return;
 153                 }
 154
 155                 $version = $version === false ? '(unknown version)' : $version;
 156                 $component = $component === false ? 'MediaWiki' : $component;
 157                 $msg = htmlspecialchars( "Use of function $function was deprecated in $component $version" );
 158                 $msg .= Html::rawElement( 'div', array( 'class' => 'mw-debug-backtrace' ),
 159                         Html::element( 'span', array(), 'Backtrace:' )
 160                          . wfBacktrace()
 161                 );
 162
 163                 self::$deprecationWarnings[] = $functionString;
 164                 self::$log[] = array(
 165                         'msg' => $msg,
 166                         'type' => 'deprecated',
 167                         'caller' => $caller,
 168                 );
 169         }
 170
 171         /**
 172          * This is a method to pass messages from wfDebug to the pretty debugger.
 173          * Do NOT use this method, use MWDebug::log or wfDebug()
 174          *
 175          * @param $str string
 176          */
 177         public static function debugMsg( $str ) {
 178                 if ( !self::$enabled ) {
 179                         return;
 180                 }
 181
 182                 self::$debug[] = trim( $str );
 183         }
 184
 185         /**
 186          * Begins profiling on a database query
 187          *
 188          * @param $sql string
 189          * @param $function string
 190          * @param $isMaster bool
 191          * @return int ID number of the query to pass to queryTime or -1 if the
 192          *  debugger is disabled
 193          */
 194         public static function query( $sql, $function, $isMaster ) {
 195                 if ( !self::$enabled ) {
 196                         return -1;
 197                 }
 198
 199                 self::$query[] = array(
 200                         'sql' => $sql,
 201                         'function' => $function,
 202                         'master' => (bool) $isMaster,
 203                         'time' => 0.0,
 204                         '_start' => microtime( true ),
 205                 );
 206
 207                 return count( self::$query ) - 1;
 208         }
 209
 210         /**
 211          * Calculates how long a query took.
 212          *
 213          * @param $id int
 214          */
 215         public static function queryTime( $id ) {
 216                 if ( $id === -1 || !self::$enabled ) {
 217                         return;
 218                 }
 219
 220                 self::$query[$id]['time'] = microtime( true ) - self::$query[$id]['_start'];
 221                 unset( self::$query[$id]['_start'] );
 222         }
 223
 224         /**
 225          * Returns a list of files included, along with their size
 226          *
 227          * @param $context IContextSource
 228          * @return array
 229          */
 230         protected static function getFilesIncluded( IContextSource $context ) {
 231                 $files = get_included_files();
 232                 $fileList = array();
 233                 foreach ( $files as $file ) {
 234                         $size = filesize( $file );
 235                         $fileList[] = array(
 236                                 'name' => $file,
 237                                 'size' => $context->getLanguage()->formatSize( $size ),
 238                         );
 239                 }
 240
 241                 return $fileList;
 242         }
 243
 244         /**
 245          * Returns the HTML to add to the page for the toolbar
 246          *
 247          * @param $context IContextSource
 248          * @return string
 249          */
 250         public static function getDebugHTML( IContextSource $context ) {
 251                 if ( !self::$enabled ) {
 252                         return '';
 253                 }
 254
 255                 global $wgVersion, $wgRequestTime;
 256                 MWDebug::log( 'MWDebug output complete' );
 257                 $request = $context->getRequest();
 258                 $debugInfo = array(
 259                         'mwVersion' => $wgVersion,
 260                         'phpVersion' => PHP_VERSION,
 261                         'gitRevision' => GitInfo::headSHA1(),
 262                         'gitBranch' => GitInfo::currentBranch(),
 263                         'time' => microtime( true ) - $wgRequestTime,
 264                         'log' => self::$log,
 265                         'debugLog' => self::$debug,
 266                         'queries' => self::$query,
 267                         'request' => array(
 268                                 'method' => $_SERVER['REQUEST_METHOD'],
 269                                 'url' => $request->getRequestURL(),
 270                                 'headers' => $request->getAllHeaders(),
 271                                 'params' => $request->getValues(),
 272                         ),
 273                         'memory' => $context->getLanguage()->formatSize( memory_get_usage() ),
 274                         'memoryPeak' => $context->getLanguage()->formatSize( memory_get_peak_usage() ),
 275                         'includes' => self::getFilesIncluded( $context ),
 276                 );
 277
 278                 // Cannot use OutputPage::addJsConfigVars because those are already outputted
 279                 // by the time this method is called.
 280                 $html = Html::inlineScript(
 281                         ResourceLoader::makeLoaderConditionalScript(
 282                                 ResourceLoader::makeConfigSetScript( array( 'debugInfo' => $debugInfo ) )
 283                         )
 284                 );
 285
 286                 return $html;
 287         }
 288 }