OPcache Preloading
OPcache preloading compiles selected PHP files into OPcache when the PHP process starts (for example, when PHP-FPM restarts or the server reboots). The goal is to reduce "cold start" latency so the first few dynamic requests don't pay the compilation cost.
Most WordPress sites do not need preloading. Standard OPcache warms quickly after the first requests. Consider preloading only if you restart PHP frequently and you have measurable cold-start pain.
OPcache vs Preloading
| Configuration State | Immediate Technical Reality |
|---|---|
| Standard OPcache (Enabled) | The server reads and parses wp-settings.php precisely once when Visitor A hits the site, caching the machine code permanently for Visitor B. |
| OPcache Preloading (Enabled) | The server compiles wp-settings.php into RAM exactly when the PHP daemon boots. Visitor A receives the accelerated cached result immediately. |
What to Preload (And What Not To)
Avoid preloading code that changes frequently. Preloading is easiest in controlled deployments where code changes happen via a release process.
| File Path Vector | Configuration Volatility | Preload Viability |
|---|---|---|
wp-settings.php | Hyper-Stable Core Bootstrap | Yes |
wp-includes/load.php | Rigid Core Logic Loader | Yes |
wp-includes/plugin.php | Standard Filter Architectures | Yes |
wp-config.php | Environment-specific config | Usually No |
/wp-content/themes/*/ | Theme code changes more often | Usually No |
If you preload plugin/theme code and that code changes, you must restart PHP to pick up the new code.
Implementation (Example)
Preloading is configured with two pieces:
- A preload script that compiles selected files.
opcache.preloadandopcache.preload_userdirectives in your PHP configuration.
Create a Preload Script
# Place this outside the web root
sudo nano /etc/php/opcache-preload.php
Example preload script:
<?php
// Keep this list limited to stable files
$files = [
'/var/www/html/wp-includes/load.php',
'/var/www/html/wp-includes/plugin.php',
'/var/www/html/wp-includes/class-wp-hook.php',
'/var/www/html/wp-settings.php',
];
foreach ($files as $file) {
if (file_exists($file)) {
opcache_compile_file($file);
}
}
?>
Configure PHP
Add these directives to your OPcache configuration (file location varies by distro and PHP handler):
opcache.preload=/etc/php/opcache-preload.php
; Must match the user PHP runs as (example: www-data)
opcache.preload_user=www-data
Restart PHP
Restart the PHP handler so the preload script runs:
sudo systemctl restart php8.3-fpm
If you're running LiteSpeed/OpenLiteSpeed, restart the relevant service instead.
Internal Health Validation Parameters
Confirm the settings are loaded (note: CLI output may differ from FPM/LSAPI):
php -i | grep preload
Expected Terminal Metric:
opcache.preload => /etc/php/opcache-preload.php
opcache.preload_user => www-data
Common Mistakes & Troubleshooting
| Configuration Failure | Operational Symptom | Remediation Protocol |
|---|---|---|
| Code changes not applied | Updates/deploys don't take effect until later. | Preloading requires a PHP restart to pick up changes to preloaded files. |
| Memory pressure on boot | PHP fails to start or returns 502/504 after restart. | Reduce preload scope and ensure OPcache has enough memory_consumption headroom. |