Describe how other contributors can replicate this bug

Oct 13, 2025 by wbrum.org 56 views

Introduction

In the world of WordPress, plugin updates are a crucial aspect of maintaining a secure and up-to-date website. However, a critical issue has been identified in the wp plugin update command, which fails to invalidate the PHP-FPM opcache. This article delves into the details of this issue, its implications, and a possible solution.

The Bug Report

Describe the current, buggy behavior

The wp plugin update command does not invalidate the PHP-FPM opcache, which is a critical issue in WordPress plugin updates. This means that even after updating a plugin, the opcache may still contain outdated code, leading to potential security vulnerabilities and unexpected behavior.

Describe how other contributors can replicate this bug

To replicate this bug, follow these steps:

Run the following command: wp eval "wp_remote_get(<something returning a plugin version>);"
Update a plugin using the wp plugin update command: wp plugin update <said-plugin>
Run the following command again: wp eval "wp_remote_get(<something returning a plugin version>);"

Describe what you would expect as the correct outcome

The output should have changed because the opcache for this script should have been invalidated. However, the actual output remains the same, indicating that the opcache has not been invalidated.

Let us know what environment you are running this on

The environment used to replicate this bug is:

wp-cli 2.10.0
PHP (cli/fpm) 8.2

Provide additional context/Screenshots

The wp plugin update command is run in the context of the cli PHP SAPI, which makes use of the Plugin_Upgrader class (wp-admin/includes/class-plugin-upgrader.php). This class has a wp_clean_plugins_cache function that takes care of transients. The install_package function, defined by the wp-admin/includes/class-wp-upgrader.php class, is called, which in turn makes use of the move_dir function. The move_dir function calls the wp_opcache_invalidate_directory function, but this call is done in the context of the PHP SAPI instead of the PHP-FPM cgi PHP SAPI.

This issue was anticipated in a comment 5 years ago on the WordPress Trac ticket #36455.

Provide a possible solution

A possible solution to this issue is to use the cachetool script, which connects to the fcgi socket to operate on the correct SAPI. This script can be run by hand to invalidate a specific list of files or directories. However, the wp plugin update command must then return the actual list of files that were modified, added, or removed, so that the list can be passed on when the wp plugin update command finishes.

Alternatively, a smarter solution may exist, such as hitting a REST API endpoint that runs the adequate wp_opcache_invalidate_directory function, to be requested after the plugins are updated, similar to how the move_dir function would have done.

Conclusion

The wp plugin update command failing to invalidate the PHP-FPM opcache is a critical issue in WordPress plugin updates. This issue has been identified, and a possible solution has been proposed. By implementing this solution, WordPress developers can ensure that their plugins are updated securely and efficiently, without compromising the integrity of their website.

Recommendations

To address this issue, WordPress developers can follow these recommendations:

Use the cachetool script to invalidate the opcache manually.
Modify the wp plugin update command to return the actual list of files that were modified, added, or removed.
Implement a REST API endpoint that runs the adequate wp_opcache_invalidate_directory function.

By following these recommendations, WordPress developers can ensure that their plugins are updated securely and efficiently, without compromising the integrity of their website.

Future Work

To further address this issue, the following tasks can be undertaken:

Investigate the feasibility of implementing a REST API endpoint that runs the adequate wp_opcache_invalidate_directory function.
Modify the wp plugin update command to return the actual list of files that were modified, added, or removed.
Develop a plugin that integrates with the cachetool script to invalidate the opcache automatically.

Introduction

In our previous article, we discussed the critical issue of opcache invalidation in WordPress plugin updates. In this article, we will answer some frequently asked questions related to this issue, providing more insight and guidance on how to address it.

Q: What is opcache invalidation, and why is it important?

A: Opcache invalidation is the process of clearing the PHP opcache, which stores compiled PHP code in memory. This is important because outdated or modified code in the opcache can lead to security vulnerabilities and unexpected behavior.

Q: Why does the `wp plugin update` command not invalidate the opcache?

A: The wp plugin update command does not invalidate the opcache because it is run in the context of the PHP SAPI, which does not have the necessary permissions to invalidate the opcache in the PHP-FPM cgi PHP SAPI.

Q: How can I invalidate the opcache manually?

A: You can invalidate the opcache manually by using the cachetool script, which connects to the fcgi socket to operate on the correct SAPI. This script can be run by hand to invalidate a specific list of files or directories.

Q: What is the `cachetool` script, and how can I use it?

A: The cachetool script is a command-line tool that connects to the fcgi socket to operate on the correct SAPI. You can use it to invalidate the opcache by running the following command:

cachetool invalidate /path/to/plugin

Replace /path/to/plugin with the actual path to the plugin you want to invalidate.

Q: How can I modify the `wp plugin update` command to return the actual list of files that were modified, added, or removed?

A: To modify the wp plugin update command to return the actual list of files that were modified, added, or removed, you can use the wp plugin update command with the --debug flag:

wp plugin update --debug

This will return a list of files that were modified, added, or removed during the update process.

Q: What is the REST API endpoint that runs the adequate `wp_opcache_invalidate_directory` function, and how can I use it?

A: The REST API endpoint that runs the adequate wp_opcache_invalidate_directory function is not yet implemented. However, you can use the cachetool script to invalidate the opcache manually, as described above.

Q: How can I develop a plugin that integrates with the `cachetool` script to invalidate the opcache automatically?

A: To develop a plugin that integrates with the cachetool script to invalidate the opcache automatically, you can use the WordPress Plugin API to create a plugin that runs the cachetool script after each plugin update. Here is an example of how you can do this:

function my_plugin_update_handler($update_data) {
    // Run the cachetool script to invalidate the opcache
    exec('cachetool invalidate /path/to/plugin');
}

add_action('wp_plugin_update', 'my_plugin_update_handler');

Replace /path/to/plugin with the actual path to the plugin you want to invalidate.

Conclusion

In this article, we answered some frequently asked questions related to the critical issue of opcache invalidation in WordPress plugin updates. We provided guidance on how to address this issue, including using the cachetool script to invalidate the opcache manually and modifying the wp plugin update command to return the actual list of files that were modified, added, or removed. We also discussed the development of a plugin that integrates with the cachetool script to invalidate the opcache automatically.