includes/debug/Debug.php

   1 <?php
   2 /**
   3  * Debug toolbar related code
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * New debugger system that outputs a toolbar on page view
  25  *
  26  * By default, most methods do nothing ( self::$enabled = false ). You have
  27  * to explicitly call MWDebug::init() to enabled them.
  28  *
  29  * @todo Profiler support
  30  */
  31 class MWDebug {
  32
  33         /**
  34          * Log lines
  35          *
  36          * @var array
  37          */
  38         protected static $log = array();
  39
  40         /**
  41          * Debug messages from wfDebug()
  42          *
  43          * @var array
  44          */
  45         protected static $debug = array();
  46
  47         /**
  48          * Queries
  49          *
  50          * @var array
  51          */
  52         protected static $query = array();
  53
  54         /**
  55          * Is the debugger enabled?
  56          *
  57          * @var bool
  58          */
  59         protected static $enabled = false;
  60
  61         /**
  62          * Array of functions that have already been warned, formatted
  63          * function-caller to prevent a buttload of warnings
  64          *
  65          * @var array
  66          */
  67         protected static $deprecationWarnings = array();
  68
  69         /**
  70          * Enabled the debugger and load resource module.
  71          * This is called by Setup.php when $wgDebugToolbar is true.
  72          */
  73         public static function init() {
  74                 self::$enabled = true;
  75         }
  76
  77         /**
  78          * Add ResourceLoader modules to the OutputPage object if debugging is
  79          * enabled.
  80          *
  81          * @param $out OutputPage
  82          */
  83         public static function addModules( OutputPage $out ) {
  84                 if ( self::$enabled ) {
  85                         $out->addModules( 'mediawiki.debug.init' );
  86                 }
  87         }
  88
  89         /**
  90          * Adds a line to the log
  91          *
  92          * @todo Add support for passing objects
  93          *
  94          * @param $str string
  95          */
  96         public static function log( $str ) {
  97                 if ( !self::$enabled ) {
  98                         return;
  99                 }
 100
 101                 self::$log[] = array(
 102                         'msg' => htmlspecialchars( $str ),
 103                         'type' => 'log',
 104                         'caller' => wfGetCaller(),
 105                 );
 106         }
 107
 108         /**
 109          * Returns internal log array
 110          * @return array
 111          */
 112         public static function getLog() {
 113                 return self::$log;
 114         }
 115
 116         /**
 117          * Clears internal log array and deprecation tracking
 118          */
 119         public static function clearLog() {
 120                 self::$log = array();
 121                 self::$deprecationWarnings = array();
 122         }
 123
 124         /**
 125          * Adds a warning entry to the log
 126          *
 127          * @param $msg
 128          * @param int $callerOffset
 129          * @return mixed
 130          */
 131         public static function warning( $msg, $callerOffset = 1 ) {
 132                 if ( !self::$enabled ) {
 133                         return;
 134                 }
 135
 136                 // Check to see if there was already a deprecation notice, so not to
 137                 // get a duplicate warning
 138                 $logCount = count( self::$log );
 139                 if ( $logCount ) {
 140                         $lastLog = self::$log[ $logCount - 1 ];
 141                         if ( $lastLog['type'] == 'deprecated' && $lastLog['caller'] == wfGetCaller( $callerOffset + 1 ) ) {
 142                                 return;
 143                         }
 144                 }
 145
 146                 self::$log[] = array(
 147                         'msg' => htmlspecialchars( $msg ),
 148                         'type' => 'warn',
 149                         'caller' => wfGetCaller( $callerOffset ),
 150                 );
 151         }
 152
 153         /**
 154          * Adds a depreciation entry to the log, along with a backtrace
 155          *
 156          * @param $function
 157          * @param $version
 158          * @param $component
 159          * @return mixed
 160          */
 161         public static function deprecated( $function, $version, $component ) {
 162                 if ( !self::$enabled ) {
 163                         return;
 164                 }
 165
 166                 // Chain: This function -> wfDeprecated -> deprecatedFunction -> caller
 167                 $caller = wfGetCaller( 4 );
 168
 169                 // Check to see if there already was a warning about this function
 170                 $functionString = "$function-$caller";
 171                 if ( in_array( $functionString, self::$deprecationWarnings ) ) {
 172                         return;
 173                 }
 174
 175                 $version = $version === false ? '(unknown version)' : $version;
 176                 $component = $component === false ? 'MediaWiki' : $component;
 177                 $msg = htmlspecialchars( "Use of function $function was deprecated in $component $version" );
 178                 $msg .= Html::rawElement( 'div', array( 'class' => 'mw-debug-backtrace' ),
 179                         Html::element( 'span', array(), 'Backtrace:' )
 180                          . wfBacktrace()
 181                 );
 182
 183                 self::$deprecationWarnings[] = $functionString;
 184                 self::$log[] = array(
 185                         'msg' => $msg,
 186                         'type' => 'deprecated',
 187                         'caller' => $caller,
 188                 );
 189         }
 190
 191         /**
 192          * This is a method to pass messages from wfDebug to the pretty debugger.
 193          * Do NOT use this method, use MWDebug::log or wfDebug()
 194          *
 195          * @param $str string
 196          */
 197         public static function debugMsg( $str ) {
 198                 if ( !self::$enabled ) {
 199                         return;
 200                 }
 201
 202                 self::$debug[] = trim( $str );
 203         }
 204
 205         /**
 206          * Begins profiling on a database query
 207          *
 208          * @param $sql string
 209          * @param $function string
 210          * @param $isMaster bool
 211          * @return int ID number of the query to pass to queryTime or -1 if the
 212          *  debugger is disabled
 213          */
 214         public static function query( $sql, $function, $isMaster ) {
 215                 if ( !self::$enabled ) {
 216                         return -1;
 217                 }
 218
 219                 self::$query[] = array(
 220                         'sql' => $sql,
 221                         'function' => $function,
 222                         'master' => (bool) $isMaster,
 223                         'time' => 0.0,
 224                         '_start' => microtime( true ),
 225                 );
 226
 227                 return count( self::$query ) - 1;
 228         }
 229
 230         /**
 231          * Calculates how long a query took.
 232          *
 233          * @param $id int
 234          */
 235         public static function queryTime( $id ) {
 236                 if ( $id === -1 || !self::$enabled ) {
 237                         return;
 238                 }
 239
 240                 self::$query[$id]['time'] = microtime( true ) - self::$query[$id]['_start'];
 241                 unset( self::$query[$id]['_start'] );
 242         }
 243
 244         /**
 245          * Returns a list of files included, along with their size
 246          *
 247          * @param $context IContextSource
 248          * @return array
 249          */
 250         protected static function getFilesIncluded( IContextSource $context ) {
 251                 $files = get_included_files();
 252                 $fileList = array();
 253                 foreach ( $files as $file ) {
 254                         $size = filesize( $file );
 255                         $fileList[] = array(
 256                                 'name' => $file,
 257                                 'size' => $context->getLanguage()->formatSize( $size ),
 258                         );
 259                 }
 260
 261                 return $fileList;
 262         }
 263
 264         /**
 265          * Returns the HTML to add to the page for the toolbar
 266          *
 267          * @param $context IContextSource
 268          * @return string
 269          */
 270         public static function getDebugHTML( IContextSource $context ) {
 271                 if ( !self::$enabled ) {
 272                         return '';
 273                 }
 274
 275                 global $wgVersion, $wgRequestTime;
 276                 MWDebug::log( 'MWDebug output complete' );
 277                 $request = $context->getRequest();
 278                 $debugInfo = array(
 279                         'mwVersion' => $wgVersion,
 280                         'phpVersion' => PHP_VERSION,
 281                         'gitRevision' => GitInfo::headSHA1(),
 282                         'gitBranch' => GitInfo::currentBranch(),
 283                         'gitViewUrl' => GitInfo::headViewUrl(),
 284                         'time' => microtime( true ) - $wgRequestTime,
 285                         'log' => self::$log,
 286                         'debugLog' => self::$debug,
 287                         'queries' => self::$query,
 288                         'request' => array(
 289                                 'method' => $_SERVER['REQUEST_METHOD'],
 290                                 'url' => $request->getRequestURL(),
 291                                 'headers' => $request->getAllHeaders(),
 292                                 'params' => $request->getValues(),
 293                         ),
 294                         'memory' => $context->getLanguage()->formatSize( memory_get_usage() ),
 295                         'memoryPeak' => $context->getLanguage()->formatSize( memory_get_peak_usage() ),
 296                         'includes' => self::getFilesIncluded( $context ),
 297                 );
 298
 299                 // Cannot use OutputPage::addJsConfigVars because those are already outputted
 300                 // by the time this method is called.
 301                 $html = Html::inlineScript(
 302                         ResourceLoader::makeLoaderConditionalScript(
 303                                 ResourceLoader::makeConfigSetScript( array( 'debugInfo' => $debugInfo ) )
 304                         )
 305                 );
 306
 307                 return $html;
 308         }
 309 }