Plugin update procedure (WordPress)
How does the WordPress plugin update procedure work? I'm glad you asked:
Context
Update & installation packages are identical
- A plugin's installation package is the same as an update package
- During an update, basically all files get replaced. See Transients Layered Nav Counts problem (WooCommerce)#Remove transient creation as an illustration: Everytime WooCommerce gets updated, the
Filterer.php
file needs to get patched again - The only difference between a fresh installation and an update, is that different procedures are followed.
Logging
- WordPress includes a built-in logging mechanism for troubleshooting and debugging purposes, known as WP Debug. While it's not specifically targeted at the plugin update process, it can log errors that occur during updates
- To enable logging, you need to modify the wp-config.php file:
define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true );
- This creates a log file in the wp-content/ directory called debug.log, which records PHP errors and warnings, including those that may occur during a plugin update
- If there’s an issue with downloading, extracting, or replacing files during the update, it might be logged here.
Update triggers
There are different ways to trigger an update. They may use the WordPress Updates API and some methods probably get started through cron. How WP-CLI approximately does this, e.g., in response to wp plugin update plugin-slug
:
- WP-CLI retrieves the installed version of
plugin-slug
by reading the plugin metadata - WP-CLI checks the
update_plugins
option in the WordPress database to see if a newer version is available for that plugin - If the database indicates that a new version is available, WP-CLI initiates the update procedure
- If the installed version matches the latest version, WP-CLI reports that the plugin is up to date and skips the update.
Procedure
What happens when a plugin is updated by WordPress:
Pre-update actions (& license check)
- License check: This might be a moment for a license check, e.g., through
pre_set_site_transient_update_plugins
hook - File permission check: WordPress checks the file permissions to ensure it has the rights to modify plugin files
Enabling maintenance mode
The site enters maintenance mode: WordPress creates a file .maintenance in the root directory of the site. This triggers the display of the "Maintenance mode" message to visitors, which looks something like Briefly unavailable for scheduled maintenance. Check back in a minute.
(License check)
- This is probably the second likely moment for plugins to do a license check: After maintenance mode and before actually downloading the plugin
- I don't know if this would be before or after plugin deactivation, as I wouldn't know how to check that. Doing it before seems to make a bit more sense to me
- See the screenshot around here concerning
woocommerce-eu-vat-number
, that seems to do its check here.
Plugin deactivation
WordPress deactivates the plugin being updated temporarily to avoid any issues during the update process.
Package download (& license check)
- WordPress downloads the latest version of the plugin, typically as a zip file
- This would be another typical moment for a license check. I believe that this is the case for some of the plugins that we use, as the download URL is displayed, followed by a license error
Source location
The package source location is defined in the plugin's meta data. Two main options:
- from the WordPress Plugin Repository
- from a third-party source where the plugin is hosted.
Download location
- PHP follows constant
open_basedir
to determine whether it can write to locations outside the Apache www-directory - WordPress used PHP's
sys_get_temp_dir()
function to determine the system's temporary directory /tmp
might be used as temporary download period (seems unlikely to me)- More likely:
wp-content/upgrade/<plugin-name>
- This location is also used as fallback location, if another location (e.g.,/tmp
) has been tried first and found to not work.
File extraction (& license check)
- The downloaded update package (usually a ZIP file) is extracted
- This might be another moment to check for a license, although not a very likely moment
- Extracted files are likely saved at
wp-content/plugins/<plugin-name>.tmp/
File replacement
- Some plugins create a temporary backup first
- Plugin files are deleted. Plugins can specify specific files and subdirectories as exceptions
- Replacement files are copied to the plugin folder. If somehow, older files were still there, they get overwritten
- Permission check and update.
Details
- Database settings are untouched
- Files outside the regular plugin directory, are untouched
- When an error occurs (e.g., insufficient file permissions, insufficient storage space, network timeouts), WordPress will halt the process and returns an error. The plugin may remain in a deactivated or partially updated state
- Some plugins have a rollback procedure that may restore the plugin to the state prior to the update attempt. This is not a native WordPress feature and depends on the plugin.
What doesn't happen
Some sources claim that a plugin directory (e.g., wp-content/plugin/dolly
) is renamed and kept as a backup and that a new plugin's directory is created for the update. This is probably not true.
Database update (if required)
Some plugins require changes to the database schema or data. After the files are replaced, the plugin might trigger a database update process if needed, which usually runs a script to modify or create new database tables or fields.
Plugin reactivation
Once the update is complete, WordPress automatically reactivates the plugin. If any issues are encountered during reactivation (such as conflicts or fatal errors), WordPress will leave the plugin deactivated and may show an error message.
Cache clearing (if required)
Some plugins (especially caching or performance plugins) will clear their caches to ensure no stale data is served after the update.
Maintenance mode deactivation
WordPress deletes the .maintenance
file, ending maintenance mode and making the site accessible to visitors again.
Completion notification
After the update is complete, WordPress will notify the user that the plugin has been successfully updated. If any errors occurred, these will also be displayed.
See also
- Custom plugin update (WordPress)
- Transients Layered Nav Counts problem (WooCommerce)#Remove transient creation
- wp plugin install
- wp plugin update
Resources
- https://www.wpbeginner.com/beginners-guide/how-to-manually-update-wordpress-plugins-via-ftp
- https://kinsta.com/knowledgebase/manually-update-wordpress-plugin
- https://makeitwork.press/scripts/wp-updater/
- https://wordpress.stackexchange.com/questions/13/updates-for-a-private-plugin
- https://wordpress.stackexchange.com/questions/131334/how-exactly-do-automatic-updates-work
- https://kinsta.com/blog/wordpress-automatic-updates/ - Nope: it doesn't say how the actual update process works
- https://help.getshieldsecurity.com/article/235-how-does-the-wordpress-automatic-updates-system-actually-work - Gets a bit closer, but still doesn't discuss the actual update process
- https://wordpress.stackexchange.com/questions/276346/wordpress-plugin-update-process
- https://developer.wordpress.org/plugins/plugin-basics/uninstall-methods/
- https://developer.wordpress.org/plugins/plugin-basics/activation-deactivation-hooks/