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