From 2caa621b0d935f700790f3c3f6fe7630b40c2cc9 Mon Sep 17 00:00:00 2001
From: Felix Arntz <flixos90@git.wordpress.org>
Date: Mon, 21 Jan 2019 20:14:56 +0000
Subject: [PATCH] Bootstrap/Load: Change `shutdown handler` naming to final
 `fatal error handler` and allow disabling the handler entirely via a
 constant.

The `WP_Shutdown_Handler` name plus related function names were premature when originally committed, as there can be multiple shutdown handlers in PHP, and WordPress makes use of that feature. This changeset modifies the name to a more appropriate `WP_Fatal_Error_Handler`, and related to that changes the following names:

* The drop-in to override the handler is now called `fatal-error-handler.php`.
* The internal function `wp_register_premature_shutdown_handler` is now called `wp_register_fatal_error_handler()`.

In addition to these naming changes, a new constant `WP_DISABLE_FATAL_ERROR_HANDLER` is introduced that can be set in `wp-config.php` to entirely disable the fatal error handler. That constant's value is and should be accessed indirectly via a new `wp_is_fatal_error_handler_enabled()` function and is filterable via a new `wp_fatal_error_handler_enabled` hook. Note that disabling the fatal error handler will skip the new functionality entirely, including the potentially used `fatal-error-handler.php` drop-in.

The new set of constant, filter and function provide for an easier-to-use mechanism to disable the fatal error handler altogether, rather than requiring developers to implement a drop-in for purely that purpose.

Props afragen, flixos90, joyously, knutsp, markjaquith, ocean90, schlessera, spacedmonkey.
Fixes #46047. See #44458.


git-svn-id: https://develop.svn.wordpress.org/trunk@44674 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/plugin.php              | 16 ++++----
 ...r.php => class-wp-fatal-error-handler.php} | 15 +++----
 src/wp-includes/error-protection.php          | 39 ++++++++++++++++---
 src/wp-settings.php                           |  6 +--
 4 files changed, 53 insertions(+), 23 deletions(-)
 rename src/wp-includes/{class-wp-shutdown-handler.php => class-wp-fatal-error-handler.php} (89%)

diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 419ba1659c..a2a579eacb 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -468,14 +468,14 @@ function get_dropins() {
  */
 function _get_dropins() {
 	$dropins = array(
-		'advanced-cache.php'   => array( __( 'Advanced caching plugin.' ), 'WP_CACHE' ), // WP_CACHE
-		'db.php'               => array( __( 'Custom database class.' ), true ), // auto on load
-		'db-error.php'         => array( __( 'Custom database error message.' ), true ), // auto on error
-		'install.php'          => array( __( 'Custom installation script.' ), true ), // auto on installation
-		'maintenance.php'      => array( __( 'Custom maintenance message.' ), true ), // auto on maintenance
-		'object-cache.php'     => array( __( 'External object cache.' ), true ), // auto on load
-		'php-error.php'        => array( __( 'Custom PHP error message.' ), true ), // auto on error
-		'shutdown-handler.php' => array( __( 'Custom PHP shutdown handler.' ), true ), // auto on error
+		'advanced-cache.php'      => array( __( 'Advanced caching plugin.' ), 'WP_CACHE' ), // WP_CACHE
+		'db.php'                  => array( __( 'Custom database class.' ), true ), // auto on load
+		'db-error.php'            => array( __( 'Custom database error message.' ), true ), // auto on error
+		'install.php'             => array( __( 'Custom installation script.' ), true ), // auto on installation
+		'maintenance.php'         => array( __( 'Custom maintenance message.' ), true ), // auto on maintenance
+		'object-cache.php'        => array( __( 'External object cache.' ), true ), // auto on load
+		'php-error.php'           => array( __( 'Custom PHP error message.' ), true ), // auto on error
+		'fatal-error-handler.php' => array( __( 'Custom PHP fatal error handler.' ), true ), // auto on error
 	);
 
 	if ( is_multisite() ) {
diff --git a/src/wp-includes/class-wp-shutdown-handler.php b/src/wp-includes/class-wp-fatal-error-handler.php
similarity index 89%
rename from src/wp-includes/class-wp-shutdown-handler.php
rename to src/wp-includes/class-wp-fatal-error-handler.php
index 18eee6a2a4..0299b67a48 100644
--- a/src/wp-includes/class-wp-shutdown-handler.php
+++ b/src/wp-includes/class-wp-fatal-error-handler.php
@@ -1,21 +1,22 @@
 <?php
 /**
- * Error Protection API: WP_Shutdown_Handler class
+ * Error Protection API: WP_Fatal_Error_Handler class
  *
  * @package WordPress
  * @since 5.1.0
  */
 
 /**
- * Core class used as the default shutdown handler.
+ * Core class used as the default shutdown handler for fatal errors.
  *
- * A drop-in 'shutdown-handler.php' can be used to override the instance of this class and use a custom implementation
- * for the shutdown handler that WordPress registers. The custom class should extend this class and can override its
- * methods individually as necessary. The file must return the instance of the class that should be registered.
+ * A drop-in 'fatal-error-handler.php' can be used to override the instance of this class and use a custom
+ * implementation for the fatal error handler that WordPress registers. The custom class should extend this class and
+ * can override its methods individually as necessary. The file must return the instance of the class that should be
+ * registered.
  *
  * @since 5.1.0
  */
-class WP_Shutdown_Handler {
+class WP_Fatal_Error_Handler {
 
 	/**
 	 * Runs the shutdown handler.
@@ -126,7 +127,7 @@ class WP_Shutdown_Handler {
 	 * very early in the WordPress bootstrap process, so any core functions used that are not part of
 	 * `wp-includes/load.php` should be checked for before being called.
 	 *
-	 * If no such drop-in is available, this will call {@see WP_Shutdown_Handler::display_default_error_template()}.
+	 * If no such drop-in is available, this will call {@see WP_Fatal_Error_Handler::display_default_error_template()}.
 	 *
 	 * @since 5.1.0
 	 */
diff --git a/src/wp-includes/error-protection.php b/src/wp-includes/error-protection.php
index f12bd2409f..45fba0cc33 100644
--- a/src/wp-includes/error-protection.php
+++ b/src/wp-includes/error-protection.php
@@ -148,19 +148,48 @@ function wp_should_handle_error( $error ) {
 }
 
 /**
- * Registers the WordPress premature shutdown handler.
+ * Registers the shutdown handler for fatal errors.
+ *
+ * The handler will only be registered if {@see wp_is_fatal_error_handler_enabled()} returns true.
  *
  * @since 5.1.0
  */
-function wp_register_premature_shutdown_handler() {
+function wp_register_fatal_error_handler() {
+	if ( ! wp_is_fatal_error_handler_enabled() ) {
+		return;
+	}
+
 	$handler = null;
-	if ( defined( 'WP_CONTENT_DIR' ) && is_readable( WP_CONTENT_DIR . '/shutdown-handler.php' ) ) {
-		$handler = include WP_CONTENT_DIR . '/shutdown-handler.php';
+	if ( defined( 'WP_CONTENT_DIR' ) && is_readable( WP_CONTENT_DIR . '/fatal-error-handler.php' ) ) {
+		$handler = include WP_CONTENT_DIR . '/fatal-error-handler.php';
 	}
 
 	if ( ! is_object( $handler ) || ! is_callable( array( $handler, 'handle' ) ) ) {
-		$handler = new WP_Shutdown_Handler();
+		$handler = new WP_Fatal_Error_Handler();
 	}
 
 	register_shutdown_function( array( $handler, 'handle' ) );
 }
+
+/**
+ * Checks whether the fatal error handler is enabled.
+ *
+ * A constant `WP_DISABLE_FATAL_ERROR_HANDLER` can be set in `wp-config.php` to disable it, or alternatively the
+ * {@see 'wp_fatal_error_handler_enabled'} filter can be used to modify the return value.
+ *
+ * @since 5.1.0
+ *
+ * @return bool True if the fatal error handler is enabled, false otherwise.
+ */
+function wp_is_fatal_error_handler_enabled() {
+	$enabled = ! defined( 'WP_DISABLE_FATAL_ERROR_HANDLER' ) || ! WP_DISABLE_FATAL_ERROR_HANDLER;
+
+	/**
+	 * Filters whether the fatal error handler is enabled.
+	 *
+	 * @since 5.1.0
+	 *
+	 * @param bool $enabled True if the fatal error handler is enabled, false otherwise.
+	 */
+	return apply_filters( 'wp_fatal_error_handler_enabled', $enabled );
+}
diff --git a/src/wp-settings.php b/src/wp-settings.php
index 781d8e6ca1..91729821d4 100644
--- a/src/wp-settings.php
+++ b/src/wp-settings.php
@@ -18,13 +18,13 @@ define( 'WPINC', 'wp-includes' );
 // Include files required for initialization.
 require( ABSPATH . WPINC . '/load.php' );
 require( ABSPATH . WPINC . '/class-wp-paused-extensions-storage.php' );
-require( ABSPATH . WPINC . '/class-wp-shutdown-handler.php' );
+require( ABSPATH . WPINC . '/class-wp-fatal-error-handler.php' );
 require( ABSPATH . WPINC . '/error-protection.php' );
 require( ABSPATH . WPINC . '/default-constants.php' );
 require_once( ABSPATH . WPINC . '/plugin.php' );
 
-// Make sure we register the premature shutdown handler as soon as possible.
-wp_register_premature_shutdown_handler();
+// Make sure we register the shutdown handler for fatal errors as soon as possible.
+wp_register_fatal_error_handler();
 
 /*
  * These can't be directly globalized in version.php. When updating,