MediaWiki  1.34.0
MWExceptionHandler Class Reference

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 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 handleUncaughtException ( $e)
 Callback to use with PHP's set_exception_handler. 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, $extraData=[])
 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
 Error types that, if unhandled, are fatal to the request. More...
 
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$catcherCAUGHT_BY_* class constant indicating what caught the error
Returns
array

Definition at line 562 of file MWExceptionHandler.php.

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

Referenced by logException().

◆ 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 510 of file MWExceptionHandler.php.

References $file, $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 530 of file MWExceptionHandler.php.

References $file, $line, and $type.

◆ getPublicLogMessage()

static MWExceptionHandler::getPublicLogMessage (   $e)
static
Parameters
Exception | Throwable$e
Returns
string

Definition at line 543 of file MWExceptionHandler.php.

References $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 463 of file MWExceptionHandler.php.

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

◆ 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 404 of file MWExceptionHandler.php.

References prettyPrintTrace().

Referenced by MWException\getHTML(), MWExceptionRenderer\getHTML(), MWException\getText(), MWExceptionRenderer\getText(), MediaWiki\Logger\Monolog\LogstashFormatter\normalizeException(), MWExceptionRenderer\output(), 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$catcherCAUGHT_BY_* class constant indicating what caught the error
Returns
array
Since
1.26

Definition at line 583 of file MWExceptionHandler.php.

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

Referenced by MediaWiki\Rest\ResponseFactory\createFromException().

◆ 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 495 of file MWExceptionHandler.php.

References $wgRequest.

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$levelError level raised
string$message
string | null$file
int | null$line
Returns
bool
See also
logError()

Definition at line 216 of file MWExceptionHandler.php.

References $file, $line, $wgPropagateErrors, handleFatalError(), 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 193 of file MWExceptionHandler.php.

References report(), and rollbackMasterChangesAndLog().

Referenced by handleUncaughtException(), and 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 | null$levelError level raised
string | null$messageError message
string | null$fileFile that error was raised in
int | null$lineLine number error was raised at
array | null$contextActive symbol table point of error
array | null$traceBacktrace at point of error (undocumented HHVM feature)
Returns
bool Always returns false

Definition at line 306 of file MWExceptionHandler.php.

References $file, $line, WebRequest\getGlobalRequestURL(), and WebRequest\getRequestId().

Referenced by handleError().

◆ handleUncaughtException()

static MWExceptionHandler::handleUncaughtException (   $e)
static

Callback to use with PHP's set_exception_handler.

Since
1.31
Parameters
Exception | Throwable$e

Definition at line 166 of file MWExceptionHandler.php.

References handleException(), and wfIsCLI().

◆ installHandler()

static MWExceptionHandler::installHandler ( )
static

Install handlers with PHP.

Definition at line 76 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$prettyAdd non-significant whitespace to improve readability (default: false).
int$escapingBitfield consisting of FormatJson::.*_OK class constants.
string$catcherCAUGHT_BY_* class constant indicating what caught the error
Returns
string|false JSON string if successful; false upon failure

Definition at line 670 of file MWExceptionHandler.php.

References FormatJson\encode().

Referenced by logError(), and logException().

◆ 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 721 of file MWExceptionHandler.php.

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

Referenced by handleError().

◆ logException()

static MWExceptionHandler::logException (   $e,
  $catcher = self::CAUGHT_BY_OTHER,
  $extraData = [] 
)
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.

Parameters
Exception | Throwable$e
string$catcherCAUGHT_BY_* class constant indicating what caught the error
array$extraData(since 1.34) Additional data to log
Since
1.22

Definition at line 691 of file MWExceptionHandler.php.

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

Referenced by MediaWiki\doPostOutputShutdown(), JobQueueEnqueueUpdate\doUpdate(), MediaWiki\emitBufferedStatsdData(), ChangesListSpecialPage\execute(), JobRunner\executeJob(), MediaWiki\preOutputCommit(), JobQueueGroup\push(), rollbackMasterChangesAndLog(), PageImages\Job\InitImageDataJob\run(), User\saveSettings(), and MediaWiki\triggerJobs().

◆ prettyPrintTrace()

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

Generate a string representation of a stacktrace.

Parameters
array$trace
string$padConstant padding to add to each line of trace
Returns
string
Since
1.26

Definition at line 416 of file MWExceptionHandler.php.

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$traceStacktrace
Returns
array Stacktrace with arugment values converted to data types

Definition at line 477 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 112 of file MWExceptionHandler.php.

References 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 139 of file MWExceptionHandler.php.

References logException().

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

Member Data Documentation

◆ $fatalErrorTypes

array MWExceptionHandler::$fatalErrorTypes
staticprotected
Initial value:
= [
E_ERROR,
E_PARSE,
E_CORE_ERROR,
E_COMPILE_ERROR,
E_USER_ERROR,
E_RECOVERABLE_ERROR,
16777217,
]

Error types that, if unhandled, are fatal to the request.

On PHP 7, these error types may be thrown as Error objects, which implement Throwable (but not Exception).

On HHVM, these invoke the set_error_handler callback, similar to how (non-fatal) warnings and notices are reported, except that after this handler runs for fatal error tpyes, script execution stops!

The user will be shown an HTTP 500 Internal Server Error. As such, these should be sent to MediaWiki's "fatal" or "exception" channel. Normally, the error handler logs them to the "error" channel.

Definition at line 55 of file MWExceptionHandler.php.

◆ $handledFatalCallback

bool MWExceptionHandler::$handledFatalCallback = false
staticprotected

Definition at line 71 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: