{
    "slug": "php_preloading_perf",
    "term": "PHP Preloading — Performance Impact",
    "category": "performance",
    "difficulty": "advanced",
    "short": "Quantifying preloading gains: most benefit on large frameworks (5–15%), negligible on tiny apps — how to measure and tune opcache.preload.",
    "long": "PHP preloading (7.4+) eliminates per-request file stat, parsing, and compilation for preloaded files. Real-world benchmark data shows: Symfony applications typically gain 5–10% throughput; Laravel 3–8%; small custom apps with few classes see under 2% improvement. The gains scale with: number of class files loaded per request, disk I/O latency (SSDs reduce the baseline making gains smaller), and opcache hit rate (if opcache already caches everything, preloading has minimal additional benefit). Measure with ab or wrk before and after enabling preloading. Key php.ini settings: opcache.preload, opcache.preload_user, opcache.memory_consumption (increase if preloading fills it).",
    "aliases": [
        "PHP preload performance",
        "opcache preload",
        "preloading PHP files"
    ],
    "tags": [
        "php",
        "performance",
        "opcache",
        "php7-4"
    ],
    "misconception": "PHP preloading speeds up every request equally. Preloading eliminates file compilation overhead for preloaded classes. Requests that heavily use preloaded classes benefit most; requests using mostly non-preloaded code see little improvement.",
    "why_it_matters": "Preloading compiles framework and library files into shared memory at FPM start — those files require zero compilation per request, reducing cold-start overhead for large codebases.",
    "common_mistakes": [
        "Preloading files that change between deploys without restarting FPM — stale preloaded code runs indefinitely.",
        "Not setting opcache.preload_user to a non-root user — FPM refuses to preload as root.",
        "Preloading the entire vendor/ directory — wastes shared memory on rarely-used packages.",
        "Not measuring before and after — preloading adds startup time; verify the per-request savings justify it."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "php_preloading",
        "opcache",
        "opcode_caching",
        "profiling"
    ],
    "prerequisites": [
        "opcache",
        "php_fpm",
        "php_compilation_pipeline"
    ],
    "refs": [
        "https://www.php.net/manual/en/opcache.preloading.php"
    ],
    "bad_code": "; php.ini — preloading not set up:\n; opcache.preload =          ; Missing\n; opcache.preload_user =     ; Missing — required (non-root)\n\n; Correct:\nopcache.preload=/var/www/app/preload.php\nopcache.preload_user=www-data\n\n; preload.php should require_once all framework/library files",
    "good_code": "; php.ini — preload framework files at FPM startup\nopcache.preload=/var/www/app/preload.php\nopcache.preload_user=www-data\n\n; preload.php — list files to compile and cache\n<?php\n$files = glob('/var/www/app/vendor/laravel/framework/src/**/*.php');\nforeach ($files as $file) {\n    require_once $file;\n}\n// ~7000 files preloaded once at startup, shared across all FPM workers\n\n; Laravel: php artisan optimize compiles routes + config into cached files\n; These are also loaded into OPcache and benefit from preloading",
    "quick_fix": "Set opcache.preload=/path/to/preload.php and preload your framework's core classes — this moves the compilation cost from per-worker to server startup, reducing FPM worker memory by 5-15MB each",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/php_preloading_perf",
        "html_url": "https://codeclaritylab.com/glossary/php_preloading_perf",
        "json_url": "https://codeclaritylab.com/glossary/php_preloading_perf.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 — Performance Impact](https://codeclaritylab.com/glossary/php_preloading_perf) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/php_preloading_perf"
            }
        }
    }
}