Add --show-changed-files flag for opcache invalidation

[Copilot]

WP-CLI runs in CLI SAPI context, so WordPress core's wp_opcache_invalidate_directory() calls during plugin/theme updates don't affect PHP-FPM opcache. Users need the list of changed files to invalidate opcache using external tools like cachetool.

Changes

• ExtensionUpgraderSkin: Hooks into upgrader_post_install filter to capture destination directory and recursively collect all PHP files. Includes duplicate hook prevention and filesystem error handling.

• CommandWithUpgrade: Detects --show-changed-files flag, enables file tracking on skin, outputs deduplicated sorted file list after updates complete.

• Documentation: Added flag to wp plugin update and wp theme update with usage examples.

• Tests: Added Behat scenarios for both plugin and theme updates.

Usage

# Output changed files for manual processing
wp plugin update akismet --show-changed-files

# Pipe to cachetool for PHP-FPM opcache invalidation
wp plugin update akismet --show-changed-files | grep "^/" | \
  xargs -I {} cachetool opcache:invalidate:scripts {}

The implementation uses upgrader_post_install (available since WordPress 2.8.0) rather than relying on wp_opcache_invalidate_file filter, ensuring consistent behavior across WordPress versions.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>opcache invalidation</issue_title>
<issue_description>## Bug Report

• Yes, I reviewed the contribution guidelines.
• Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.

Describe the current, buggy behavior

wp plugin update doesn't invalidate PHP-FPM opcache

Describe how other contributors can replicate this bug

• wp eval "wp_remote_get(<something returning a plugin version>);"
• wp plugin update <said-plugin>
• wp eval "wp_remote_get(<something returning a plugin version>);"

Describe what you would expect as the correct outcome

Output should have changed because the opcache for this script should have been invalidated.
Actual: It's the same output

Let us know what environment you are running this on

wp-cli 2.10.0 on PHP (cli/fpm) 8.2

Provide additional context/Screenshots

• wp plugin update is run in the context of the cli PHP SAPI
• It makes use of Plugin_Upgrader (wp-admin/includes/class-plugin-upgrader.php)
• This one has a wp_clean_plugins_cache taking care of transients.
• and call install_package defined by wp-admin/includes/class-wp-upgrader.php
• which makes use of move_dir which...
• calls wp_opcache_invalidate_directory

The problem is that this call is done in the context of the PHP SAPI instead of the PHP-FPM cgi PHP SAPI.

This issue was anticipated in this comment 5 years ago https://core.trac.wordpress.org/ticket/36455#comment:104

Provide a possible solution

https://github.com/gordalina/cachetool/ connects to the fcgi socket to operate on the correct SAPI. I could run the script by hand to invalidate a specific list of files/dir. But wp plugin update must then return the actual list of files which were modified/added/removed (a helper could exist for that purpose), so that the list could be passed on when wp plugin update finishes.

(But something smarter may exist, like hitting a REST API endpoint which runs the adequate wp_opcache_invalidate_directory(), to be requested after the plugins are updated like move_dir would have done?)</issue_description>

Comments on the Issue (you are @copilot in this section)

@swissspidy > But wp plugin update must then return the actual list of files which were modified/added/removed (a helper could exist for that purpose), so that the list could be passed on when wp plugin update finishes.

Just noting that this is probably relevant for other types of updates too.

(But something smarter may exist, like hitting a REST API endpoint which runs the adequate wp_opcache_invalidate_directory(), to be requested after the plugins are updated like move_dir would have done?)

In the past I‘ve recommended https://github.com/wearerequired/wp-cli-clear-opcache for this. It‘s not something WP-CLI can provide out of the box since it requires a change on the WordPress side.</comment_new>
<comment_new>@swissspidy

Isn't that something wp-cli could do (to avoid doing a full reset of the opcache when only one plugin was updated). Something like wp plugin update --show-changed-files ?

Possibly. The wp_opcache_invalidate_file filter could potentially be (mis-)used for that. If you're up for writing a quick proof of concept PR then this could be discussed further to see if it's a valuable addition to WP-CLI.</comment_new>

• Fixes opcache invalidation #444

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.