APCu — In-Process User Cache

Also Known As

TL;DR

Explanation

APCu (APC User Cache) provides a key-value store in shared memory segments accessible to all PHP-FPM worker processes on a single server. With no serialisation over a network socket, APCu reads are extremely fast — nanoseconds vs microseconds for Redis. Ideal for: parsed application configuration, compiled route tables, permission trees, and any rarely-changing but frequently-read data. Limitations: data is local to one server (multi-server deployments need a distributed cache for shared state) and all data is lost on PHP-FPM restart. Use apcu_store(), apcu_fetch(), apcu_exists(), and apcu_delete(). Check memory usage with apcu_sma_info().

Diagram

flowchart TD
    REQ[PHP Request] --> CHECK{APCu cache<br/>has key?}
    CHECK -->|HIT| RETURN[Return cached value<br/>O of 1 microseconds]
    CHECK -->|MISS| DB[(Database or API)]
    DB --> STORE[Store in APCu<br/>shared memory]
    STORE --> RETURN
    subgraph Shared Memory
        W1[Worker 1] & W2[Worker 2] & W3[Worker 3]
        W1 & W2 & W3 <-->|all share| MEM[(APCu<br/>in-process cache<br/>per server)]
    end
    INFO[No network hop<br/>Same process memory<br/>Lost on restart]
style RETURN fill:#238636,color:#fff
style MEM fill:#1f6feb,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Using APCu in a multi-server environment expecting shared state — APCu is per-server, not distributed; use Redis for that.
• Not setting a reasonable TTL — stale data lives forever without expiry.
• Not checking apcu_fetch() return value — it returns false for a cache miss, which is falsy and can be confused with a cached false value; use the success parameter.
• Caching objects that hold database connections or file handles — those are not serializable.

Avoid When

• Multi-server deployments — APCu is per-process/per-server and does not share data across nodes.
• Storing large objects — APCu memory is shared with PHP workers and exhausting it crashes requests.
• Data that must be consistent across all servers — use Redis or Memcached for shared cache.
• CLI scripts — APCu in CLI uses a separate memory pool isolated from the web server processes.

When To Use

• Single-server applications or worker processes where shared-memory cache is sufficient.
• Caching config, translations, or compiled data that is identical across requests on the same server.
• Ultra-low-latency caching — APCu is faster than Redis because there is no network roundtrip.
• OPcache extension companion — APCu caches user data while OPcache caches compiled bytecode.

Code Examples

// Miss detection bug — cached false indistinguishable from cache miss:
$result = apcu_fetch('key');
if (!$result) { // Wrong — also triggers when cached value is false or 0
    $result = expensiveQuery();
    apcu_store('key', $result, 300);
}

// Correct:
$result = apcu_fetch('key', $success);
if (!$success) {
    $result = expensiveQuery();
    apcu_store('key', $result, 300);
}

// APCu — in-process shared memory cache (same server, same PHP-FPM pool)
// Install: pecl install apcu; extension=apcu.so in php.ini

// Store & retrieve
apc_store('config:theme', 'dark', 3600);   // TTL in seconds
$theme = apc_fetch('config:theme', $success);
if (!$success) { /* cache miss */ }

// Atomic increment — race-condition-free counters
apc_inc('page_views:home');

// Clear specific key or all
apc_delete('config:theme');
apc_clear_cache();

// Good for: PHP-computed config, feature flags, hot lookup tables
// Not good for: session data, shared across multiple servers (use Redis instead)

References

• ↗ https://www.php.net/manual/en/book.apcu.php

Tags

Related Terms