Rename shutdown handler constant to allow it to be used for disabling it altogether

[schlessera]

As we cannot unregister the shutdown handler we register for the WSOD protection, we're currently defining a constant WP_EXECUTION_SUCCEEDED to short-circuit its execution once WordPress has fully loaded.

This constant can actually be used to disable the shutdown handler altogether. Therefore, I suggest renaming it to WP_DISABLE_SHUTDOWN_HANDLER so that its usage is more obvious.

[schlessera]

Regarding the naming, as we have multiple shutdown handler, this might still be misleading. A more precise name would be WP_DISABLE_PREMATURE_SHUTDOWN_HANDLER or WP_DISABLE_WSOD_PROTECTION...

[flixos90]

Regardless of the name we choose, I suggest to add the WP_DISABLE_* constant as an entirely new constant, in addition to WP_EXECUTION_SUCCEEDED. While they are closely related, semantically they are not the same:

• One flags that WordPress has successfully loaded so that the shutdown handler should not run.
• One disables the shutdown handler entirely.

The new WP_DISABLE_* would be purely for definition in wp-config.php, and I suggest to put the check for it into the wp_register_premature_shutdown_handler() function: If it is defined and true, don't even register any shutdown handler. This separates the two concerns and also allows mitigating the problem in #46038 easily, for example in a development setup.

[flixos90]

46047.2.diff​ renames the WP_Shutdown_Handler class to WP_Fatal_Error_Handler and adjusts the drop-in name to fatal-error-handler.php. It furthermore introduces a constant WP_DISABLE_FATAL_ERROR_HANDLER to disable the handler entirely, and a filter wp_fatal_error_handler_enabled to dynamically tweak that value.

These changes were discussed and agreed on in Slack today: ​https://wordpress.slack.com/archives/C60K3MP2Q/p1548090570493300

[flixos90]

46047.3.diff​ maintains the history correctly by using svn mv, props @ocean90 :)

[flixos90]

In 44674:

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.

[jtsternberg]

While testing this, trying to add my own fatal error handler (fatal-error-handler.php), the defined( 'WP_CONTENT_DIR' ) check is always false (unless, of course, I define it directly in my wp-config.php file). Does that sound correct? If so, when documenting this option, should also document that defining it in your wp-config.php is important (at which point, why not allow defining the path to the custom fatal error handler directly??).

[TimothyBlynJacobs]

I think this is because wp_initial_constants() is not called until after wp_register_fatal_error_handler(). The only meaningful changes between those two calls is the loading of the version file. It seems like it'd be fine to move the fatal error handler registration after that function call.

[jtsternberg]

Yep, that seems like it would do the trick, and is better as then the various globals and constants will be available to the custom error handler (e.g. handle errors differently for versions of WP > X, for instance).

[flixos90]

In 44717:

Bootstrap/Load: Revert fatal error recovery mechanism from 5.1 to polish for 5.2.

Due to the high number of follow-up tickets and associated security concerns, it was decided to reschedule the fatal error recovery feature for WordPress 5.2, in order to address these issues properly. The feature will continue to be developed, with iterations being merged into trunk early in the 5.2 release cycle.

Fixes #46141. See #44458, #45932, #45940, #46038, #46047, #46068.

[flixos90]

This ticket is based on the old fatal error recovery mode implementation and will be covered as part of #46130.