Handler class for MWExceptions. More...

Static Public Member Functions
static	getLogContext ( $e, $catcher=self::CAUGHT_BY_OTHER)
	Get a PSR-3 log event context from an Exception. More...

static	getLogId ( $e)
	Get the ID for this exception. More...

static	getLogMessage ( $e)
	Get a message formatting the exception message and its origin. More...

static	getLogNormalMessage ( $e)
	Get a normalised message for formatting with PSR-3 log event context. More...

static	getPublicLogMessage ( $e)

static	getRedactedTrace ( $e)
	Return a copy of an exception's backtrace as an array. More...

static	getRedactedTraceAsString ( $e)
	Generate a string representation of an exception's stack trace. More...

static	getStructuredExceptionData ( $e, $catcher=self::CAUGHT_BY_OTHER)
	Get a structured representation of an Exception. More...

static	getURL ()
	If the exception occurred in the course of responding to a request, returns the requested URL. More...

static	handleError ( $level, $message, $file=null, $line=null)
	Handler for set_error_handler() callback notifications. More...

static	handleException ( $e)
	Exception handler which simulates the appropriate catch() handling: More...

static	handleFatalError ( $level=null, $message=null, $file=null, $line=null, $context=null, $trace=null)
	Dual purpose callback used as both a set_error_handler() callback and a registered shutdown function. More...

static	installHandler ()
	Install handlers with PHP. More...

static	jsonSerializeException ( $e, $pretty=false, $escaping=0, $catcher=self::CAUGHT_BY_OTHER)
	Serialize an Exception object to JSON. More...

static	logException ( $e, $catcher=self::CAUGHT_BY_OTHER)
	Log an exception to the exception log (if enabled). More...

static	prettyPrintTrace (array $trace, $pad='')
	Generate a string representation of a stacktrace. More...

static	redactTrace (array $trace)
	Redact a stacktrace generated by Exception::getTrace(), debug_backtrace() or similar means. More...

static	rollbackMasterChangesAndLog ( $e)
	Roll back any open database transactions and log the stack trace of the exception. More...

Public Attributes
const	CAUGHT_BY_HANDLER = 'mwe_handler'

const	CAUGHT_BY_OTHER = 'other'

Static Protected Member Functions
static	logError (ErrorException $e, $channel, $level=LogLevel::ERROR)
	Log an exception that wasn't thrown but made to wrap an error. More...

static	report ( $e)
	Report an exception to the user. More...

Static Protected Attributes
static	$fatalErrorTypes

static	$handledFatalCallback = false

static	$reservedMemory

Detailed Description

Handler class for MWExceptions.

Definition at line 30 of file MWExceptionHandler.php.

Member Function Documentation

◆ getLogContext()

static MWExceptionHandler::getLogContext	(	$e,
		$catcher = `self::CAUGHT_BY_OTHER`
	)

static

Get a PSR-3 log event context from an Exception.

Creates a structured array containing information about the provided exception that can be used to augment a log message sent to a PSR-3 logger.

Parameters

Exception \| Throwable	$e
string	$catcher	CAUGHT_BY_* class constant indicating what caught the error

Returns: array

Definition at line 485 of file MWExceptionHandler.php.

References $e, WebRequest\getRequestId(), and getURL().

◆ getLogId()

static MWExceptionHandler::getLogId ( $e )

static

Get the ID for this exception.

The ID is saved so that one can match the one output to the user (when $wgShowExceptionDetails is set to false), to the entry in the debug log.

Since: 1.22

Deprecated:: since 1.27: Exception IDs are synonymous with request IDs.

Parameters

Exception | Throwable $e

Returns: string

Definition at line 406 of file MWExceptionHandler.php.

References WebRequest\getRequestId(), and wfDeprecated().

◆ getLogMessage()

static MWExceptionHandler::getLogMessage ( $e )

static

Get a message formatting the exception message and its origin.

Since: 1.22

Parameters

Exception | Throwable $e

Returns: string

Definition at line 433 of file MWExceptionHandler.php.

References $e, $line, $type, WebRequest\getRequestId(), and getURL().

Referenced by MWException\getHTML(), MWExceptionRenderer\getHTML(), MWException\getText(), MWExceptionRenderer\getText(), and MWExceptionRenderer\output().

◆ getLogNormalMessage()

static MWExceptionHandler::getLogNormalMessage ( $e )

static

Get a normalised message for formatting with PSR-3 log event context.

Must be used together with getLogContext() to be useful.

Since: 1.30

Parameters

Exception | Throwable $e

Returns: string

Definition at line 453 of file MWExceptionHandler.php.

References $e, $line, and $type.

◆ getPublicLogMessage()

static MWExceptionHandler::getPublicLogMessage ( $e )

static

Parameters

Exception | Throwable $e

Returns: string

Definition at line 466 of file MWExceptionHandler.php.

References $e, $type, and WebRequest\getRequestId().

Referenced by MWExceptionRenderer\output().

◆ getRedactedTrace()

static MWExceptionHandler::getRedactedTrace ( $e )

static

Return a copy of an exception's backtrace as an array.

Like Exception::getTrace, but replaces each element in each frame's argument array with the name of its class (if the element is an object) or its type (if the element is a PHP primitive).

Since: 1.22

Parameters

Exception | Throwable $e

Returns: array

Definition at line 370 of file MWExceptionHandler.php.

References $e.

Referenced by MediaWiki\Logger\LegacyLogger\format(), getStructuredExceptionData(), and MWExceptionHandlerTest\testGetRedactedTrace().

◆ getRedactedTraceAsString()

static MWExceptionHandler::getRedactedTraceAsString ( $e )

static

Generate a string representation of an exception's stack trace.

Like Exception::getTraceAsString, but replaces argument values with argument type or class name.

Parameters

Exception | Throwable $e

Returns: string

See also: prettyPrintTrace()

Definition at line 311 of file MWExceptionHandler.php.

References $e, and prettyPrintTrace().

Referenced by MWException\getHTML(), MWExceptionRenderer\getHTML(), MWException\getText(), MWExceptionRenderer\getText(), MediaWiki\Logger\Monolog\LogstashFormatter\normalizeException(), MWExceptionRenderer\output(), ApiMainTest\provideExceptionErrors(), and ApiMain\substituteResultWithError().

◆ getStructuredExceptionData()

static MWExceptionHandler::getStructuredExceptionData	(	$e,
		$catcher = `self::CAUGHT_BY_OTHER`
	)

static

Get a structured representation of an Exception.

Returns an array of structured data (class, message, code, file, backtrace) derived from the given exception. The backtrace information will be redacted as per getRedactedTraceAsArray().

Parameters

Exception \| Throwable	$e
string	$catcher	CAUGHT_BY_* class constant indicating what caught the error

Returns: array

Since: 1.26

Definition at line 506 of file MWExceptionHandler.php.

References $e, $wgLogExceptionBacktrace, getRedactedTrace(), WebRequest\getRequestId(), getURL(), and global.

◆ getURL()

static MWExceptionHandler::getURL ( )

static

If the exception occurred in the course of responding to a request, returns the requested URL.

Otherwise, returns false.

Since: 1.23

Returns: string|false

Definition at line 418 of file MWExceptionHandler.php.

References $wgRequest, and global.

Referenced by MWException\getHTML(), MWExceptionRenderer\getHTML(), getLogContext(), getLogMessage(), and getStructuredExceptionData().

◆ handleError()

static MWExceptionHandler::handleError	(	$level,
		$message,
		$file = `null`,
		$line = `null`
	)

static

Handler for set_error_handler() callback notifications.

Receive a callback from the interpreter for a raised error, create an ErrorException, and log the exception to the 'error' logging channel(s). If the raised error is a fatal error type (only under HHVM) delegate to handleFatalError() instead.

Since: 1.25

Parameters

int	$level	Error level raised
string	$message
string	$file
int	$line

Returns: bool

See also: logError()

Definition at line 151 of file MWExceptionHandler.php.

References $e, $line, and logError().

◆ handleException()

static MWExceptionHandler::handleException ( $e )

static

Exception handler which simulates the appropriate catch() handling:

try { ... } catch ( Exception $e ) { $e->report(); } catch ( Exception $e ) { echo $e->__toString(); }

Since: 1.25

Parameters

Exception | Throwable $e

Definition at line 128 of file MWExceptionHandler.php.

References $e, report(), and rollbackMasterChangesAndLog().

Referenced by MediaWiki\run().

◆ handleFatalError()

static MWExceptionHandler::handleFatalError	(	$level = `null`,
		$message = `null`,
		$file = `null`,
		$line = `null`,
		$context = `null`,
		$trace = `null`
	)

static

Dual purpose callback used as both a set_error_handler() callback and a registered shutdown function.

Receive a callback from the interpreter for a raised error or system shutdown, check for a fatal error, and log to the 'fatal' logging channel.

Special handling is included for missing class errors as they may indicate that the user needs to install 3rd-party libraries via Composer or other means.

Since: 1.25

Parameters

int	$level	Error level raised
string	$message	Error message
string	$file	File that error was raised in
int	$line	Line number error was raised at
array	$context	Active symbol table point of error
array	$trace	Backtrace at point of error (undocumented HHVM feature)

Returns: bool Always returns false

Definition at line 223 of file MWExceptionHandler.php.

References $line, a, and(), by, directly, captcha-old\help, href, in, is(), not, on, or, see, user, and wfRandomString().

◆ installHandler()

static MWExceptionHandler::installHandler ( )

static

Install handlers with PHP.

Definition at line 53 of file MWExceptionHandler.php.

◆ jsonSerializeException()

static MWExceptionHandler::jsonSerializeException	(	$e,
		$pretty = `false`,
		$escaping = `0`,
		$catcher = `self::CAUGHT_BY_OTHER`
	)

static

Serialize an Exception object to JSON.

The JSON object will have keys 'id', 'file', 'line', 'message', and 'url'. These keys map to string values, with the exception of 'line', which is a number, and 'url', which may be either a string URL or or null if the exception did not occur in the context of serving a web request.

If $wgLogExceptionBacktrace is true, it will also have a 'backtrace' key, mapped to the array return value of Exception::getTrace, but with each element in each frame's "args" array (if set) replaced with the argument's class name (if the argument is an object) or type name (if the argument is a PHP primitive).

Sample JSON record ($wgLogExceptionBacktrace = false):: {

"id": "c41fb419",

"type": "MWException",

"file": "/var/www/mediawiki/includes/cache/MessageCache.php",

"line": 704,

"message": "Non-string key given",

"url": "/wiki/Main_Page"

}

Sample JSON record ($wgLogExceptionBacktrace = true):: {

"id": "dc457938",

"type": "MWException",

"file": "/vagrant/mediawiki/includes/cache/MessageCache.php",

"line": 704,

"message": "Non-string key given",

"url": "/wiki/Main_Page",

"backtrace": [{

"file": "/vagrant/mediawiki/extensions/VisualEditor/VisualEditor.hooks.php",

"line": 80,

"function": "get",

"class": "MessageCache",

"type": "->",

"args": ["array"]

}]

}

Since: 1.23

Parameters

Exception \| Throwable	$e
bool	$pretty	Add non-significant whitespace to improve readability (default: false).
int	$escaping	Bitfield consisting of FormatJson::.*_OK class constants.
string	$catcher	CAUGHT_BY_* class constant indicating what caught the error

Returns: string|false JSON string if successful; false upon failure

Definition at line 593 of file MWExceptionHandler.php.

References $e, and FormatJson\encode().

Referenced by logError(), logException(), MWExceptionTest\testJsonserializeexceptionBacktracingDisabled(), MWExceptionTest\testJsonserializeexceptionBacktracingEnabled(), MWExceptionTest\testJsonserializeexceptionKeys(), and MWExceptionTest\testJsonSerializeExceptions().

◆ logError()

static MWExceptionHandler::logError	(	ErrorException	$e,
			$channel,
			$level = `LogLevel::ERROR`
	)

staticprotected

Log an exception that wasn't thrown but made to wrap an error.

Since: 1.25

Parameters

ErrorException	$e
string	$channel
string	$level

Definition at line 639 of file MWExceptionHandler.php.

References $e, $suppressed, FormatJson\ALL_OK, CAUGHT_BY_HANDLER, jsonSerializeException(), and Hooks\run().

Referenced by handleError().

◆ logException()

static MWExceptionHandler::logException	(	$e,
		$catcher = `self::CAUGHT_BY_OTHER`
	)

static

Log an exception to the exception log (if enabled).

This method must not assume the exception is an MWException, it is also used to handle PHP exceptions or exceptions from other libraries.

Since: 1.22

Parameters

Exception \| Throwable	$e
string	$catcher	CAUGHT_BY_* class constant indicating what caught the error

Definition at line 613 of file MWExceptionHandler.php.

References $e, FormatJson\ALL_OK, jsonSerializeException(), and Hooks\run().

Referenced by JobQueueSecondTestQueue\doBatchPush(), WikiPage\doViewUpdates(), JobRunner\executeJob(), ResourceLoaderStartUpModule\getModuleRegistrations(), JobQueueGroup\push(), JobQueueGroup\pushLazyJobs(), rollbackMasterChangesAndLog(), User\saveSettings(), and MediaWiki\triggerJobs().

◆ prettyPrintTrace()

static MWExceptionHandler::prettyPrintTrace	(	array	$trace,
			$pad = `''`
	)

static

Generate a string representation of a stacktrace.

Parameters

array	$trace
string	$pad	Constant padding to add to each line of trace

Returns: string

Since: 1.26

Definition at line 323 of file MWExceptionHandler.php.

References as.

Referenced by MediaWiki\Logger\LegacyLogger\format(), getRedactedTraceAsString(), and MediaWiki\Logger\Monolog\LineFormatter\normalizeExceptionArray().

◆ redactTrace()

static MWExceptionHandler::redactTrace ( array $trace )

static

Redact a stacktrace generated by Exception::getTrace(), debug_backtrace() or similar means.

Replaces each element in each frame's argument array with the name of its class (if the element is an object) or its type (if the element is a PHP primitive).

Since: 1.26

Parameters

array $trace Stacktrace

Returns: array Stacktrace with arugment values converted to data types

Definition at line 384 of file MWExceptionHandler.php.

Referenced by MediaWiki\Logger\Monolog\LineFormatter\exceptionAsArray().

◆ report()

static MWExceptionHandler::report ( $e )

staticprotected

Report an exception to the user.

Parameters

Exception | Throwable $e

Definition at line 66 of file MWExceptionHandler.php.

References $e, MWExceptionRenderer\AS_PRETTY, MWExceptionRenderer\AS_RAW, and MWExceptionRenderer\output().

Referenced by handleException().

◆ rollbackMasterChangesAndLog()

static MWExceptionHandler::rollbackMasterChangesAndLog ( $e )

static

Roll back any open database transactions and log the stack trace of the exception.

This method is used to attempt to recover from exceptions

Since: 1.23

Parameters

Exception | Throwable $e

Definition at line 93 of file MWExceptionHandler.php.

References $e, $services, and logException().

Referenced by MediaWiki\doPostOutputShutdown(), JobRunner\executeJob(), handleException(), ApiMain\handleException(), AssembleUploadChunksJob\run(), PublishStashedFileJob\run(), and DeferredUpdates\runUpdate().

Member Data Documentation

◆ $fatalErrorTypes

array MWExceptionHandler::$fatalErrorTypes

staticprotected

Initial value:

= [
        E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR,
         16777217,
    ]

Definition at line 41 of file MWExceptionHandler.php.

◆ $handledFatalCallback

bool MWExceptionHandler::$handledFatalCallback = false

staticprotected

Definition at line 48 of file MWExceptionHandler.php.

◆ $reservedMemory

string MWExceptionHandler::$reservedMemory

staticprotected

Definition at line 37 of file MWExceptionHandler.php.

◆ CAUGHT_BY_HANDLER

const MWExceptionHandler::CAUGHT_BY_HANDLER = 'mwe_handler'

Definition at line 31 of file MWExceptionHandler.php.

Referenced by logError().

◆ CAUGHT_BY_OTHER

const MWExceptionHandler::CAUGHT_BY_OTHER = 'other'

Definition at line 32 of file MWExceptionHandler.php.

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

includes/exception/MWExceptionHandler.php

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ getLogContext()

◆ getLogId()

◆ getLogMessage()

◆ getLogNormalMessage()

◆ getPublicLogMessage()

◆ getRedactedTrace()

◆ getRedactedTraceAsString()

◆ getStructuredExceptionData()

◆ getURL()

◆ handleError()

◆ handleException()

◆ handleFatalError()

◆ installHandler()

◆ jsonSerializeException()

◆ logError()

◆ logException()

◆ prettyPrintTrace()

◆ redactTrace()

◆ report()

◆ rollbackMasterChangesAndLog()

Member Data Documentation

◆ $fatalErrorTypes

◆ $handledFatalCallback

◆ $reservedMemory

◆ CAUGHT_BY_HANDLER

◆ CAUGHT_BY_OTHER