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