PHP OPcache Problems in WordPress – Stale Code & Cache Fix
Master the tricky "stale code" issues caused by PHP OPcache in WordPress. Learn how to debug, flush, and configure OPcache for optimal performance — from beginner to expert level.
📖 Introduction – The Stale Code Trap
You've just deployed a critical bug fix to your WordPress plugin. You upload the new file, refresh the page, and... the bug is still there. You clear your browser cache, try incognito mode, even restart your local server — but the old code persists. This is the classic PHP OPcache stale code problem.
Fatal ErrorPHP Warning: require(/var/www/site/wp-content/plugins/my-plugin/includes/functions.php):
failed to open stream: No such file or directory in /var/www/site/wp-content/plugins/my-plugin/my-plugin.php on line 22
Or more subtly, you may see no error at all — just outdated functionality. The culprit? OPcache is serving the old compiled bytecode instead of recompiling the changed source.
This guide covers everything from basic troubleshooting to advanced cache invalidation strategies, ensuring you never waste another hour chasing phantom code changes.
🧠 What is OPcache & How It Works
OPcache (Opcode Cache) is a PHP extension that stores precompiled script bytecode in shared memory. When a PHP script is executed, PHP compiles it into bytecode, which is then executed. Without OPcache, this compilation happens on every request, wasting CPU cycles. OPcache eliminates this by caching the compiled bytecode.
Key concepts:
- Bytecode cache – Stores compiled PHP code in memory for reuse.
- Invalidation – The process of clearing cached bytecode when source code changes.
- Timestamp validation – Checks file modification times to detect changes (if enabled).
- CLI vs Web cache – OPcache often behaves differently between command line and web server (PHP-FPM/Apache).
In WordPress, OPcache can dramatically improve performance, but stale code issues occur when the cache isn't invalidated after code changes.
🎯 Root Causes of OPcache Problems – Beginner to Expert
3.1 Beginner Level: Misconceptions & Basic Issues
- Assuming changes take effect immediately – OPcache may keep old code for up to
opcache.revalidate_freqseconds (default 2). - Not knowing OPcache is enabled – Many hosting providers enable it by default, leading to confusion when code changes don't reflect.
- Clearing browser cache but not OPcache – Browser cache is unrelated; OPcache is server-side.
- PHP CLI vs Web discrepancy – Editing code via WP-CLI may not reflect in web because CLI uses a separate OPcache instance.
3.2 Intermediate Level: Configuration Pitfalls
opcache.validate_timestamps=0– Disables timestamp checking, so changes are never detected until cache reset or server restart. Recommended for production performance but problematic during development.- High
opcache.revalidate_freq– Default is 2 seconds, but some setups set it to 60 or even 0 (always check). If set too high, changes take longer to appear. opcache.memory_consumptiontoo low – Cache fills up, forcing eviction and recompilation, reducing performance.- Shared hosting limitations – You may not be able to change OPcache settings or flush cache manually.
3.3 Expert Level: Advanced Scenarios
- Multi-server / load-balanced environments – OPcache may be local to each server, leading to inconsistent code versions across servers.
- Symlinked deployments – If code is deployed via symlink, OPcache may cache the old symlink target unless properly configured.
- PHP-FPM restart not always clearing OPcache – Graceful reloads may keep the OPcache if
opcache.validate_timestamps=0. - Zend OPcache vs APC – Confusion between different opcode caches can lead to double caching issues.
3.4 Most Expert Level: Hidden Bottlenecks
- OPcache file cache (opcache.file_cache) – If enabled, stale code may persist even after restart because the file cache is used as fallback.
- Shared OPcache in PHP-FPM with multiple pools – Different pools may have separate OPcache instances if
opcache.mmap_baseisn't coordinated. - WordPress cron and OPcache – WP-Cron running as CLI may use a different OPcache than web requests.
| Cause | Typical Symptom | Solution |
|---|---|---|
| validate_timestamps=0 | Changes never appear until restart | Set to 1 during development, 0 in production with explicit resets |
| revalidate_freq high | Changes take long to appear | Set to 0 (always check) or 2 seconds in dev |
| CLI vs web separate caches | WP-CLI changes not reflecting | Use opcache_reset() or restart web server |
| Memory limit reached | Performance degradation | Increase opcache.memory_consumption |
| File cache enabled | Stale code persists after restart | Clear file cache directory or disable |
🛠️ Debugging OPcache Issues – From Logs to Tools
4.1 Check OPcache Status
Create a PHP file (e.g., opcache-info.php) with the following content and access it via browser:
opcache-info.php<?php
phpinfo();
?>
Look for the OPcache section, or use opcache_get_status() to get detailed information programmatically.
OPcache Status// Get opcache status
$status = opcache_get_status();
print_r($status);
4.2 Flush OPcache
There are several ways to clear OPcache:
- Restart PHP-FPM or Apache (most reliable).
- Call
opcache_reset()in a PHP script (must be executed in the same SAPI as the cache). - Use WP-CLI command:
wp opcache flush(if the WP-CLI opcache package is installed). - Use a plugin like "OPcache Flush" or "Clear OPcache" from WordPress admin.
Flush via PHP<?php
if (function_exists('opcache_reset')) {
opcache_reset();
echo 'OPcache flushed';
} else {
echo 'OPcache not available';
}
?>
4.3 Enable OPcache Logging
Configure OPcache to log revalidations or errors:
php.iniopcache.log_verbosity_level = 1
opcache.error_log = /var/log/opcache.log
Check the log for clues about cache invalidation or memory issues.
4.4 Identify Stale Code with Timestamps
Use filemtime() and opcache_get_status() to check if the cached file timestamp is older than the source file.
Check Timestamps$file = '/var/www/site/wp-content/plugins/my-plugin/my-plugin.php';
echo 'File mtime: ' . filemtime($file) . "\n";
$status = opcache_get_status();
if (isset($status['scripts'][$file])) {
echo 'OPcache timestamp: ' . $status['scripts'][$file]['timestamp'] . "\n";
}
4.5 Test in Isolated Environment
To confirm OPcache is the issue, disable OPcache temporarily via php.ini or ini_set('opcache.enable', 0); and see if the problem persists.
🛒 WooCommerce & OPcache Scenarios
Problem: Checkout page not reflecting fix after plugin update
Business Context: A WooCommerce store updated a plugin to fix a critical checkout bug, but customers continued to experience the issue. The developer had uploaded the new files but OPcache was serving old bytecode because opcache.validate_timestamps=0 was set on the production server for performance.
Root Cause: OPcache wasn't checking file modification times, so the old code remained in cache.
Fix:
Fix# Restart PHP-FPM to flush OPcache
sudo systemctl restart php8.2-fpm
# Or add a manual flush mechanism in wp-config.php
if (isset($_GET['flush_opcache']) && current_user_can('manage_options')) {
opcache_reset();
echo 'OPcache flushed';
}
Problem: Payment gateway IPN callbacks still hitting old endpoint after migration
Business Context: After migrating to a new payment gateway IPN URL, some callbacks were still hitting the old endpoint because OPcache served a cached version of the routing file.
Root Cause: OPcache cached the old route definition; revalidate_freq was set to 60 seconds, causing delayed propagation.
Fix:
Fix# Set revalidate_freq to 0 for immediate detection during development
opcache.revalidate_freq = 0
5.1 OPcache and WooCommerce Rest API
WooCommerce REST API endpoints are PHP scripts, so OPcache can cache them too. If you modify an endpoint's code and don't flush OPcache, API consumers will get old responses.
🌐 REST API & AJAX OPcache Considerations
6.1 REST API Response Caching by OPcache
OPcache doesn't cache responses, only compiled PHP code. But if your endpoint's source code changes, OPcache may serve old compiled code, resulting in old data or logic until the cache is flushed.
Always flush OPcache after updating REST API endpoint code, especially if using opcache.validate_timestamps=0.
6.2 AJAX Handlers and OPcache
Admin AJAX handlers are also PHP scripts. If you update an AJAX handler and the old code is cached, the admin interface may behave unexpectedly. Use the same flushing strategies.
AJAX Flushadd_action('wp_ajax_flush_opcache', function() {
check_ajax_referer('opcache_nonce', 'nonce');
if (function_exists('opcache_reset')) {
opcache_reset();
wp_send_json_success('OPcache flushed');
}
wp_send_json_error('OPcache not available');
});
⚙️ Advanced OPcache Configuration – Expert Level
7.1 Key OPcache Directives Explained
| Directive | Description | Recommendation |
|---|---|---|
opcache.enable |
Enable OPcache | 1 |
opcache.memory_consumption |
Memory for cache (MB) | 128-256 for WordPress |
opcache.interned_strings_buffer |
Memory for strings | 8-16 |
opcache.max_accelerated_files |
Max files cached | 4000-10000 |
opcache.validate_timestamps |
Check file mtimes | 1 (dev), 0 (prod with reset) |
opcache.revalidate_freq |
How often to check (seconds) | 0 (always) or 2 |
opcache.file_cache |
File-based fallback cache | Usually disabled |
7.2 Configuring for Development vs Production
Development: Always set opcache.validate_timestamps=1 and opcache.revalidate_freq=0 to see changes immediately. You may even disable OPcache entirely for simplicity.
Production: For maximum performance, set validate_timestamps=0 and flush OPcache intentionally via deployment scripts (e.g., after git pull, run opcache_reset() or restart PHP-FPM).
7.3 Using WP-CLI to Flush OPcache
Install the WP-CLI OPcache package:
WP-CLIwp package install wp-cli/opcache-command
wp opcache flush
This will clear OPcache for the CLI process, but note it may not affect the web server's OPcache if they are separate. For web, you need to trigger a web request to opcache_reset() or restart PHP-FPM.
7.4 Deployments with Symlinks
When using symlinked deployments (e.g., Capistrano), OPcache may cache the real path of the old release. Configure opcache.use_cwd=1 and consider adding opcache_reset() in your deployment script after switching symlinks.
🤖 AI-Oriented Cache Optimization Trends (2026)
8.1 AI-Assisted OPcache Management
AI can analyze access patterns and automatically adjust OPcache settings (memory, file count, revalidate frequency) to optimize performance while minimizing stale code risks. Machine learning models can predict which files are likely to change and proactively invalidate them.
8.2 AI Tools for Cache Monitoring
| Tool | Type | AI Capability | Integration |
|---|---|---|---|
| New Relic APM | Application Monitoring | Anomaly detection in opcache hit rates | Cloud service |
| Datadog | Infrastructure Monitoring | Predictive cache sizing | Cloud service |
| GitHub Copilot | AI Pair Programmer | Suggests opcache_reset() calls in deployment scripts | VS Code |
| Custom ML Models | Predictive Maintenance | Forecast stale code risk based on change frequency | CI/CD pipeline |
8.3 AI-Resilient Deployment Practices
Use AI to automate post-deployment OPcache flushing and verify code freshness. For example, a CI/CD pipeline could use AI to compare file hashes and cached timestamps, triggering resets only when necessary, minimizing downtime.
AI Deployment Script# After code update
if [ "$(git diff --name-only HEAD@{1} HEAD)" ]; then
echo "Code changed, flushing OPcache..."
wp opcache flush
curl -s http://example.com/wp-admin/admin-ajax.php?action=opcache_flush
fi
8.4 LLM Prompt for OPcache Diagnosis
"You are a senior WordPress performance engineer. Analyze the following OPcache problem: [describe issue]. Current opcache settings: [settings]. Describe the root cause and recommend fixes. Include instructions for flushing cache in both CLI and web environments."
🎤 Interview Questions & Answers — All Levels
Click any question to expand the answer. Filter by level to focus your preparation.
💼 Business Problem-Solving Scenarios
Real-world business challenges where OPcache issues caused significant impact:
Problem: New Discount Code Not Working After Plugin Update
Business Impact: A store launched a promotional discount code, but customers couldn't use it because the plugin update that added the code wasn't being reflected. The promo was active for 2 hours before the issue was noticed.
Root Cause: OPcache was serving old plugin code because opcache.validate_timestamps=0 was set for performance. The update was uploaded but not applied.
Solution:
- Flushed OPcache by restarting PHP-FPM.
- Updated deployment script to include
opcache_reset()after file upload. - Set
validate_timestamps=1during non-peak hours for future updates.
Lesson: Always include a cache flush step in deployment processes.
Problem: Mobile App Receiving Old Data from REST API
Business Impact: A mobile app using a WordPress REST API was receiving outdated product data because OPcache cached the endpoint's code before the data source was updated.
Root Cause: OPcache served old compiled code that referenced an old database table. The code update was uploaded but not flushed.
Solution:
- Configured OPcache to revalidate timestamps every 0 seconds for faster detection.
- Added a version query parameter to API responses to bust caches.
- Implemented automated OPcache flush after API code deployment.
Lesson: For APIs, ensure cache invalidation is part of the release process.
Problem: Security Patch Not Applied Due to OPcache
Business Impact: A critical security vulnerability in a plugin was patched, but the old vulnerable code remained active on production for over an hour due to OPcache serving stale code.
Root Cause: The server had opcache.validate_timestamps=0 and no automated flush. The admin manually uploaded the patch but forgot to flush OPcache.
Solution:
- Immediately flushed OPcache via restart.
- Implemented a security plugin feature to force OPcache flush after updates.
- Changed configuration to
validate_timestamps=1withrevalidate_freq=0for faster response.
Lesson: Security patches must be verified as active, not just uploaded.
🏆 Best Practices & Prevention Strategies
11.1 Development Environment
- Set
opcache.validate_timestamps=1andopcache.revalidate_freq=0. - Or disable OPcache entirely to avoid confusion:
opcache.enable=0. - Use version control and clear caches after pulling changes.
11.2 Production Environment
- For max performance, set
validate_timestamps=0but implement a robust deployment process with automatic OPcache flush. - Include a flush step in your CI/CD pipeline (e.g., call
opcache_reset()via a web endpoint or restart PHP-FPM). - Monitor OPcache hit rate and memory usage with tools like New Relic.
- Keep
opcache.memory_consumptionadequate to avoid eviction.
11.3 Deployment Process
- After updating files, trigger OPcache reset immediately.
- Use a code deployment tool that integrates with OPcache (e.g., Deployer, Capistrano with opcache_reset task).
- For load-balanced setups, flush OPcache on all servers.
11.4 Monitoring and Alerts
- Set up alerts for OPcache memory exhaustion or low hit rate.
- Log OPcache resets and cache misses for debugging.
- Use
opcache_get_status()in a health check endpoint.
11.5 CI/CD Pipeline Checks
| Stage | Check | Tool |
|---|---|---|
| Code Review | Ensure no dependency on stale cache | GitHub PRs |
| Deployment | Execute opcache_reset after upload | Deploy script |
| Post-Deploy | Verify file hash vs cached timestamp | Custom health check |
| Production | Monitor OPcache hit rate | New Relic, Datadog |
🎯 Conclusion – From Cache Confusion to Mastery
OPcache is a double-edged sword: it can dramatically speed up WordPress, but if misconfigured, it leads to frustrating stale code issues. By understanding how it works and implementing proper cache invalidation strategies, you can enjoy the performance benefits without the headaches.
opcache_reset(), restart PHP-FPM, or a custom script, make it an automatic part of your workflow.
Whether you're preparing for a job interview, troubleshooting a production site, or planning an upgrade, the principles in this guide will serve you well.
Keep learning, keep optimizing, and never let stale code slow you down. 🚀
No comments:
Post a Comment
Thanks for your valuable comment...........
Md. Mominul Islam