PHP-FPM opcache.validate_timestamps: the development setting that costs production

The default opcache.validate_timestamps = 1 is convenient for development: edit a file, refresh the browser, see the change immediately. In production, that same convenience becomes a per-request filesystem tax and, with frequent deploys, a silent source of OPcache fragmentation.

The trade-off is not subtle. Leave validate_timestamps enabled and PHP stats source files on every request (or at the interval set by revalidate_freq), burning syscalls and CPU. Disable it and PHP serves cached bytecode forever, which means a deploy that does not explicitly clear OPcache will serve stale code to every user until someone intervenes. Neither option is free. The question is which cost you can control.

What it is and why it matters

opcache.validate_timestamps controls whether PHP re-checks the modification time (mtime) of each source file before serving its cached bytecode. When enabled (the default), PHP issues a stat() syscall on included files at the frequency set by opcache.revalidate_freq. If the file has changed on disk, OPcache recompiles it. This is the behavior developers want locally: save a file, hit reload, the new code runs.

The cost in production is twofold. First, every stat() is a syscall that touches the filesystem. On a large framework that includes thousands of files per request, this adds up. Second, with revalidate_freq = 0, PHP stats on every request, which is the worst case for throughput. Running with opcache.validate_timestamps = 1 in production causes silent performance degradation through per-request syscalls that scale with codebase size and traffic.

The production recommendation is the opposite: set validate_timestamps = 0. PHP never stats source files, never recompiles on its own, and the cache is stable until you explicitly clear it. The trade-off is operational, not technical: you now own the invalidation step in your deploy pipeline.

How it works

When a PHP request begins, OPcache is consulted before the compiler. With validate_timestamps = 1, the flow for each included file is:

1. Check if the file’s compiled bytecode is in the OPcache shared memory.
2. If cached, check whether revalidate_freq seconds have elapsed since the last mtime check.
3. If the interval has elapsed, issue stat() to read the file’s current mtime.
4. If mtime changed, mark the old bytecode as wasted memory and compile the new version into the cache.
5. If mtime is unchanged, serve the cached bytecode.

With validate_timestamps = 0, steps 2 through 4 are skipped entirely. OPcache serves whatever bytecode it has, forever, until an explicit reset, FPM restart, or SIGUSR2 reload clears the shared memory segment.

flowchart TD
    A[Request includes file.php] --> B{In OPcache?}
    B -- No --> C[Compile from disk]
    C --> D[Cache bytecode]
    D --> E[Serve request]
    B -- Yes --> F{validate_timestamps?}
    F -- "0 (production)" --> E
    F -- "1 (default)" --> G{revalidate_freq elapsed?}
    G -- No --> E
    G -- Yes --> H[stat file mtime]
    H --> I{mtime changed?}
    I -- No --> E
    I -- Yes --> J[Mark old as wasted memory]
    J --> C

The critical consequence of disabling validation: deploying new code does NOT update what users see. The old bytecode is served until you intervene. This is the source of the “I deployed but nothing changed” incident.

When validation is enabled and a deploy changes files on disk, the old cache entries are marked as wasted memory but cannot be freed without a full OPcache restart. Repeated deploys without a cache clear fragment the shared memory segment, pushing it toward the opcache.max_wasted_percentage threshold and potential restarts.

Where it shows up in production

Leftover development defaults. Many PHP-FPM deployments inherit validate_timestamps = 1 from the distro package or Docker image. It works, so nobody questions it. The per-request stat() cost is invisible until traffic scales or the codebase grows.

Wasted memory accumulation during deploys. When validate_timestamps = 1 and code changes during a deploy, old cache entries are marked as wasted memory. The default opcache.max_wasted_percentage is 5%, so an actual full-cache restart can happen much earlier unless that limit has been raised. A wasted-memory reading above 30% indicates severe fragmentation; it is not the upstream restart threshold. On a system deploying multiple times per day, this accumulates fast. The fix is not to tune max_wasted_percentage higher but to clear the cache on deploy.

Deploy without cache clear (the dangerous combination). The most damaging scenario is validate_timestamps = 0 paired with a deploy process that does not clear OPcache. Old and new bytecode both consume the shared memory, crowding the cache toward saturation. Worse, users see the old code until someone notices and manually clears the cache.

Symlink-based deploys. With release-directory-plus-symlink-swap deploy strategies, each release creates new file paths. OPcache keys entries by file path, so the same script ends up cached at multiple paths. With validate_timestamps = 0, those stale entries persist until explicitly invalidated or the cache is reset. The cache fills faster than you would expect from the actual codebase size.

NFS and network filesystems. On NFS-mounted code, file mtime may not be reliable across NFS clients. With validate_timestamps = 1, this makes cache invalidation behavior unpredictable. Disabling timestamp validation removes the dependency on cross-client mtime consistency, which is why it is recommended for NFS-mounted codebases.

Tradeoffs and when to use it

The decision is not whether to disable timestamp validation in production. You should. The decision is whether your deploy pipeline is disciplined enough to clear OPcache reliably on every release. If it is not, the safer temporary state is leaving validate_timestamps = 1 and accepting the stat() cost. Serving stale bytecode silently to every user is worse than paying a measurable syscall tax.

Clearing OPcache on deploy. Two reliable methods:

• Call opcache_reset() from within the PHP-FPM SAPI. This must be invoked through FPM, not CLI. CLI PHP has a separate opcache (or none at all), so running opcache_reset() from the command line does not affect the FPM worker pool’s cache. A common pattern is a small PHP script restricted to localhost that calls opcache_reset() and is hit as the final step of the deploy pipeline.
• Reload PHP-FPM via SIGUSR2 (systemctl reload php-fpm or equivalent). The graceful reload drains workers and re-execs the master process, which clears the shared memory segment entirely. Be aware that there is a brief window during re-exec where no new workers are available. On high-traffic sites, this window can produce transient 502 errors.

For symlink deploys, call opcache_reset() after the symlink swap, or reload FPM as the final deploy step. Without one of these, the old release’s bytecode remains cached alongside the new release’s, doubling OPcache memory consumption per deploy cycle.

The deploy discipline checklist. If you are moving from validate_timestamps = 1 to validate_timestamps = 0:

• Confirm the deploy pipeline clears OPcache. Either opcache_reset() via FPM or a graceful reload. Test this end to end on staging before changing production.
• Verify the clear takes effect. After deploy, check opcache_get_status() to confirm the cached scripts count reset and the hit rate drops temporarily during warmup.
• Watch for warmup latency. After a cache clear, the first requests for each script compile from disk. High CPU with low throughput immediately after a restart is expected and should resolve within minutes as the cache warms.
• Document the rollback procedure. If a deploy ships broken code and validate_timestamps = 0, rolling back the code is not enough. You must clear OPcache again after the rollback, or workers continue serving the broken bytecode from cache.

Signals to watch in production

The key diagnostic distinction: if OPcache hit rate drops and CPU spikes across all workers simultaneously, the cache is thrashing or cold. If hit rate is stable but latency increases, the problem is downstream (database, external API, session locks), not OPcache. Correlating hit rate with CPU pattern tells you which side of the compiler the bottleneck is on.

How Netdata helps

• OPcache hit rate, used memory, free memory, wasted memory, and restart counters are collected per second, so the exact moment a deploy caused fragmentation or a cache wipe is visible in the timeline.
• Correlating OPcache hit rate drops with PHP-FPM worker CPU and request duration distinguishes compilation thrash (hit rate down, CPU up across all workers) from a slow dependency (hit rate stable, CPU low, workers blocked on I/O).
• Per-worker RSS tracking catches the memory pressure that a deploy-without-cache-clear creates when old and new bytecode crowd the OPcache shared memory segment.
• Filesystem and disk I/O metrics surface the stat() syscall cost that validate_timestamps = 1 imposes, which is invisible in PHP-FPM’s own status page.
• Anomaly detection on OPcache hit rate and wasted memory flags post-deploy fragmentation before it crosses a fixed percentage threshold.

Related guides

• PHP-FPM 504 Gateway Timeout: requests accepted but never finishing in time
• PHP-FPM active processes near max_children: reading pool utilization
• PHP-FPM in containers: cgroup limits and the silent OOM kill
• PHP-FPM “child N exited on signal 11 (SIGSEGV)”: worker segfaults
• PHP-FPM crash loop and fork storm: workers dying faster than they serve
• PHP-FPM dynamic mode scaling lag: why the pool cannot keep up with bursts
• PHP-FPM emergency restart: “failed processes threshold reached, initiating reload”
• PHP-FPM graceful reload: the brief no-worker window on SIGUSR2
• How PHP-FPM actually works in production: a mental model for operators
• PHP-FPM idle processes at zero: no burst headroom left
• PHP-FPM listen queue growing: the earliest signal of saturation
• PHP-FPM “server reached pm.max_children setting (N), consider raising it”