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' );
  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          */
  91         public static function getLog() {
  92                 return self::$log;
  93         }
  94
  95         /**
  96          * Clears internal log array and deprecation tracking
  97          */
  98         public static function clearLog() {
  99                 self::$log = array();
 100                 self::$deprecationWarnings = array();
 101         }
 102
 103         /**
 104          * Adds a warning entry to the log
 105          *
 106          * @param $msg
 107          * @param int $callerOffset
 108          * @return mixed
 109          */
 110         public static function warning( $msg, $callerOffset = 1 ) {
 111                 if ( !self::$enabled ) {
 112                         return;
 113                 }
 114
 115                 // Check to see if there was already a deprecation notice, so not to
 116                 // get a duplicate warning
 117                 $logCount = count( self::$log );
 118                 if ( $logCount ) {
 119                         $lastLog = self::$log[ $logCount - 1 ];
 120                         if ( $lastLog['type'] == 'deprecated' && $lastLog['caller'] == wfGetCaller( $callerOffset + 1 ) ) {
 121                                 return;
 122                         }
 123                 }
 124
 125                 self::$log[] = array(
 126                         'msg' => htmlspecialchars( $msg ),
 127                         'type' => 'warn',
 128                         'caller' => wfGetCaller( $callerOffset ),
 129                 );
 130         }
 131
 132         /**
 133          * Adds a depreciation entry to the log, along with a backtrace
 134          *
 135          * @param $function
 136          * @param $version
 137          * @param $component
 138          * @return mixed
 139          */
 140         public static function deprecated( $function, $version, $component ) {
 141                 if ( !self::$enabled ) {
 142                         return;
 143                 }
 144
 145                 // Chain: This function -> wfDeprecated -> deprecatedFunction -> caller
 146                 $caller = wfGetCaller( 4 );
 147
 148                 // Check to see if there already was a warning about this function
 149                 $functionString = "$function-$caller";
 150                 if ( in_array( $functionString, self::$deprecationWarnings ) ) {
 151                         return;
 152                 }
 153
 154                 $version = $version === false ? '(unknown version)' : $version;
 155                 $component = $component === false ? 'MediaWiki' : $component;
 156                 $msg = htmlspecialchars( "Use of function $function was deprecated in $component $version" );
 157                 $msg .= Html::rawElement( 'div', array( 'class' => 'mw-debug-backtrace' ),
 158                         Html::element( 'span', array(), 'Backtrace:' )
 159                          . wfBacktrace()
 160                 );
 161
 162                 self::$deprecationWarnings[] = $functionString;
 163                 self::$log[] = array(
 164                         'msg' => $msg,
 165                         'type' => 'deprecated',
 166                         'caller' => $caller,
 167                 );
 168         }
 169
 170         /**
 171          * This is a method to pass messages from wfDebug to the pretty debugger.
 172          * Do NOT use this method, use MWDebug::log or wfDebug()
 173          *
 174          * @param $str string
 175          */
 176         public static function debugMsg( $str ) {
 177                 if ( !self::$enabled ) {
 178                         return;
 179                 }
 180
 181                 self::$debug[] = trim( $str );
 182         }
 183
 184         /**
 185          * Begins profiling on a database query
 186          *
 187          * @param $sql string
 188          * @param $function string
 189          * @param $isMaster bool
 190          * @return int ID number of the query to pass to queryTime or -1 if the
 191          *  debugger is disabled
 192          */
 193         public static function query( $sql, $function, $isMaster ) {
 194                 if ( !self::$enabled ) {
 195                         return -1;
 196                 }
 197
 198                 self::$query[] = array(
 199                         'sql' => $sql,
 200                         'function' => $function,
 201                         'master' => (bool) $isMaster,
 202                         'time' > 0.0,
 203                         '_start' => microtime( true ),
 204                 );
 205
 206                 return count( self::$query ) - 1;
 207         }
 208
 209         /**
 210          * Calculates how long a query took.
 211          *
 212          * @param $id int
 213          */
 214         public static function queryTime( $id ) {
 215                 if ( $id === -1 || !self::$enabled ) {
 216                         return;
 217                 }
 218
 219                 self::$query[$id]['time'] = microtime( true ) - self::$query[$id]['_start'];
 220                 unset( self::$query[$id]['_start'] );
 221         }
 222
 223         /**
 224          * Returns a list of files included, along with their size
 225          *
 226          * @param $context IContextSource
 227          * @return array
 228          */
 229         protected static function getFilesIncluded( IContextSource $context ) {
 230                 $files = get_included_files();
 231                 $fileList = array();
 232                 foreach ( $files as $file ) {
 233                         $size = filesize( $file );
 234                         $fileList[] = array(
 235                                 'name' => $file,
 236                                 'size' => $context->getLanguage()->formatSize( $size ),
 237                         );
 238                 }
 239
 240                 return $fileList;
 241         }
 242
 243         /**
 244          * Returns the HTML to add to the page for the toolbar
 245          *
 246          * @param $context IContextSource
 247          * @return string
 248          */
 249         public static function getDebugHTML( IContextSource $context ) {
 250                 if ( !self::$enabled ) {
 251                         return '';
 252                 }
 253
 254                 global $wgVersion, $wgRequestTime;
 255                 MWDebug::log( 'MWDebug output complete' );
 256                 $request = $context->getRequest();
 257                 $debugInfo = array(
 258                         'mwVersion' => $wgVersion,
 259                         'phpVersion' => PHP_VERSION,
 260                         'time' => microtime( true ) - $wgRequestTime,
 261                         'log' => self::$log,
 262                         'debugLog' => self::$debug,
 263                         'queries' => self::$query,
 264                         'request' => array(
 265                                 'method' => $_SERVER['REQUEST_METHOD'],
 266                                 'url' => $request->getRequestURL(),
 267                                 'headers' => $request->getAllHeaders(),
 268                                 'params' => $request->getValues(),
 269                         ),
 270                         'memory' => $context->getLanguage()->formatSize( memory_get_usage() ),
 271                         'memoryPeak' => $context->getLanguage()->formatSize( memory_get_peak_usage() ),
 272                         'includes' => self::getFilesIncluded( $context ),
 273                 );
 274                 // TODO: Clean this up
 275                 $html = Html::openElement( 'script' );
 276                 $html .= 'var debugInfo = ' . Xml::encodeJsVar( $debugInfo ) . ';';
 277                 $html .= " $(function() { mw.loader.using( 'mediawiki.debug', function() { mw.Debug.init( debugInfo ) } ); }); ";
 278                 $html .= Html::closeElement( 'script' );
 279
 280                 return $html;
 281         }
 282 }