php-opcache

name	php-opcache
description	Use when optimizing PHP application performance or configuring OPcache: sizing memory and cache limits, tuning revalidation strategy, enabling JIT compilation, setting up preloading, or diagnosing cache saturation and unexpected behavior in production.

PHP OPcache

OPcache stores precompiled script opcodes in shared memory, eliminating parsing overhead on every request. Misconfiguration leads to silent cache misses, full-cache restarts, or stale code in production.

Production Config (Starting Point)

; Memory
opcache.memory_consumption=256
opcache.interned_strings_buffer=32

; Cache limits — count your PHP files: find . -type f -name "*.php" | wc -l
opcache.max_accelerated_files=20000

; Disable timestamp checking; invalidate manually on deploy
opcache.validate_timestamps=0

; Required by annotation-based frameworks (Doctrine, Symfony, PHPUnit)
opcache.save_comments=1

; JIT (PHP 8+) — tracing is the recommended mode
opcache.jit=tracing
opcache.jit_buffer_size=64M

; Optional: secondary disk cache for faster restarts
opcache.file_cache=/var/cache/php/opcache

See production.md for reasoning, gotchas, and monitoring.

Files in This Skill

File	Contents
configuration.md	Complete directive reference — all opcache.* settings, types, defaults, notes
production.md	Production tuning guide — recommended values, cache saturation, deployment gotchas
preloading.md	Preloading deep dive — when to use it, Symfony setup, performance expectations

Common Mistakes

Memory settings in FPM pool files don't work. opcache.memory_consumption and opcache.interned_strings_buffer are INI_SYSTEM, but OPcache allocates shared memory once at PHP startup — before pool configuration is applied. Settings in www.conf are silently ignored. Always configure in php.ini.

file_cache survives FPM reloads. When opcache.file_cache is set, systemctl reload php-fpm only clears the SHM cache. The disk cache persists and PHP reloads stale opcodes from it on restart. Full invalidation requires: rm -rf /var/cache/php/opcache/* && systemctl reload php-fpm.

Preloading is incompatible with Octane, Roadrunner, FrankenPHP, Lambda. These runtimes manage PHP state differently; enabling opcache.preload on them causes conflicts or is silently ineffective.

Key Concepts

Cache saturation — OPcache has no eviction. When memory is full and wasted memory is below max_wasted_percentage, every new script compiles on every request as if OPcache didn't exist. Monitor oom_restarts and cache_full via opcache_get_status().

Validate timestamps off — Disables filesystem stat() calls per request (~1–3% gain). Requires deliberate invalidation on deploy: opcache_reset(), opcache_invalidate(), or FPM reload.

JIT — Benefits CPU-bound code most (math, string processing). Negligible gain for typical I/O-bound web apps. Use tracing mode; allocate jit_buffer_size from separate memory (not memory_consumption).

Preloading — Loads files once at FPM startup. Useful only for apps already below ~100ms response time. Incompatible with Octane, Roadrunner, FrankenPHP, Lambda.