New in 6.3: Rollback for failed manual plugin and theme updates

Should the manual pluginPlugin 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 Plugin Directory or can be cost-based plugin from a third-party or theme update process fail, the rollback feature will automatically restore the previously installed version to ensure the website remains available to its users.

The Rollback feature originated in #51857.

When updating a plugin or theme, the old version of the plugin or theme is moved to a wp-content/upgrade-temp-backup/plugins/PLUGINNAME or wp-content/upgrade-temp-backup/themes/THEMENAME folder.

The reason we chose to move instead of zip, is because zipping/unzipping are resources-intensive processes, and could increase the risk of failure on low-end, shared hosts. Moving files, on the other hand, is performed instantly and won’t be a bottleneck.

Moving is accomplished by means of the new move_dir() function, included in WordPress 6.2. PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher’s rename() is used for this with a fallback to copy_dir(), a recursive file copy used by CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. for a long time. move_dir()uses the ::move()method for the WP_Filesystem_DirectWP_Filesystem_FTPextWP_Filesystem_ftpsockets, and WP_Filesystem_SSH2 filesystem abstractions and has a fallback to copy_dir(). Find out more in the move_dir() devnote.

If the update process fails, then the backup we moved in the “upgrade-temp-backup” folder is restored to its original location. If the update succeeds, then the backup is deleted.

Two new checks were added in the Site Health screen:

  • Check to make sure that the backup folders are writable.
  • Check there is enough disk-space available to safely perform updates.

To avoid confusion: The “upgrade-temp-backup” folder will NOT be used to “roll back” a plugin/them to a previous version after a successful update. You can use the various rollback plugins for this.

The “upgrade-temp-backup” folder will simply contain a transient backup of the previously installed plugin or theme getting updated, and as soon as the update process finishes, the folder will be emptied.

When a rollback occurs, the user should simply see that there is an update pending and their site should still be working.

The simplest explanation of what results in a manual update failure and a rollback is anything that returns a WP_Error from WP_Upgrader::install_package().

  1. A bad request, something missing the source or destination of the update.
  2. WP_Error returned from the upgrader_pre_installupgrader_source_selectionupgrader_clear_destinationupgrader_post_install filters.
  3. An empty download package.
  4. A failure when moving the moving the installed plugin/theme to the temp-backup directory.
  5. If the remote source destination folder not able to be cleared and something is there.
  6. Unable to create remote destination folder.
  7. Unable to move/copy the the update to the remote destination.

Updated August 2, 2023 @afragen

The above encompasses parts 1 and 2 of the Rollback feature. Part 3, hopefully for WordPress 6.4, is the same process but for automatic updates. Specifically, Rollback part 3 checks to see that the updated plugin does not cause a PHP fatal error when activated. If it does, this error is captured and the previously installed version is restored.

All of the Rollback feature, parts 1-3, are included for testing in the Rollback Update Failure feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins..

Props @costdev for peer review, @stevenlinx and @desrosj for review.

#6-3, #dev-notes, #dev-notes6-3, #props