OPcache Preloading (PHP 7.4)
debt(d9/e3/b3/t7)
Closest to 'silent in production until users hit it' (d9). The detection_hints note automated=no and the only code_pattern is the ini directive opcache.preload. There is no tooling that flags when preloading is enabled in a dev environment or when the preload file is stale after Composer updates — both failure modes are silent until a developer notices stale code behavior or missing changes in production/dev.
Closest to 'simple parameterised fix' (e3). The quick_fix describes disabling preloading in dev (single ini change), regenerating the preload file via a Composer command, and restarting FPM. This is a small set of targeted actions within one configuration/deployment concern, not a single-line patch but not a multi-file refactor either — landing at e3.
Closest to 'localised tax' (b3). The applies_to scope is web context only (not CLI/queue), and the burden is confined to deployment and FPM restart procedures. It does not permeate application code broadly — it's a production configuration concern that affects deployment workflow but leaves the rest of the codebase unaffected.
Closest to 'serious trap (contradicts how a similar concept works elsewhere)' (t7). The misconception field directly states the trap: developers assume preloading behaves like normal PHP file loading (pick up changes on next request), but it actually loads code once at FPM start and requires a restart to reflect any changes. This contradicts the standard PHP development workflow and is a serious gotcha that can cause confusing stale-code bugs in development.
TL;DR
Explanation
Configured with opcache.preload = /path/to/preload.php in php.ini. The preload script uses opcache_compile_file() or require to load files into shared memory. All PHP-FPM workers share this preloaded code. Gains: 10–30% performance improvement for frameworks (Symfony, Laravel). Limitation: preloaded code cannot be reloaded without restarting PHP-FPM — not suitable for development. opcache.preload_user specifies the user to run the preload script as. Frameworks generate preload scripts automatically. Ideal for production only.
Common Misconception
Why It Matters
Common Mistakes
- Enabling preloading in development — must restart FPM for code changes to take effect.
- Not regenerating the preload file after Composer updates.
- Preloading too much — only framework core, not application code.
Code Examples
# Development with preloading — requires FPM restart on every change:
; opcache.preload=/var/www/vendor/autoload.php# Production php-fpm.conf:
[production]
opcache.preload=/var/www/config/preload.php
opcache.preload_user=www-data
# preload.php:
<?php
require '/var/www/vendor/autoload.php';
opcache_compile_file('/var/www/vendor/symfony/framework-bundle/FrameworkBundle.php');