Background
The biggest risk for a site owner when updating plugins is encountering a PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher fatal error that crashes their website. While Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. updates are protected by automatic rollbacks since WordPress 3.7 (#22704), no such protection for plugins was added. Although fatal error protection and recovery mode were added in WordPress 5.2, it requires manual intervention from an administrator, and ideally WordPress should be able to recover on its own in a similar way that Core does. The Upgrade/Install team began exploring rollbacks for plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party updates.
Rollbacks for plugin updates comprises three features:
- move_dir() – Introduced in WordPress 6.2 (#57375)
- Rollback for plugin/theme update failures when updating manually – Introduced in WordPress 6.3 (#51857)
- Rollback for plugin auto-updates when failures are encountered – Covered by this proposal (#58281)
Some background references
Overview
When active plugins are updated, they are briefly deactivated before the new version is installed and reactivated immediately after. Since WordPress 6.3, when an administrator is manually updating plugins, the plugin will not be reactivated if the update causes a PHP fatal error. During an auto-update, this reactivation check does not occur and the next time the site runs users will see the white screen of death (WSOD).
To further protect websites and increase confidence in automatic plugin updates within WordPress, the Rollback Auto-Update feature plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. aims to detect PHP fatal errors during automatic plugin updates, and subsequently rolls back to the previously installed version.
This proposal is to merge the changes required to also perform rollbacks when fatal errors occur during attempted plugin auto-updates by default.
Implementation
Rollback Auto-Update performs a loopback request to the homepage to check for PHP fatal errors, using an approach similar to the Plugin or Theme File Editors. If a PHP fatal error is encountered, an error handler logs the specific message and the previously installed version of the plugin is restored. When a plugin rollback occurs, a notification will be sent to the site’s administration email (stored in the admin_email
option) notifying them of the failed update and rollback.
The current implementation attempts to detect a PHP fatal error during an automatic update by using a loopback request to the homepage. If the loopback returns an error, a PHP fatal error in the active plugin is assumed and the update will be reverted for safety.
After the problematic plugin is rolled back, the auto-updating process will continue for any other core, plugin, or theme updates that were in queue. When the next check for auto-updates occurs, WordPress will attempt to update the same plugin again.
Previously, maintenance mode was only enabled during installation of an update. However, testing established that disabling maintenance mode during the rest of the process means that active visits to the site can trigger errors. This can have side effects, such as deactivating plugins, etc. Rollback Auto-Update enables maintenance mode for the duration of all automatic updates. While maintenance mode is enabled for longer, this is relative to the number of updates being performed at that given time – usually a very low number – and helps improve stability of automatic updates.
At the time of publishing, this code is being tested on 6,000+ sites running the Rollback Update Failure feature plugin, which has contained the related code since v7.0.0 was released on 10/12/2023.
For easier testing of the feature within wordpress-develop
, a merge PR (Core-5287) has been created.
Due to limitations in the ability to modify wp_is_maintenance_mode()
in the feature plugin, the PR is slightly different. The feature plugin is available for historical reference. All pre-merge testing should be done using the PR. Some contributors have also been running the PR on sites for a few months.
Example of email text sent to site’s administration email.
Howdy! Plugins failed to update on your site at https://test.xxxxx.net.
Please check your site now. It’s possible that everything is working. If there are updates available, you should update.
The following plugins failed to update. If there was a fatal error in the update, the previously installed version has been restored.
- This Plugin Should Not Be Used (from version 0.1 to 0.2) : https://wordpress.org/plugins/this-plugin-should-not-be-used/
To manage plugins on your site, visit the Plugins page: https://test.xxxxx.net/wp-admin/plugins.php
If you experience any issues or need support, the volunteers in the WordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ support forums may be able to help.
https://wordpress.org/support/forums/
The WordPress Team
Testing
There are no known issues directly related to Rollback Auto-Update that don’t currently exist in Core.
I (@afragen) have been testing using the test plugin. The plugin is on a test site, active, and set to auto-update. I have been running like this since the beginning of the year using the PR and on other sites for several years using the feature plugin.
- Install the PR into WP 6.5.x or trunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision..
- Install version 0.1 of the test plugin.
- Activate the test plugin and enable auto-updates.
The WordPress.org update API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. will serve the version 0.2 version of the plugin, which will cause a PHP fatal error. To confirm a rollback is successful, data is written to the error.log
at every point in the auto-update process, creating an audit trail the user can use to discern the flow and results of rolling back an auto-update. This logging is only intended for testing purposes.
FAQ
Stay up to date with development on the PR. Please comment on the GitHub PR if any problems are discovered.
- What happens if loopback requests aren’t working?
- As demonstrated by the Site Health message for loopback requests that aren’t working: “Loopback requests are used to run scheduled events, and are also used by the built-in editors for themes and plugins to verify code stability.”
- Auto-updates shouldn’t run if loopback requests aren’t working. If a loopback request fails due to an HTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. error, Rollback Auto-Update will consider it as a PHP fatal error detected, and revert any plugin updates.
As a project, it’s important to continuously evaluate ways to make site management easier for the large majority of users and site owners. Providing safer plugin auto-updates is just one way for WordPress itself to handle problems that may require technical expertise seamlessly for end users.
All feedback will be collected and addressed over the next 2-3 weeks, with the goal of committing to trunk
after all feedback is addressed to ensure that the feature gets plenty of testing through the nightly builds early in the WordPress 6.6 release cycle.
Props: @costdev and @desrosj for review and editing.
#6-6, #feature-projects, #feature-autoupdates, #merge-proposals, #rollback