includes/debug/Debug.php

   1 <?php
   2
   3 /**
   4  * New debugger system that outputs a toolbar on page view
   5  *
   6  * @todo Profiler support
   7  */
   8 class MWDebug {
   9
  10         /**
  11          * Log lines
  12          *
  13          * @var array
  14          */
  15         protected static $log = array();
  16
  17         /**
  18          * Debug messages from wfDebug()
  19          *
  20          * @var array
  21          */
  22         protected static $debug = array();
  23
  24         /**
  25          * Queries
  26          *
  27          * @var array
  28          */
  29         protected static $query = array();
  30
  31         /**
  32          * Request information
  33          *
  34          * @var array
  35          */
  36         protected static $request = array();
  37
  38         /**
  39          * Is the debugger enabled?
  40          *
  41          * @var bool
  42          */
  43         protected static $enabled = true;
  44
  45         /**
  46          * Array of functions that have already been warned, formatted
  47          * function-caller to prevent a buttload of warnings
  48          *
  49          * @var array
  50          */
  51         protected static $deprecationWarnings = array();
  52
  53         /**
  54          * Called in Setup.php, initializes the debugger if it is enabled with
  55          * $wgDebugToolbar
  56          */
  57         public static function init() {
  58                 global $wgDebugToolbar;
  59
  60                 if ( !$wgDebugToolbar ) {
  61                         self::$enabled = false;
  62                         return;
  63                 }
  64
  65                 RequestContext::getMain()->getOutput()->addModules( 'mediawiki.debug' );
  66         }
  67
  68         /**
  69          * Adds a line to the log
  70          *
  71          * @todo Add support for passing objects
  72          *
  73          * @param $str string
  74          */
  75         public static function log( $str ) {
  76                 if ( !self::$enabled ) {
  77                         return;
  78                 }
  79
  80                 self::$log[] = array(
  81                         'msg' => htmlspecialchars( $str ),
  82                         'type' => 'log',
  83                         'caller' => wfGetCaller(),
  84                 );
  85         }
  86
  87         /**
  88          * Adds a warning entry to the log
  89          *
  90          * @param $msg
  91          * @param int $callerOffset
  92          * @return mixed
  93          */
  94         public static function warning( $msg, $callerOffset = 1 ) {
  95                 if ( !self::$enabled ) {
  96                         return;
  97                 }
  98
  99                 // Check to see if there was already a deprecation notice, so not to
 100                 // get a duplicate warning
 101                 if ( count( self::$log ) ) {
 102                         $lastLog = self::$log[ count( self::$log ) - 1 ];
 103                         if ( $lastLog['type'] == 'deprecated' && $lastLog['caller'] == wfGetCaller( $callerOffset + 1 ) ) {
 104                                 return;
 105                         }
 106                 }
 107
 108                 self::$log[] = array(
 109                         'msg' => htmlspecialchars( $msg ),
 110                         'type' => 'warn',
 111                         'caller' => wfGetCaller( $callerOffset ),
 112                 );
 113         }
 114
 115         /**
 116          * Adds a depreciation entry to the log, along with a backtrace
 117          *
 118          * @param $function
 119          * @param $version
 120          * @param $component
 121          * @return mixed
 122          */
 123         public static function deprecated( $function, $version, $component ) {
 124                 if ( !self::$enabled ) {
 125                         return;
 126                 }
 127
 128                 // Chain: This function -> wfDeprecated -> deprecatedFunction -> caller
 129                 $caller = wfGetCaller( 4 );
 130
 131                 // Check to see if there already was a warning about this function
 132                 $functionString = "$function-$caller";
 133                 if ( in_array( $functionString, self::$deprecationWarnings ) ) {
 134                         return;
 135                 }
 136
 137                 $version = $version === false ? '(unknown version)' : $version;
 138                 $component = $component === false ? 'MediaWiki' : $component;
 139                 $msg = htmlspecialchars( "Use of function $function was deprecated in $component $version" );
 140                 $msg .= Html::rawElement( 'div', array( 'class' => 'mw-debug-backtrace' ),
 141                         Html::element( 'span', array(), 'Backtrace:' )
 142                          . wfBacktrace()
 143                 );
 144
 145                 self::$deprecationWarnings[] = $functionString;
 146                 self::$log[] = array(
 147                         'msg' => $msg,
 148                         'type' => 'deprecated',
 149                         'caller' => $caller,
 150                 );
 151         }
 152
 153         /**
 154          * This is a method to pass messages from wfDebug to the pretty debugger.
 155          * Do NOT use this method, use MWDebug::log or wfDebug()
 156          *
 157          * @param $str string
 158          */
 159         public static function debugMsg( $str ) {
 160                 if ( !self::$enabled ) {
 161                         return;
 162                 }
 163
 164                 self::$debug[] = trim( $str );
 165         }
 166
 167         /**
 168          * Begins profiling on a database query
 169          *
 170          * @param $sql string
 171          * @param $function string
 172          * @param $isMaster bool
 173          * @return int ID number of the query to pass to queryTime or -1 if the
 174          *  debugger is disabled
 175          */
 176         public static function query( $sql, $function, $isMaster ) {
 177                 if ( !self::$enabled ) {
 178                         return -1;
 179                 }
 180
 181                 self::$query[] = array(
 182                         'sql' => $sql,
 183                         'function' => $function,
 184                         'master' => (bool) $isMaster,
 185                         'time' > 0.0,
 186                         '_start' => wfTime(),
 187                 );
 188
 189                 return count( self::$query ) - 1;
 190         }
 191
 192         /**
 193          * Calculates how long a query took.
 194          *
 195          * @param $id int
 196          */
 197         public static function queryTime( $id ) {
 198                 if ( $id === -1 || !self::$enabled ) {
 199                         return;
 200                 }
 201
 202                 self::$query[$id]['time'] = wfTime() - self::$query[$id]['_start'];
 203                 unset( self::$query[$id]['_start'] );
 204         }
 205
 206         /**
 207          * Processes a WebRequest object
 208          *
 209          * @param $request WebRequest
 210          */
 211         public static function processRequest( WebRequest $request ) {
 212                 if ( !self::$enabled ) {
 213                         return;
 214                 }
 215
 216                 self::$request = array(
 217                         'method' => $_SERVER['REQUEST_METHOD'],
 218                         'url' => $request->getRequestURL(),
 219                         'headers' => $request->getAllHeaders(),
 220                         'params' => $request->getValues(),
 221                 );
 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                 $debugInfo = array(
 258                         'mwVersion' => $wgVersion,
 259                         'phpVersion' => PHP_VERSION,
 260                         'time' => wfTime() - $wgRequestTime,
 261                         'log' => self::$log,
 262                         'debugLog' => self::$debug,
 263                         'queries' => self::$query,
 264                         'request' => self::$request,
 265                         'memory' => $context->getLanguage()->formatSize( memory_get_usage() ),
 266                         'memoryPeak' => $context->getLanguage()->formatSize( memory_get_peak_usage() ),
 267                         'includes' => self::getFilesIncluded( $context ),
 268                 );
 269                 // TODO: Clean this up
 270                 $html = Html::openElement( 'script' );
 271                 $html .= 'var debugInfo = ' . Xml::encodeJsVar( $debugInfo ) . ';';
 272                 $html .= " $(function() { mw.loader.using( 'mediawiki.debug', function() { mw.Debug.init( debugInfo ) } ); }); ";
 273                 $html .= Html::closeElement( 'script' );
 274
 275                 return $html;
 276         }
 277 }