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