{
    "slug": "php_preloading",
    "term": "PHP Preloading (opcache.preload)",
    "category": "php",
    "difficulty": "advanced",
    "short": "Loading PHP files into shared memory at server start so every worker process gets pre-compiled bytecode with zero per-request filesystem overhead.",
    "long": "PHP 7.4 introduced preloading via opcache.preload — a php.ini directive pointing to a bootstrap script that calls opcache_compile_file() on framework and application files. At PHP-FPM startup these files are compiled to bytecode and mapped into shared memory, available to all worker processes with no per-request file stat or compilation cost. Frameworks like Symfony and Laravel ship preload scripts. Gains are most noticeable for large frameworks (5–10% throughput). Caveat: preloaded files cannot be updated without restarting PHP-FPM; always disable preloading in development environments.",
    "aliases": [
        "PHP preload",
        "opcache.preload",
        "PHP 7.4 preloading"
    ],
    "tags": [
        "php",
        "php7-4",
        "performance",
        "opcache"
    ],
    "misconception": "PHP preloading always improves application performance. Preloading loads specified files into shared memory at server startup — if the preloaded files change (during deployment), the server must be restarted to pick up the new code, otherwise the old preloaded version continues to run.",
    "why_it_matters": "Preloading compiles PHP files into shared memory at FPM startup — those files skip parsing and compilation on every request, reducing per-request CPU overhead for large framework codebases.",
    "common_mistakes": [
        "Preloading files that change frequently — FPM must restart for changes to take effect.",
        "Not setting opcache.preload_user — FPM won't preload as root by default.",
        "Preloading the entire vendor directory — classes that are rarely used waste shared memory.",
        "Not measuring the impact — preloading adds startup time and memory; benchmark before committing."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "opcache",
        "opcode_caching",
        "php_fpm",
        "php_jit"
    ],
    "prerequisites": [
        "opcache",
        "php_fpm",
        "php_compilation_pipeline"
    ],
    "refs": [
        "https://www.php.net/manual/en/opcache.preloading.php"
    ],
    "bad_code": "; php.ini — preloading not configured:\n; opcache.preload =              ; Not set — no preloading\n; opcache.preload_user =         ; Required — must be non-root\n\n; Correct:\nopcache.preload = /var/www/app/preload.php\nopcache.preload_user = www-data",
    "good_code": "; php.ini — preload at FPM startup (PHP 7.4+)\nopcache.preload      = /var/www/app/preload.php\nopcache.preload_user = www-data\n\n// preload.php — compile key files on startup:\n<?php\nforeach (glob('/var/www/app/src/**/*.php') as \\$file) {\n    opcache_compile_file(\\$file);\n}\n\n; Laravel: php artisan optimize\n; Symfony: php bin/console cache:warmup\n\n; Verify:\n$ php -r \"print_r(opcache_get_status()['scripts']);\"\n\n; Biggest win: eliminates per-request parsing of framework files",
    "quick_fix": "Create a preload.php that includes your most-used framework files, set opcache.preload=/path/to/preload.php and opcache.preload_user=www-data in php.ini",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/php_preloading",
        "html_url": "https://codeclaritylab.com/glossary/php_preloading",
        "json_url": "https://codeclaritylab.com/glossary/php_preloading.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": "[PHP Preloading (opcache.preload)](https://codeclaritylab.com/glossary/php_preloading) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/php_preloading"
            }
        }
    }
}