3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
21 use MediaWiki\Logger\LoggerFactory
;
24 * Handler class for MWExceptions
27 class MWExceptionHandler
{
30 * @var string $reservedMemory
32 protected static $reservedMemory;
34 * @var array $fatalErrorTypes
36 protected static $fatalErrorTypes = array(
37 E_ERROR
, E_PARSE
, E_CORE_ERROR
, E_COMPILE_ERROR
, E_USER_ERROR
,
38 /* HHVM's FATAL_ERROR level */ 16777217,
41 * @var bool $handledFatalCallback
43 protected static $handledFatalCallback = false;
46 * Install handlers with PHP.
48 public static function installHandler() {
49 set_exception_handler( 'MWExceptionHandler::handleException' );
50 set_error_handler( 'MWExceptionHandler::handleError' );
52 // Reserve 16k of memory so we can report OOM fatals
53 self
::$reservedMemory = str_repeat( ' ', 16384 );
54 register_shutdown_function( 'MWExceptionHandler::handleFatalError' );
58 * Report an exception to the user
61 protected static function report( Exception
$e ) {
62 global $wgShowExceptionDetails;
64 $cmdLine = MWException
::isCommandLine();
66 if ( $e instanceof MWException
) {
68 // Try and show the exception prettily, with the normal skin infrastructure
70 } catch ( Exception
$e2 ) {
71 // Exception occurred from within exception handler
72 // Show a simpler message for the original exception,
73 // don't try to invoke report()
74 $message = "MediaWiki internal error.\n\n";
76 if ( $wgShowExceptionDetails ) {
77 $message .= 'Original exception: ' . self
::getLogMessage( $e ) .
78 "\nBacktrace:\n" . self
::getRedactedTraceAsString( $e ) .
79 "\n\nException caught inside exception handler: " . self
::getLogMessage( $e2 ) .
80 "\nBacktrace:\n" . self
::getRedactedTraceAsString( $e2 );
82 $message .= "Exception caught inside exception handler.\n\n" .
83 "Set \$wgShowExceptionDetails = true; at the bottom of LocalSettings.php " .
84 "to show detailed debugging information.";
90 self
::printError( $message );
92 echo nl2br( htmlspecialchars( $message ) ) . "\n";
96 $message = "Exception encountered, of type \"" . get_class( $e ) . "\"";
98 if ( $wgShowExceptionDetails ) {
99 $message .= "\n" . self
::getLogMessage( $e ) . "\nBacktrace:\n" .
100 self
::getRedactedTraceAsString( $e ) . "\n";
104 self
::printError( $message );
106 echo nl2br( htmlspecialchars( $message ) ) . "\n";
113 * Print a message, if possible to STDERR.
114 * Use this in command line mode only (see isCommandLine)
116 * @param string $message Failure text
118 public static function printError( $message ) {
119 # NOTE: STDERR may not be available, especially if php-cgi is used from the
120 # command line (bug #15602). Try to produce meaningful output anyway. Using
121 # echo may corrupt output to STDOUT though.
122 if ( defined( 'STDERR' ) ) {
123 fwrite( STDERR
, $message );
130 * If there are any open database transactions, roll them back and log
131 * the stack trace of the exception that should have been caught so the
132 * transaction could be aborted properly.
135 * @param Exception $e
137 public static function rollbackMasterChangesAndLog( Exception
$e ) {
138 $factory = wfGetLBFactory();
139 if ( $factory->hasMasterChanges() ) {
140 $logger = LoggerFactory
::getInstance( 'Bug56269' );
142 'Exception thrown with an uncommited database transaction: ' .
143 self
::getLogMessage( $e ),
144 self
::getLogContext( $e )
146 $factory->rollbackMasterChanges();
151 * Exception handler which simulates the appropriate catch() handling:
155 * } catch ( Exception $e ) {
157 * } catch ( Exception $e ) {
158 * echo $e->__toString();
162 * @param Exception $e
164 public static function handleException( Exception
$e ) {
166 // Rollback DBs to avoid transaction notices. This may fail
167 // to rollback some DB due to connection issues or exceptions.
168 // However, any sane DB driver will rollback implicitly anyway.
169 self
::rollbackMasterChangesAndLog( $e );
170 } catch ( DBError
$e2 ) {
171 // If the DB is unreacheable, rollback() will throw an error
172 // and the error report() method might need messages from the DB,
173 // which would result in an exception loop. PHP may escalate such
174 // errors to "Exception thrown without a stack frame" fatals, but
175 // it's better to be explicit here.
176 self
::logException( $e2 );
179 self
::logException( $e );
182 // Exit value should be nonzero for the benefit of shell jobs
187 * Handler for set_error_handler() callback notifications.
189 * Receive a callback from the interpreter for a raised error, create an
190 * ErrorException, and log the exception to the 'error' logging
191 * channel(s). If the raised error is a fatal error type (only under HHVM)
192 * delegate to handleFatalError() instead.
196 * @param int $level Error level raised
197 * @param string $message
198 * @param string $file
203 public static function handleError(
204 $level, $message, $file = null, $line = null
206 if ( in_array( $level, self
::$fatalErrorTypes ) ) {
207 return call_user_func_array(
208 'MWExceptionHandler::handleFatalError', func_get_args()
212 // Map error constant to error name (reverse-engineer PHP error
215 case E_RECOVERABLE_ERROR
:
216 $levelName = 'Error';
220 case E_COMPILE_WARNING
:
222 $levelName = 'Warning';
226 $levelName = 'Notice';
229 $levelName = 'Strict Standards';
232 case E_USER_DEPRECATED
:
233 $levelName = 'Deprecated';
236 $levelName = 'Unknown error';
240 $e = new ErrorException( "PHP $levelName: $message", 0, $level, $file, $line );
241 self
::logError( $e, 'error' );
243 // This handler is for logging only. Return false will instruct PHP
244 // to continue regular handling.
250 * Dual purpose callback used as both a set_error_handler() callback and
251 * a registered shutdown function. Receive a callback from the interpreter
252 * for a raised error or system shutdown, check for a fatal error, and log
253 * to the 'fatal' logging channel.
255 * Special handling is included for missing class errors as they may
256 * indicate that the user needs to install 3rd-party libraries via
257 * Composer or other means.
261 * @param int $level Error level raised
262 * @param string $message Error message
263 * @param string $file File that error was raised in
264 * @param int $line Line number error was raised at
265 * @param array $context Active symbol table point of error
266 * @param array $trace Backtrace at point of error (undocumented HHVM
268 * @return bool Always returns false
270 public static function handleFatalError(
271 $level = null, $message = null, $file = null, $line = null,
272 $context = null, $trace = null
274 // Free reserved memory so that we have space to process OOM
276 self
::$reservedMemory = null;
278 if ( $level === null ) {
279 // Called as a shutdown handler, get data from error_get_last()
280 if ( static::$handledFatalCallback ) {
281 // Already called once (probably as an error handler callback
282 // under HHVM) so don't log again.
286 $lastError = error_get_last();
287 if ( $lastError !== null ) {
288 $level = $lastError['type'];
289 $message = $lastError['message'];
290 $file = $lastError['file'];
291 $line = $lastError['line'];
298 if ( !in_array( $level, self
::$fatalErrorTypes ) ) {
299 // Only interested in fatal errors, others should have been
300 // handled by MWExceptionHandler::handleError
304 $msg = "[{exception_id}] PHP Fatal Error: {$message}";
306 // Look at message to see if this is a class not found failure
307 // HHVM: Class undefined: foo
308 // PHP5: Class 'foo' not found
309 if ( preg_match( "/Class (undefined: \w+|'\w+' not found)/", $msg ) ) {
310 // @codingStandardsIgnoreStart Generic.Files.LineLength.TooLong
314 MediaWiki or an installed extension requires this class but it is not embedded directly in MediaWiki's git repository and must be installed separately by the end user.
316 Please see <a href="https://www.mediawiki.org/wiki/Download_from_Git#Fetch_external_libraries">mediawiki.org</a> for help on installing the required components.
318 // @codingStandardsIgnoreEnd
321 // We can't just create an exception and log it as it is likely that
322 // the interpreter has unwound the stack already. If that is true the
323 // stacktrace we would get would be functionally empty. If however we
324 // have been called as an error handler callback *and* HHVM is in use
325 // we will have been provided with a useful stacktrace that we can
327 $trace = $trace ?
: debug_backtrace();
328 $logger = LoggerFactory
::getInstance( 'fatal' );
329 $logger->error( $msg, array(
330 'exception' => array(
331 'class' => 'ErrorException',
332 'message' => "PHP Fatal Error: {$message}",
336 'trace' => static::redactTrace( $trace ),
338 'exception_id' => wfRandomString( 8 ),
341 // Remember call so we don't double process via HHVM's fatal
342 // notifications and the shutdown hook behavior
343 static::$handledFatalCallback = true;
348 * Generate a string representation of an exception's stack trace
350 * Like Exception::getTraceAsString, but replaces argument values with
351 * argument type or class name.
353 * @param Exception $e
356 public static function getRedactedTraceAsString( Exception
$e ) {
357 return self
::prettyPrintRedactedTrace(
358 self
::getRedactedTrace( $e )
363 * Generate a string representation of a structured stack trace generated
364 * by getRedactedTrace().
366 * @param array $trace
370 public static function prettyPrintRedactedTrace( array $trace ) {
373 foreach ( $trace as $level => $frame ) {
374 if ( isset( $frame['file'] ) && isset( $frame['line'] ) ) {
375 $text .= "#{$level} {$frame['file']}({$frame['line']}): ";
377 // 'file' and 'line' are unset for calls via call_user_func (bug 55634)
378 // This matches behaviour of Exception::getTraceAsString to instead
379 // display "[internal function]".
380 $text .= "#{$level} [internal function]: ";
383 if ( isset( $frame['class'] ) ) {
384 $text .= $frame['class'] . $frame['type'] . $frame['function'];
386 $text .= $frame['function'];
389 if ( isset( $frame['args'] ) ) {
390 $text .= '(' . implode( ', ', $frame['args'] ) . ")\n";
397 $text .= "#{$level} {main}";
403 * Return a copy of an exception's backtrace as an array.
405 * Like Exception::getTrace, but replaces each element in each frame's
406 * argument array with the name of its class (if the element is an object)
407 * or its type (if the element is a PHP primitive).
410 * @param Exception $e
413 public static function getRedactedTrace( Exception
$e ) {
414 return static::redactTrace( $e->getTrace() );
418 * Redact a stacktrace generated by Exception::getTrace(),
419 * debug_backtrace() or similar means. Replaces each element in each
420 * frame's argument array with the name of its class (if the element is an
421 * object) or its type (if the element is a PHP primitive).
424 * @param array $trace Stacktrace
425 * @return array Stacktrace with arugment values converted to data types
427 public static function redactTrace( array $trace ) {
428 return array_map( function ( $frame ) {
429 if ( isset( $frame['args'] ) ) {
430 $frame['args'] = array_map( function ( $arg ) {
431 return is_object( $arg ) ?
get_class( $arg ) : gettype( $arg );
439 * Get the ID for this exception.
441 * The ID is saved so that one can match the one output to the user (when
442 * $wgShowExceptionDetails is set to false), to the entry in the debug log.
445 * @param Exception $e
448 public static function getLogId( Exception
$e ) {
449 if ( !isset( $e->_mwLogId
) ) {
450 $e->_mwLogId
= wfRandomString( 8 );
456 * If the exception occurred in the course of responding to a request,
457 * returns the requested URL. Otherwise, returns false.
460 * @return string|false
462 public static function getURL() {
464 if ( !isset( $wgRequest ) ||
$wgRequest instanceof FauxRequest
) {
467 return $wgRequest->getRequestURL();
471 * Get a message formatting the exception message and its origin.
474 * @param Exception $e
477 public static function getLogMessage( Exception
$e ) {
478 $id = self
::getLogId( $e );
479 $type = get_class( $e );
480 $file = $e->getFile();
481 $line = $e->getLine();
482 $message = $e->getMessage();
483 $url = self
::getURL() ?
: '[no req]';
485 return "[$id] $url $type from line $line of $file: $message";
489 * Get a PSR-3 log event context from an Exception.
491 * Creates a structured array containing information about the provided
492 * exception that can be used to augment a log message sent to a PSR-3
495 * @param Exception $e
498 public static function getLogContext( Exception
$e ) {
501 'exception_id' => static::getLogId( $e ),
506 * Get a structured representation of an Exception.
508 * Returns an array of structured data (class, message, code, file,
509 * backtrace) derived from the given exception. The backtrace information
510 * will be redacted as per getRedactedTraceAsArray().
512 * @param Exception $e
516 public static function getStructuredExceptionData( Exception
$e ) {
517 global $wgLogExceptionBacktrace;
519 'id' => self
::getLogId( $e ),
520 'type' => get_class( $e ),
521 'file' => $e->getFile(),
522 'line' => $e->getLine(),
523 'message' => $e->getMessage(),
524 'code' => $e->getCode(),
525 'url' => self
::getURL() ?
: null,
528 if ( $e instanceof ErrorException
&&
529 ( error_reporting() & $e->getSeverity() ) === 0
531 // Flag surpressed errors
532 $data['suppressed'] = true;
535 if ( $wgLogExceptionBacktrace ) {
536 $data['backtrace'] = self
::getRedactedTrace( $e );
539 $previous = $e->getPrevious();
540 if ( $previous !== null ) {
541 $data['previous'] = self
::getStructuredExceptionData( $previous );
548 * Serialize an Exception object to JSON.
550 * The JSON object will have keys 'id', 'file', 'line', 'message', and
551 * 'url'. These keys map to string values, with the exception of 'line',
552 * which is a number, and 'url', which may be either a string URL or or
553 * null if the exception did not occur in the context of serving a web
556 * If $wgLogExceptionBacktrace is true, it will also have a 'backtrace'
557 * key, mapped to the array return value of Exception::getTrace, but with
558 * each element in each frame's "args" array (if set) replaced with the
559 * argument's class name (if the argument is an object) or type name (if
560 * the argument is a PHP primitive).
562 * @par Sample JSON record ($wgLogExceptionBacktrace = false):
566 * "type": "MWException",
567 * "file": "/var/www/mediawiki/includes/cache/MessageCache.php",
569 * "message": "Non-string key given",
570 * "url": "/wiki/Main_Page"
574 * @par Sample JSON record ($wgLogExceptionBacktrace = true):
578 * "type": "MWException",
579 * "file": "/vagrant/mediawiki/includes/cache/MessageCache.php",
581 * "message": "Non-string key given",
582 * "url": "/wiki/Main_Page",
584 * "file": "/vagrant/mediawiki/extensions/VisualEditor/VisualEditor.hooks.php",
587 * "class": "MessageCache",
595 * @param Exception $e
596 * @param bool $pretty Add non-significant whitespace to improve readability (default: false).
597 * @param int $escaping Bitfield consisting of FormatJson::.*_OK class constants.
598 * @return string|false JSON string if successful; false upon failure
600 public static function jsonSerializeException( Exception
$e, $pretty = false, $escaping = 0 ) {
601 $data = self
::getStructuredExceptionData( $e );
602 return FormatJson
::encode( $data, $pretty, $escaping );
606 * Log an exception to the exception log (if enabled).
608 * This method must not assume the exception is an MWException,
609 * it is also used to handle PHP exceptions or exceptions from other libraries.
612 * @param Exception $e
614 public static function logException( Exception
$e ) {
615 if ( !( $e instanceof MWException
) ||
$e->isLoggable() ) {
616 $logger = LoggerFactory
::getInstance( 'exception' );
618 self
::getLogMessage( $e ),
619 self
::getLogContext( $e )
622 $json = self
::jsonSerializeException( $e, false, FormatJson
::ALL_OK
);
623 if ( $json !== false ) {
624 $logger = LoggerFactory
::getInstance( 'exception-json' );
625 $logger->error( $json, array( 'private' => true ) );
628 Hooks
::run( 'LogException', array( $e, false ) );
633 * Log an exception that wasn't thrown but made to wrap an error.
636 * @param ErrorException $e
637 * @param string $channel
639 protected static function logError( ErrorException
$e, $channel ) {
640 // The set_error_handler callback is independent from error_reporting.
641 // Filter out unwanted errors manually (e.g. when
642 // MediaWiki\suppressWarnings is active).
643 $suppressed = ( error_reporting() & $e->getSeverity() ) === 0;
644 if ( !$suppressed ) {
645 $logger = LoggerFactory
::getInstance( $channel );
647 self
::getLogMessage( $e ),
648 self
::getLogContext( $e )
652 // Include all errors in the json log (surpressed errors will be flagged)
653 $json = self
::jsonSerializeException( $e, false, FormatJson
::ALL_OK
);
654 if ( $json !== false ) {
655 $logger = LoggerFactory
::getInstance( "{$channel}-json" );
656 $logger->error( $json, array( 'private' => true ) );
659 Hooks
::run( 'LogException', array( $e, $suppressed ) );