How to clear APC cache entries?

How to clear APC cache entries?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to Clear APC Cache Entries

When deploying a new version of a PHP application, stale opcode caches can cause fatal errors or unexpected behavior because the old code remains in memory while the new files are written to disk. While the web interface in APC.php offers a convenient button to clear all entries, that option is often absent from production environments for security and resource reasons. More critically, you cannot simply click a button to selectively wipe user or system entries; the architecture of APCu separates these concerns, requiring specific commands to target them effectively.

The most reliable method for clearing cache via the command line relies on the apcu_clear_cache() function, which is available in the PHP CLI environment if the APC extension is loaded. This single call removes all user data and opcodes currently held in memory. However, there is a significant nuance regarding system entries. In standard APCu configurations, system entries (which store configuration directives like apc.shm_segments or internal metadata) are not typically cleared by the standard cache flush function because they are managed differently by the shared memory allocator. If you need to reset these system-level structures, you often have to restart the PHP-FPM service or the web server process entirely, effectively forcing an unload of the entire shared memory segment.

If you are managing a clustered environment with multiple application servers, relying solely on apcu_clear_cache() might not be enough if your deployment strategy involves upgrading the APCu extension version itself. When the extension version changes, the internal data structures in the shared memory segment can become incompatible with the old binary format. In scenarios where the extension has been updated between deployments, simply calling the clear function will result in a crash upon the next request because the application tries to read corrupted metadata. In these specific cases, restarting the PHP process is mandatory to reallocate the shared memory with the new structure.

For high-traffic applications, a full restart can introduce unacceptable downtime. In such scenarios, you might consider using apcu_store() with custom expiration times or leveraging alternative caching layers like Redis or Memcached, which offer more robust eviction policies and do not rely on volatile shared memory segments that require process restarts to reset. If you are using APCu specifically for its opcode caching benefits and cannot switch stacks immediately, ensure your deployment script includes a step to restart the PHP-FPM pool or Apache worker processes after writing the new code but before traffic is routed back to the server.

There is also the matter of apc.stat. This directive controls whether APC checks file timestamps to determine if opcodes need updating. If you set apc.stat=0 to improve performance, your application assumes that no source files have changed unless you manually clear the cache. Consequently, every deployment with apc.stat=0 becomes a mandatory trigger for clearing the user data or restarting the process. This is a classic trade-off between lookup speed and deployment safety. Without careful management of this setting, teams often face "silent" failures where the application runs on code that no longer exists on disk.

If you are looking for enterprise-grade managed hosting solutions that handle these complexities automatically, including automatic cache invalidation during deployments, you might explore services like https://laravelcompany.com. These platforms often abstract away the shared memory management and provide tools to ensure your code is always running from the latest version without manual intervention.

Ultimately, there is no native command-line switch to selectively purge only system or per-directory entries while leaving user data intact in standard APCu implementations. The architecture prioritizes speed over granular control of the cache segments. Your strategy must therefore focus on managing the entire shared memory segment through restarts or full clears, ensuring that your deployment pipeline accounts for the inevitable need to reset the state after every code change.

Our network