Skip to content
BOA Documentation

Powered by Grav

PHP opcache & APCu

PHP opcache & APCu

Below Drupal's caches sit two PHP-level ones you never configure but will definitely notice: opcache, which caches compiled PHP code, and APCu, a small per-worker memory cache that Drupal 8+ uses as a front tier for its hottest bins. Both are sized and managed by the server; what's useful to you is knowing how they behave — and the one self-service lever you have.

Why changes take about a minute

You'll see this note all over these docs: "give it about a minute." Opcache is why. PHP keeps your compiled code (and the INI control files BOA reads through it) cached for speed and re-checks files roughly every 60 seconds — so a code change you deploy, or a control-file line you save, becomes live within a minute rather than on the very next request. It's not broken; it's warming.

There's one clean way around the wait while you develop: on a .dev. preview URL, BOA tells opcache to re-check your files instantly, so code changes show up on the very next .dev. request. On the production names, patience is the right tool. (The graceful reload at the bottom of this page exists for a different problem: stale APCu.)

APCu: the per-worker front tier (Drupal 8+)

On Drupal 8+ sites, BOA upgrades the three hottest cache bins — bootstrap, discovery, and config — to the ChainedFast backend. Reads try three tiers in order:

TXT
APCu (inside each PHP worker)  →  Redis/Valkey (shared)  →  Database

APCu is memory inside each PHP-FPM worker process: the fastest possible read, but local to that worker and invisible to Drush on the command line. Valkey is the shared tier that keeps all workers consistent. This layering is deliberate and load-bearing — overriding it in local.settings.php (say, pinning discovery to the database because of a transient error) is a performance regression on every request. If a cache bin is misbehaving, the causes are almost always elsewhere; start at Something looks broken.

Drupal 6/7 sites don't use an APCu tier — their bins live directly in Redis/Valkey, as described on The Redis/Valkey object cache.

When APCu goes stale — and the self-service fix

Because APCu lives inside each worker process, it can't be flushed remotely — not by drush cc all, not by a Valkey flush, not by the Clear caches task. A stale APCu entry (an old field definition, a plugin list from before your update, a renamed Solr core) only clears when the worker processes are recycled.

BOA gives you a graceful way to do exactly that, without dropping a single active connection. From your shell or over SFTP, create one empty file in your account's control folder:

BASH
touch ~/static/control/run-php-fpm-reload.pid

The server's monitor spots the file shortly afterwards, gracefully reloads every installed PHP-FPM version — which clears APCu across all workers — and removes the file itself when done. A built-in cooldown of about 30 seconds prevents reload storms if it's triggered repeatedly.

Reach for it after a platform update, a config change that won't stick, or a Solr core rename — the classic stale-APCu moments. If the file just sits there and nothing happens, the feature isn't enabled for your account's plan; open a support request instead and your host will reload FPM for you.

One case needs no action at all: after a brief Redis/Valkey outage, BOA clears the APCu tier automatically on recovery (redis_flush_apcu_on_recovery, on by default), so the degraded window can't leave stale front-tier entries behind.

What's the server's to manage

Opcache and APCu capacity are managed on the server side — APCu's budget scales with the server's memory, opcache uses a fixed allocation — and there's no INI control-file setting for either; hand-edits to PHP configuration aren't yours to make on a hosted account. If your site's workload genuinely needs bigger PHP-level caches, that's a conversation with your host: open a support request and describe the symptom rather than the setting.

© 2026 BOA Documentation. All rights reserved.