Configure and Verify Zend OPcache Bytecode Caching for PHP Applications

Desired Outcome

Enable Zend OPcache so PHP scripts are compiled once and served from shared memory. This reduces parsing and compilation overhead. The configuration must also ensure that deployed code changes are visible without serving stale bytecode.

Prerequisites

• PHP 5.5.0 or newer with the Zend Engine. Most modern distributions include OPcache by default.
• Access to the global php.ini or a per-directory .user.ini file. Root or sudo access is required to edit global settings and restart services.
• Enough RAM for the cache. A typical medium application needs 64 MiB to 256 MiB.
• A web server such as Apache or Nginx with PHP-FPM, or a CLI environment you can restart after changes.

Procedure

1. Confirm OPcache is available. Run this on the server where PHP executes:

   php -i | grep -i opcache

   Look for opcache.enable => On and the active directive values.
2. Edit php.ini (or .user.ini) and set production directives:

   opcache.enable=1
   opcache.memory_consumption=128
   opcache.max_accelerated_files=10000
   opcache.revalidate_freq=60
   opcache.validate_timestamps=0

   • opcache.memory_consumption sets shared memory in megabytes.
   • opcache.max_accelerated_files sets the maximum number of cached script files.
   • opcache.revalidate_freq sets the timestamp check interval in seconds when timestamp validation is enabled.
   • opcache.validate_timestamps=0 disables timestamp checks. Use 1 in development.
3. Apply the configuration. After editing php.ini, restart PHP-FPM:

   systemctl restart php-fpm

   Run as root or with sudo. This causes a brief service interruption. If you used .user.ini, no restart is required.
4. Create a verification script named opcache_status.php in a web-accessible directory:

   <?php
   $status = opcache_get_status();
   var_dump($status['opcache_enabled']);
   var_dump($status['cache_full']);
   var_dump($status['num_cached_keys']);
   ?>

   Access it with a browser or curl. Expect bool(true) for enabled, bool(false) for cache_full, and an integer greater than zero for cached keys.
5. Verify update behavior. Edit opcache_status.php, such as adding a comment, then reload the page. With opcache.validate_timestamps=1, the change appears immediately. With 0, the change appears only after opcache_reset() or a PHP-FPM restart.

Expected Checks

• Run php -i | grep -i opcache after changes to confirm directives match your intent.
• Use the verification script to check opcache_enabled, cache_full, and num_cached_keys before and after traffic. An increase in cached keys means scripts are being cached.
• Under load, monitor opcache_get_status()['cache_full']. If it becomes true, increase memory_consumption or max_accelerated_files.

Recovery Options

If stale code persists after deployment:

• Run opcache_reset(); from a temporary script or the command line to flush the bytecode cache.
• Restart the PHP-FPM pool so workers rebuild the cache from current files.
• Temporarily set opcache.validate_timestamps=1 in development to force immediate reflection of file changes.

These actions affect only the in-memory cache, not source files.

Limitations and Practical Verification

OPcache uses shared memory per SAPI. CLI and PHP-FPM maintain separate caches, so a CLI change does not invalidate a running FPM worker. Check opcache_get_status() in both contexts to confirm.

Memory exhaustion or hitting max_accelerated_files causes cache misses and falls back to normal compilation. Requests do not fail, but latency may rise. Monitor cache_full under realistic traffic.

OPcache does not cache user data. Use APCu or Redis for application-level caching. Bytecode inspectors or debuggers that expect fresh compilation may behave unexpectedly with validate_timestamps=0.

Summary

Enable OPcache, tune memory_consumption and max_accelerated_files, and set validate_timestamps based on environment. Verify with php -i, opcache_get_status(), and a test script. Use opcache_reset() or a service restart when stale code appears.