{
    "slug": "apc_apcu",
    "term": "APCu — In-Process User Cache",
    "category": "performance",
    "difficulty": "intermediate",
    "short": "APCu stores PHP values in shared memory within the PHP-FPM pool — the fastest possible cache with no network hop overhead.",
    "long": "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().",
    "aliases": [
        "APCu",
        "APC user cache",
        "PHP in-memory cache"
    ],
    "tags": [
        "php",
        "performance",
        "caching"
    ],
    "misconception": "APCu cache is shared across all web requests automatically. APCu is per-process in PHP-FPM — data cached in one worker process is not visible to others unless you use a shared cache like Redis or Memcached. APCu is suitable for per-process memoization, not cross-request shared state.",
    "why_it_matters": "APCu is PHP's in-process user cache — it stores computed values in shared memory across requests on the same server, eliminating redundant computation with near-zero latency.",
    "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."
    ],
    "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."
    ],
    "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."
    ],
    "related": [
        "caching",
        "opcache",
        "redis_patterns",
        "opcode_caching"
    ],
    "prerequisites": [
        "caching",
        "php_extensions",
        "opcache"
    ],
    "refs": [
        "https://www.php.net/manual/en/book.apcu.php"
    ],
    "bad_code": "// Miss detection bug — cached false indistinguishable from cache miss:\n$result = apcu_fetch('key');\nif (!$result) { // Wrong — also triggers when cached value is false or 0\n    $result = expensiveQuery();\n    apcu_store('key', $result, 300);\n}\n\n// Correct:\n$result = apcu_fetch('key', $success);\nif (!$success) {\n    $result = expensiveQuery();\n    apcu_store('key', $result, 300);\n}",
    "good_code": "// APCu — in-process shared memory cache (same server, same PHP-FPM pool)\n// Install: pecl install apcu; extension=apcu.so in php.ini\n\n// Store & retrieve\napc_store('config:theme', 'dark', 3600);   // TTL in seconds\n$theme = apc_fetch('config:theme', $success);\nif (!$success) { /* cache miss */ }\n\n// Atomic increment — race-condition-free counters\napc_inc('page_views:home');\n\n// Clear specific key or all\napc_delete('config:theme');\napc_clear_cache();\n\n// Good for: PHP-computed config, feature flags, hot lookup tables\n// Not good for: session data, shared across multiple servers (use Redis instead)",
    "quick_fix": "Use APCu (apcu_store/apcu_fetch) for per-process in-memory caching of expensive computed values — it's faster than Redis for single-server setups with no serialisation overhead",
    "severity": "medium",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-25",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/apc_apcu",
        "html_url": "https://codeclaritylab.com/glossary/apc_apcu",
        "json_url": "https://codeclaritylab.com/glossary/apc_apcu.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[APCu — In-Process User Cache](https://codeclaritylab.com/glossary/apc_apcu) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/apc_apcu"
            }
        }
    }
}