MediaWiki master
MWDebug Class Reference

Debug toolbar. More...

Static Public Member Functions

static addModules (OutputPage $out)
 Add ResourceLoader modules to the OutputPage object if debugging is enabled.
 
static appendDebugInfoToApiResult (IContextSource $context, ApiResult $result)
 Append the debug info to given ApiResult.
 
static clearDeprecationFilters ()
 Clear all deprecation filters.
 
static clearLog ()
 Clears internal log array and deprecation tracking.
 
static debugMsg ( $str, $context=[])
 This method receives messages from LoggerFactory, wfDebugLog, and MWExceptionHandler.
 
static deinit ()
 Disable the debugger.
 
static deprecated ( $function, $version=false, $component=false, $callerOffset=2)
 Show a warning that $function is deprecated.
 
static deprecatedMsg ( $msg, $version=false, $component=false, $callerOffset=2)
 Log a deprecation warning with arbitrary message text.
 
static detectDeprecatedOverride ( $instance, $class, $method, $version=false, $component=false, $callerOffset=2)
 Show a warning if $method declared in $class is overridden in $instance.
 
static filterDeprecationForTest (string $regex, ?callable $callback=null)
 Deprecation messages matching the supplied regex will be suppressed.
 
static getDebugHTML (IContextSource $context)
 Returns the HTML to add to the page for the toolbar.
 
static getDebugInfo (IContextSource $context)
 Returns the HTML to add to the page for the toolbar.
 
static getHTMLDebugLog ()
 Generate debug log in HTML for displaying at the bottom of the main content area.
 
static getLog ()
 Returns internal log array.
 
static init ()
 Enabled the debugger and load resource module.
 
static log ( $str)
 Adds a line to the log.
 
static parseCallerDescription ( $msg)
 Append a caller description to an error message.
 
static query ( $sql, $function, $runTime, $dbhost)
 Begins profiling on a database query.
 
static sendRawDeprecated ( $msg, $sendToLog=true, $callerFunc='')
 Send a raw deprecation message to the log and the debug toolbar, without filtering of duplicate messages.
 
static setup ()
 
static warning ( $msg, $callerOffset=1, $level=E_USER_NOTICE, $log='auto')
 Adds a warning entry to the log.
 

Static Protected Member Functions

static getFilesIncluded (IContextSource $context)
 Returns a list of files included, along with their size.
 

Static Protected Attributes

static array $debug = []
 Debug messages from wfDebug().
 
static array $deprecationFilters = []
 Keys are regexes, values are optional callbacks to call if the filter is hit.
 
static array $deprecationWarnings = []
 Array of functions that have already been warned, formatted function-caller to prevent a buttload of warnings.
 
static bool $enabled = false
 Is the debugger enabled?
 
static array $log = []
 Log lines.
 
static array $query = []
 SQL statements of the database queries.
 

Detailed Description

Debug toolbar.

By default most of these methods do nothing, as enforced by self::$enabled = false.

To enable the debug toolbar, use $wgDebugToolbar = true in LocalSettings.php. That ensures MWDebug::init() is called from Setup.php.

Since
1.19

Definition at line 42 of file MWDebug.php.

Member Function Documentation

◆ addModules()

static MWDebug::addModules ( OutputPage  $out)
static

Add ResourceLoader modules to the OutputPage object if debugging is enabled.

Since
1.19
Parameters
OutputPage$out

Definition at line 134 of file MWDebug.php.

References MediaWiki\Output\OutputPage\addModules().

◆ appendDebugInfoToApiResult()

static MWDebug::appendDebugInfoToApiResult ( IContextSource  $context,
ApiResult  $result 
)
static

Append the debug info to given ApiResult.

Parameters
IContextSource$context
ApiResult$result

Definition at line 706 of file MWDebug.php.

References ApiResult\addValue().

◆ clearDeprecationFilters()

static MWDebug::clearDeprecationFilters ( )
static

Clear all deprecation filters.

Definition at line 402 of file MWDebug.php.

◆ clearLog()

static MWDebug::clearLog ( )
static

Clears internal log array and deprecation tracking.

Since
1.19

Definition at line 173 of file MWDebug.php.

◆ debugMsg()

static MWDebug::debugMsg (   $str,
  $context = [] 
)
static

This method receives messages from LoggerFactory, wfDebugLog, and MWExceptionHandler.

Do NOT call this method directly.

Access: internal
For use by MWExceptionHandler and LegacyLogger only
Since
1.19
Parameters
string$str
array$context

Definition at line 508 of file MWDebug.php.

References $wgDebugComments, and $wgShowDebug.

Referenced by MediaWiki\Logger\LegacyLogger\log().

◆ deinit()

static MWDebug::deinit ( )
static

Disable the debugger.

Since
1.28

Definition at line 123 of file MWDebug.php.

◆ deprecated()

static MWDebug::deprecated (   $function,
  $version = false,
  $component = false,
  $callerOffset = 2 
)
static

Show a warning that $function is deprecated.

See also
deprecatedMsg()
Since
1.19
Parameters
string$functionFunction that is deprecated.
string | false$versionVersion in which the function was deprecated.
string | bool$componentComponent to which the function belongs. If false, it is assumed the function is in MediaWiki core.
int$callerOffsetHow far up the callstack is the original caller. 2 = function that called the function that called MWDebug::deprecated() (Added in 1.20).

Definition at line 222 of file MWDebug.php.

◆ deprecatedMsg()

static MWDebug::deprecatedMsg (   $msg,
  $version = false,
  $component = false,
  $callerOffset = 2 
)
static

Log a deprecation warning with arbitrary message text.

A caller description will be appended. If the message has already been sent for this caller, it won't be sent again.

Although there are component and version parameters, they are not automatically appended to the message. The message text should include information about when the thing was deprecated.

The warning will be sent to the following locations:

  • Debug toolbar, with one item per function and caller, if $wgDebugToolbar is set to true.
  • PHP's error log, with level E_USER_DEPRECATED, if $wgDevelopmentWarnings is set to true. This is the case in phpunit tests per default, and will cause tests to fail.
  • MediaWiki's debug log, if $wgDevelopmentWarnings is set to false.
Since
1.35
Parameters
string$msgThe message
string | false$versionVersion of MediaWiki that the function was deprecated in.
string | bool$componentComponent to which the function belongs. If false, it is assumed the function is in MediaWiki core.
int | false$callerOffsetHow far up the call stack is the original caller. 2 = function that called the function that called us. If false, the caller description will not be appended.

Definition at line 304 of file MWDebug.php.

References $wgDeprecationReleaseLimit.

◆ detectDeprecatedOverride()

static MWDebug::detectDeprecatedOverride (   $instance,
  $class,
  $method,
  $version = false,
  $component = false,
  $callerOffset = 2 
)
static

Show a warning if $method declared in $class is overridden in $instance.

Since
1.36
See also
deprecatedMsg()

phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam

Parameters
object$instanceObject on which to detect deprecated overrides (typically $this).
string$classClass declaring the deprecated method (typically CLASS )
string$methodThe name of the deprecated method.
string | false$versionVersion in which the method was deprecated. Does not issue deprecation warnings if false.
string | bool$componentComponent to which the class belongs. If false, it is assumed the class is in MediaWiki core.
int$callerOffsetHow far up the callstack is the original caller. 2 = function that called the function that called MWDebug::detectDeprecatedOverride()
Returns
bool True if the method was overridden, false otherwise. If the method was overridden, it should be called. The deprecated method's default implementation should call MWDebug::deprecated().

Definition at line 256 of file MWDebug.php.

◆ filterDeprecationForTest()

static MWDebug::filterDeprecationForTest ( string  $regex,
?callable  $callback = null 
)
static

Deprecation messages matching the supplied regex will be suppressed.

Use this to filter deprecation warnings when testing deprecated code.

Parameters
string$regex
?callable$callback To call if $regex is hit

Definition at line 390 of file MWDebug.php.

◆ getDebugHTML()

static MWDebug::getDebugHTML ( IContextSource  $context)
static

Returns the HTML to add to the page for the toolbar.

Since
1.19
Parameters
IContextSource$context
Returns
WrappedStringList

Definition at line 645 of file MWDebug.php.

References $wgDebugComments.

◆ getDebugInfo()

static MWDebug::getDebugInfo ( IContextSource  $context)
static

Returns the HTML to add to the page for the toolbar.

Parameters
IContextSource$context
Returns
array

Definition at line 740 of file MWDebug.php.

References MediaWiki\Context\IContextSource\getLanguage(), MediaWiki\Context\IContextSource\getRequest(), and MW_VERSION.

◆ getFilesIncluded()

static MWDebug::getFilesIncluded ( IContextSource  $context)
staticprotected

Returns a list of files included, along with their size.

Parameters
IContextSource$context
Returns
array

Definition at line 617 of file MWDebug.php.

References MediaWiki\Context\IContextSource\getLanguage().

◆ getHTMLDebugLog()

static MWDebug::getHTMLDebugLog ( )
static

Generate debug log in HTML for displaying at the bottom of the main content area.

If $wgShowDebug is false, an empty string is always returned.

Since
1.20
Returns
WrappedStringList HTML fragment

Definition at line 680 of file MWDebug.php.

References $wgShowDebug.

◆ getLog()

static MWDebug::getLog ( )
static

Returns internal log array.

Since
1.19
Returns
array

Definition at line 165 of file MWDebug.php.

◆ init()

static MWDebug::init ( )
static

Enabled the debugger and load resource module.

This is called by Setup.php when $wgDebugToolbar is true.

Since
1.19

Definition at line 114 of file MWDebug.php.

◆ log()

static MWDebug::log (   $str)
static

Adds a line to the log.

Since
1.19
Parameters
mixed$str

Definition at line 146 of file MWDebug.php.

References wfGetCaller().

◆ parseCallerDescription()

static MWDebug::parseCallerDescription (   $msg)
static

Append a caller description to an error message.

Access: internal
For use by MWExceptionHandler to override 'exception.file' in error logs.
Parameters
string$msgFormatted message from formatCallerDescription() and getCallerDescription()
Returns
null|array<string,string> Null if unable to recognise all parts, or array with:
  • 'file': string of file path
  • 'line': string of line number
  • 'func': string of function or method name
  • 'message': Re-formatted version of $msg for use with ErrorException, so as to not include file/line twice.

Definition at line 467 of file MWDebug.php.

◆ query()

static MWDebug::query (   $sql,
  $function,
  $runTime,
  $dbhost 
)
static

Begins profiling on a database query.

Since
1.19
Parameters
string$sql
string$function
float$runTimeQuery run time
string$dbhost
Returns
bool True if debugger is enabled, false otherwise

Definition at line 572 of file MWDebug.php.

Referenced by MediaWiki\Logger\LegacyLogger\log().

◆ sendRawDeprecated()

static MWDebug::sendRawDeprecated (   $msg,
  $sendToLog = true,
  $callerFunc = '' 
)
static

Send a raw deprecation message to the log and the debug toolbar, without filtering of duplicate messages.

A caller description will not be appended.

Parameters
string$msgThe complete message including relevant caller information.
bool$sendToLogIf true, the message will be sent to the debug toolbar, the debug log, and raised as a warning to PHP. If false, the message will only be sent to the debug toolbar.
string$callerFuncThe caller, for display in the debug toolbar's caller column.

Definition at line 368 of file MWDebug.php.

◆ setup()

static MWDebug::setup ( )
static
Access: internal
For use by Setup.php only.

Definition at line 87 of file MWDebug.php.

References $wgDebugToolbar, $wgUseCdn, $wgUseFileCache, and MW_ENTRY_POINT.

◆ warning()

static MWDebug::warning (   $msg,
  $callerOffset = 1,
  $level = E_USER_NOTICE,
  $log = 'auto' 
)
static

Adds a warning entry to the log.

Since
1.19
Parameters
string$msg
int$callerOffset
int$levelA PHP error level. See sendMessage()
string$log'production' will always trigger a php error, 'auto' will trigger an error if $wgDevelopmentWarnings is true, and 'debug' will only write to the debug log(s).

Definition at line 189 of file MWDebug.php.

References $wgDevelopmentWarnings.

Member Data Documentation

◆ $debug

array MWDebug::$debug = []
staticprotected

Debug messages from wfDebug().

Definition at line 55 of file MWDebug.php.

◆ $deprecationFilters

array MWDebug::$deprecationFilters = []
staticprotected

Keys are regexes, values are optional callbacks to call if the filter is hit.

Definition at line 82 of file MWDebug.php.

◆ $deprecationWarnings

array MWDebug::$deprecationWarnings = []
staticprotected

Array of functions that have already been warned, formatted function-caller to prevent a buttload of warnings.

Definition at line 77 of file MWDebug.php.

◆ $enabled

bool MWDebug::$enabled = false
staticprotected

Is the debugger enabled?

Definition at line 69 of file MWDebug.php.

◆ $log

array MWDebug::$log = []
staticprotected

Log lines.

Definition at line 48 of file MWDebug.php.

◆ $query

array MWDebug::$query = []
staticprotected

SQL statements of the database queries.

Definition at line 62 of file MWDebug.php.


The documentation for this class was generated from the following file: