PHP Preloading — Performance Impact

Also Known As

TL;DR

Explanation

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).

Common Misconception

Why It Matters

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.

Code Examples

; php.ini — preloading not set up:
; opcache.preload =          ; Missing
; opcache.preload_user =     ; Missing — required (non-root)

; Correct:
opcache.preload=/var/www/app/preload.php
opcache.preload_user=www-data

; preload.php should require_once all framework/library files

; php.ini — preload framework files at FPM startup
opcache.preload=/var/www/app/preload.php
opcache.preload_user=www-data

; preload.php — list files to compile and cache
<?php
$files = glob('/var/www/app/vendor/laravel/framework/src/**/*.php');
foreach ($files as $file) {
    require_once $file;
}
// ~7000 files preloaded once at startup, shared across all FPM workers

; Laravel: php artisan optimize compiles routes + config into cached files
; These are also loaded into OPcache and benefit from preloading

Tags

Related Terms

References

• https://www.php.net/manual/en/opcache.preloading.php