Diagnosing a Non‑Functional Zend Server OPcache: A Step‑by‑Step Checklist

Problem Statement

When Zend Server’s OPcache is not functioning, you’ll notice:

• High CPU usage from repeated PHP compilation
• Slow initial requests and inconsistent performance
• phpinfo() shows opcache.enable = 0 or missing cache statistics

These symptoms usually stem from mis‑configured php.ini directives, permission issues, or extension conflicts.

Common Causes & Quick Diagnostic Table

Cause	Diagnostic Indicator
OPcache disabled in php.ini	phpinfo() shows opcache.enable = 0
Cache directory too small or missing	High cache hit rate < 10 % and frequent opcache_get_status() errors
Unwritable opcache.file_cache directory	File creation errors in error_log
Conflicting caching extensions (APCu, Zend OPcache)	Extension list contains both, and OPcache is disabled automatically
Corrupted cache from abrupt shutdowns	Repeated recompilation after server restart
Misconfigured include_path or open_basedir	Scripts not found in cache, phpinfo shows restrictions
Missing opcache.enable_cli for CLI scripts	CLI scripts recompile on every run, but web requests are cached
PHP‑FPM or Apache misconfiguration	Initial requests remain slow after OPcache activation

Ordered Diagnostic Checks

1. Verify OPcache status via phpinfo()

   # Create /var/www/html/info.php
   <?php phpinfo(); ?>
   

   Open http://your.server/info.php and confirm opcache.enable = 1 and other memory settings are present.

2. Check cache statistics programmatically

   # Run as web‑server user
   php -r 'var_dump(opcache_get_status(true));'
   

   Look for opcache_statistics and a non‑zero total_accelerated_files.

3. Inspect cache directory permissions

   # Replace /var/lib/php/opcache with your actual path
   ls -ld /var/lib/php/opcache
   

   Ensure the directory is owned by the web‑server user (e.g., www-data) and has write permission.

4. Identify conflicting extensions

   # List loaded extensions
   php -r 'print_r(get_loaded_extensions());'
   

   If both apcu and Zend OPcache appear, consider disabling one.

5. Confirm open_basedir and include_path

   # In phpinfo() or via script
   var_dump(ini_get('open_basedir'));
   var_dump(ini_get('include_path'));
   

   Ensure script directories are within the allowed paths.

6. Check for abrupt shutdown logs

   # System journal for PHP‑FPM or Apache
   journalctl -u php-fpm -b | grep -i opcache
   

   Look for errors indicating cache corruption.

Fixes Tied to Findings

• Enable OPcache

  # Edit /etc/php/8.2/php.ini (or Zend Server equivalent)
  opcache.enable=1
  opcache.enable_cli=1
  opcache.memory_consumption=128
  opcache.interned_strings_buffer=8
  

  Restart Zend Server: systemctl restart zend-server.

• Adjust cache size or directory

  # Increase memory
  opcache.memory_consumption=256
  # Set a dedicated cache directory
  opcache.file_cache=/var/lib/php/opcache
  opcache.file_cache_consistency_checks=1
  

  Ensure the directory exists and has proper ownership.

• Fix permissions

  # Example for Apache running as www-data
  chown -R www-data:www-data /var/lib/php/opcache
  chmod 700 /var/lib/php/opcache
  

  Test by creating a dummy PHP file and accessing it.

• Resolve extension conflicts

  # Disable APCu in Zend Server config
  extension=apcu.so
  # or remove from php.ini
  

  Restart Zend Server.

• Clear corrupted cache

  # Remove stale files
  rm -rf /var/lib/php/opcache/*
  # Or reset via phpinfo() settings
  opcache.reset=1
  

  After restart, verify total_accelerated_files increases.

• Adjust open_basedir and include_path

  # Add script directories
  open_basedir=/var/www/html:/usr/share/php
  include_path=.:/var/www/html:/usr/share/php
  

  Restart Zend Server.

• Warm cache for PHP‑FPM

  # Enable preloading (PHP 8.2+)
  opcache.preload=/var/www/html/preload.php
  

  Create preload.php that requires all critical scripts.

Verification Checklist

1. Re‑run phpinfo() and confirm opcache.enable = 1.
2. Execute php -r 'var_dump(opcache_get_status(true));' and verify opcache_statistics shows non‑zero cache hits.
3. Make a request to a known PHP page and check server logs for any OPcache error messages.
4. Measure page load times before and after changes; a noticeable drop indicates successful caching.

Escalation Criteria

If after applying all fixes the cache remains inactive or performance does not improve, consider:

• Reviewing Zend Server logs for OPcache specific errors.
• Ensuring no other modules (e.g., mod_php, php-fpm) are overriding settings.
• Contacting Zend Support with the following details:
  
  • Zend Server version and PHP build.
  • Exact php.ini directives used.
  • Output from opcache_get_status(true) and phpinfo().
  • Relevant log excerpts.

Limitations and Cautions

• Changing opcache.memory_consumption increases RAM usage; monitor free -m to avoid swapping.
• Enabling opcache.enable_cli in production exposes compiled scripts to any CLI user; restrict access accordingly.
• Modifying file permissions may affect other services; use ACLs if necessary.
• Restarting Zend Server is required for all php.ini changes; partial reloads will not apply new settings.

Practical Check: Confirming Cache Hit Rate

After applying the fixes, run:

php -r 'var_dump(opcache_get_status(true));'

Look for a high opcache_statistics.total_hits relative to total_requests (ideally > 90 %).