"I uploaded the fix. The site still shows the old code."
You deploy a one-line fix to a plugin, refresh the page, and nothing changes. You upload it again. Still nothing. Five minutes later it suddenly works. Nobody touched anything. The file was right all along: the server was running a compiled copy of the old one from OPcache.
To debug PHP in WordPress you need to know where your code actually runs, and how many stops a request makes before it reaches your plugin.
Goal
Follow one request from the browser to wp-load.php and know what each stop changes.
Key concepts
flowchart LR
B["Browser<br/>GET /shop/"] --> W["Web server<br/>nginx · Apache"]
W -- "FastCGI" --> F["PHP-FPM<br/>pool of workers · php.ini"]
F --> O["OPcache<br/>compiled opcodes in memory"]
O --> I["index.php"]
I --> L["wp-blog-header.php<br/>wp-load.php · wp-config.php"]
L --> P["Plugins · theme<br/>your code"]
- Web server (nginx or Apache) serves static files itself and hands
.phprequests to PHP. - PHP-FPM keeps a pool of PHP worker processes. Each worker handles one request at a time with the settings from its own
php.ini. - OPcache keeps compiled PHP files in shared memory, so PHP does not parse every file on every request. With
opcache.validate_timestamps=0it never checks the file on disk until the cache is reset. index.php→wp-blog-header.php→wp-load.phploadswp-config.php, then core, plugins and the theme.- PHP CLI (
php,wp) is a separate binary with its ownphp.ini. Whatphp -vshows in SSH may differ from what the site runs.
Commands / artifacts
# Which PHP the terminal uses and which php.ini it reads
php -v
php --ini
# Loaded extensions: is opcache, intl or imagick there?
php -m
# OPcache settings (CLI): validate_timestamps, revalidate_freq
php -i | grep opcache
# Which PHP the site itself runs (through WordPress)
wp eval 'echo PHP_VERSION . " " . PHP_SAPI;'
// In the browser (temporary, admins only): what FPM really uses.
add_action( 'admin_notices', function () {
if ( current_user_can( 'manage_options' ) ) {
printf( '<div class="notice"><p>PHP %s, %s, memory_limit %s</p></div>',
esc_html( PHP_VERSION ),
esc_html( PHP_SAPI ),
esc_html( ini_get( 'memory_limit' ) )
);
}
} );
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| A deployed change does not apply for minutes | OPcache serves the old compiled file (validate_timestamps=0 or a long revalidate_freq) | Reset OPcache after deploy (reload PHP-FPM or call opcache_reset() through FPM, not CLI) |
php -v says 8.4, the site behaves like 8.1 | CLI and PHP-FPM are different binaries with different versions | Check the site's version through WordPress: Site Health or wp eval 'echo PHP_VERSION;' |
| Extension "installed" but the plugin says it is missing | Enabled in the CLI php.ini, not in the FPM one | php --ini for CLI, Site Health → Info → Server for FPM |
opcache_reset() in a CLI script "does nothing" | CLI has its own OPcache, separate from the FPM pool | Reset it inside a web request or reload PHP-FPM |
WPCS
Do not leave debug output in plugin code. The admin notice above escapes every value with esc_html(), as the WordPress Coding Standards require for any output, even a temporary one.
Practice
Find out which PHP the terminal uses, which php.ini it reads, whether OPcache is loaded and which PHP the site itself runs.
Interview Questions
PHP-FPM (FastCGI Process Manager) runs a pool of PHP worker processes separately from the web server. nginx or Apache passes .php requests to it over FastCGI. The pool can be sized and restarted independently, and each site can have its own pool, user and php.ini.
OPcache stores compiled opcodes of PHP files in shared memory, so files are not parsed on every request. When timestamp validation is off or delayed, a changed file keeps running the old code until the cache is reset, so a deploy should reload PHP-FPM or reset OPcache.
The CLI and PHP-FPM are separate binaries, often with several PHP versions installed side by side. The terminal uses whatever php is first in PATH; the site uses the FPM pool configured for it. Check the site's version through WordPress itself.