PHP Site Health Mechanisms in 5.1

Update (2019-03-04): The fatal error protection mechanism explained here has been pulled out of the 5.1 release as it had several flaws critical enough to postpone the feature. A new path to address the issues is underway via #46130 and is intended to be released as part of WordPress 5.2.

Update (2019-01-21): A few critical naming changes have been made regarding the fatal error protection since the post was originally published. Most importantly, the drop-in to override the new shutdown handler is now called fatal-error-handler.php, and the class to override is called WP_Fatal_Error_Handler. Furthermore, a new WP_DISABLE_FATAL_ERROR_HANDLER constant allows entirely disabling the feature via wp-config.php. The rest of the post is also updated to use these new terms, however you might need to update your code if you built anything based on the previous information. For a history of what exactly has changed since the original post date, please refer to the umbrella ticket #44458.


WordPress 5.1 will start showing notices to administrators of sites that run on long outdated PHP versions. This part of the Servehappy and more globally Site Health projects paves the way to a more secure and performant web and, more specifically to WordPress, to a bump of the minimum required PHP version.

The current threshold for which PHP versions to display the notice will be anything below 5.6. While the lowest PHP version still receiving security updates is currently 7.1, the idea is to not go all the way there at the beginning to limit the support load. PHP 5.6 is the intended version to bump WordPress requirements to, and from then the threshold for the PHP notice will increase granularly, with the goal to over time catch up with the actual PHP version progress. The threshold is managed via a new Servehappy API endpoint on wordpress.org, so the version numbers can be modified independently of a WordPress release.

Warning about outdated PHP version in WordPress backend

The link from the button points to a new support page about updating PHP which briefly explains the problem and then dives into how to prepare for an update and perform it. The link URL in WordPress is a translatable string so that locales can provide their own versions of the page. In order for that process to be straightforward, the content is managed through a page template, with the translation strings thus being available in GlotPress (see https://meta.trac.wordpress.org/ticket/4004). Furthermore, the link can be adjusted via either an environment variable WP_UPDATE_PHP_URL intended for hosting providers or a filter wp_update_php_url for a more dynamic approach on the code level. Replacing the URL should happen in cases where a more specific guide to update PHP on the given environment exists. The hosting provider is the preferred source to set this, so plugins are recommended to honor this priority and not unconditionally override it. Furthermore, if the URL is changed in any way, the URL to the original WordPress resource is still maintained as an additional link, which you can see in the following screenshot:

Warning about outdated PHP version with custom URL and related annotation

For further background information on these changes, please refer to the respective tickets #41191 and #45686.

Fatal Error Protection

To help the process of recovering errors that result from updating the PHP version, a mechanism has been implemented to detect fatal errors and, in certain designated areas of WordPress, recover from them. While updating PHP is mostly fairly straightforward and popular plugins and themes are typically maintained well, not necessarily all extensions are compatible with the latest PHP versions yet. So unfortunately there might be cases where a plugin or theme causes the WordPress site to no longer be accessible after the PHP update by causing a fatal error.

With the so-called WSOD protection (white-screen-of-death protection), WordPress will recognize when a fatal error occurs and which plugin or theme is causing it. When accessing the admin backend, the respective extension will be paused, allowing users to still log in to their site so that they can (at least temporarily) fix the problem. Once the extension is known to be fixed, it can be resumed from the backend. While this does not necessarily make updating PHP easier, it lowers the burden of possibly running into the case where you are completely locked out of your site when you do not have access to the codebase.

Extensions are only paused in the admin backend and a few other areas while for example the frontend stays unaffected, and thus broken. Since it is impossible to predict which functionality the broken extension is responsible for, it would be dangerous to have it disabled in the frontend. It is more clear to a user accessing the site to see a message that it is currently not accessible rather than, without notice, no longer having access to a certain part of the key functionality. In the frontend, a message that the site is currently inaccessible will be displayed via a regular wp_die() call, with a link to the admin backend. Sites that would like to modify this output can use a new php-error.php drop-in that should send the necessary HTTP header as well as the output.

Default output in the frontend when WSOD protection detects has detected an error

Note that, while the primary reason for implementing the fatal error protection mechanism was making the process of updating PHP less “dangerous”, it is technically not tied to the update at all. In fact, it will be enabled permanently and discover fatal errors under any circumstances.

For sites that prefer to alter this behavior or sites that would like to omit the WSOD protection altogether, it is possible to add a new drop-in file fatal-error-handler.php. That file should declare a custom shutdown handler class for treating fatal errors that extends the default WP_Fatal_Error_Handler, and then return the instance of it to use. The default class’s functionality is split into distinct methods so that it is easy to reuse and override as granularly as necessary in a child class. The functionality can also be disabled entirely if that is preferred, via a new constant WP_DISABLE_FATAL_ERROR_HANDLER or, more dynamically, a corresponding wp_fatal_error_handler_enabled filter.

For further background information on these changes, please refer to #44458.

Honoring Plugin PHP Version Requirements

When browsing plugins to install, WordPress 5.1 will display a warning for those plugins that require a higher PHP version than the one currently active. While that screen previously already included such information about WordPress version compatibility, it now does the same for PHP. Furthermore, for both of these potential issues, WordPress will now enforce these requirements, disabling the button to install such plugins.

This is only a first step in enforcing version requirements of plugins and themes. In a future WordPress version, these restrictions will expand also to updating or activating plugins and eventually cover themes as well.

For further background information on these changes, please refer to #43986.

#5-1, #dev-notes, #servehappy