Production et performances
Ce que le framework coûte à l’exécution, et comment construire, régler et livrer le cache pour qu’en production seuls les appels dotés de behaviors aient un coût.
Traduit de l’anglais. La page anglaise fait référence. Lire l’original
Le framework compile une seule fois vos classes avec leurs behaviors (comportements) et stocke le résultat sous forme de fichiers PHP ordinaires. Ces fichiers sont ensuite servis comme n’importe quel autre code : OPcache les met en cache, Composer les charge, et aucun parseur, aucune réflexion ni aucun eval() ne s’exécute pendant la requête. Avec un cache chaud, une requête de production lit un fichier de métadonnées, confie les classes générées à Composer et ne paie que pour les appels réellement interceptés. Les méthodes et propriétés sans behavior ne coûtent rien.
Cette page donne les chiffres mesurés, explique d’où vient le coût et montre comment livrer le cache : préchauffage du cache au déploiement, OPcache, Composer, Docker et Kubernetes. Les options du noyau (kernel) sont décrites dans Configuration et CLI. Un résumé visuel se trouve sur la page de la fonctionnalité Performance.
Coûts mesurés
Section intitulée « Coûts mesurés »Tous les chiffres de cette page proviennent du fichier docs/performance.md de goaop/framework en amont. Ils ont été mesurés sur une seule machine : lisez-les comme des rapports entre modes. Ce sont ces rapports qui se transposent à d’autres machines.
Banc d’essai
Section intitulée « Banc d’essai »- Une petite application de boutique : environ 250 fichiers sous les chemins d’inclusion (94 classes compilées), 120 classes de bibliothèque en dehors, et 6 behavior classes (classes de comportement) avec
#[Before],#[Around],#[AfterThrowing]et des behaviors de propriété. - Une requête passe 50 commandes. Cela représente ~2 600 appels de méthode interceptés et ~950 accès à des propriétés interceptés.
- PHP 8.5.12 NTS, 4 CPU, OPcache en mémoire partagée,
opcache.jit=disable,opcache.file_update_protection=0.
La méthode complète figure plus bas, dans Reproduire les benchmarks.
Durée de requête par mode
Section intitulée « Durée de requête par mode »Les trois états du cache :
- à chaud (hot) : cache compilé présent, OPcache rempli. L’état stable d’un worker de production.
- à tiède (warm) : cache compilé présent, OPcache vide. Un PHP-FPM tout juste démarré ou un nouveau pod.
- à froid (cold) : rien n’est encore en cache. La première requête compile chaque classe qu’elle charge.
| Mode | à chaud | à tiède | Pic mémoire (à chaud) |
|---|---|---|---|
debug => false + PREBUILT_CACHE |
5,4 ms | 59 ms | 1,3 Mo |
debug => false |
5,5 ms | 62 ms | 1,3 Mo |
debug => true |
13,0 ms | 63 ms | 2,2 Mo |
| Même application sans le framework (les behaviors ne s’exécutent pas) | 2,1 ms | 36 ms | 0,7 Mo |
- ~3 500 interceptions avec de vrais corps de behaviors (journalisation, lectures de cache, chronomètres) ajoutent ~3,3 ms à la requête. Le démarrage du noyau en représente ~0,15 ms.
- Un appel intercepté coûte environ un tiers de microseconde, et chaque behavior supplémentaire sur cet appel ~70 ns.
- Le cache complet se construit en moins d’une demi-seconde avec
cache:warmup:aop. Une application de 2 000 fichiers prend 1,1 s avec 4 workers. - Les conteneurs démarrent à chaud. Avec un file cache OPcache amorcé, la première requête d’un nouveau PHP-FPM prend 19 ms au lieu de 71 ms. Avec le préchargement en plus, elle prend 10 ms, autant que l’application seule sans le framework (9 ms).
Coût par appel
Section intitulée « Coût par appel »Ces chiffres utilisent des behaviors vides : ils ne mesurent donc que le travail propre du framework, c’est-à-dire le call context (contexte d’appel), la chaîne d’intercepteurs et l’appel de la méthode d’origine.
| Appel | Surcoût par appel |
|---|---|
| Méthode ou propriété sans behavior dans une classe compilée | 0 |
Méthode avec un #[Before] ou un #[Around] |
~0,33 µs |
Méthode avec trois #[Around] |
~0,48 µs |
Méthode statique avec un #[Around] |
~0,34 µs |
Lecture de propriété avec un #[Around] |
~0,22 µs |
Écriture de propriété avec un #[Around] |
~0,26 µs |
Un million d’appels interceptés coûtent environ un tiers de seconde. Une requête typique comptant quelques centaines d’interceptions paie une fraction de milliseconde.
Processus CLI
Section intitulée « Processus CLI »Chaque processus CLI démarre avec un OPcache vide. Un opcache.file_cache amorcé permet aux commandes de courte durée de démarrer presque aussi vite qu’une requête web à chaud.
| Durée du script par processus | OPcache désactivé | OPcache activé (mémoire seule) | opcache.file_cache, amorcé |
|---|---|---|---|
PREBUILT_CACHE |
33 ms | 69 ms | 21 ms |
debug => false |
30 ms | 69 ms | 22 ms |
| Sans le framework | 19 ms | 34 ms | 10 ms |
Ce qui coûte quoi
Section intitulée « Ce qui coûte quoi »Membres sans behavior
Section intitulée « Membres sans behavior »Le proxy ne redéfinit que les membres qui ont des behaviors. Toutes les autres méthodes et propriétés sont votre code d’origine et s’exécutent à pleine vitesse : le surcoût est de 0. Les classes qu’aucune matching rule (règle de correspondance) ne sélectionne ne sont pas compilées du tout.
Appels interceptés et behaviors empilés
Section intitulée « Appels interceptés et behaviors empilés »Chaque méthode interceptée déclare un call context statique :
static $__joinPoint = InterceptorInjector::forMethod(...)Le call context et sa liste d’intercepteurs sont construits au premier appel. Chaque appel suivant se réduit à un unique $__joinPoint->__invoke($this, [$args]). Cette liste contient des first-class callables qui pointent directement vers les méthodes de vos behavior classes : pas de recherche de behaviors, pas de réflexion, pas de __call().
Le premier behavior sur une méthode coûte ~0,33 µs. Chaque behavior supplémentaire ajoute ~70 ns, si bien que trois behaviors #[Around] coûtent ~0,48 µs. Une méthode statique avec un #[Around] coûte ~0,34 µs.
La réflexion destinée aux behaviors (getMethod(), getField()) n’est créée que lorsqu’un behavior la demande.
Accès aux propriétés
Section intitulée « Accès aux propriétés »L’interception de propriétés se compile en hooks natifs get et set de PHP 8.4 sur le proxy. Il n’y a ni magie __get() ou __set(), ni réflexion à chaque accès. Une lecture de propriété avec un #[Around] coûte ~0,22 µs, une écriture ~0,26 µs.
Démarrage du noyau
Section intitulée « Démarrage du noyau »Le démarrage du noyau prend ~0,15 ms dans le benchmark. Les services du framework, les transformateurs et vos behavior classes sont enregistrés comme des factories, à raison d’une écriture de tableau chacun. Rien n’est autochargé, réfléchi ni instancié au démarrage : une requête à chaud ne charge donc jamais le parseur, la grammaire des matching rules, le moteur de correspondance des behaviors ni les transformateurs.
- L’index du cache (
CachePathManager) est le seul service construit dansinit(), car l’autoloader lit immédiatement la class map. - Les behavior classes sont instanciées au premier appel de l’un de leurs behaviors, sous forme d’objets paresseux natifs (native lazy objects) de PHP 8.4. La compile step (étape de compilation) et le préchauffage du cache n’instancient jamais une behavior class ; ils se contentent de la lire.
- La production n’active aucun listener d’enregistrement. Le mode debug surveille les modifications des fichiers des behavior classes grâce à un listener qui résout les fichiers via Composer sans charger les classes.
- La table d’analyse de la grammaire des matching rules est du PHP généré, et les règles ne sont analysées qu’à leur première utilisation.
Démarrages à froid et à tiède
Section intitulée « Démarrages à froid et à tiède »Une requête à tiède (cache compilé présent, OPcache vide) prend 59 ms avec PREBUILT_CACHE, contre 36 ms pour l’application seule. Vous la raccourcissez avec un opcache.file_cache amorcé et le préchargement, voir Docker et Kubernetes.
Une requête à froid compile chaque classe qu’elle charge. Avec un cache construit au déploiement et PREBUILT_CACHE, une requête de production ne compile jamais.
Temps de compilation
Section intitulée « Temps de compilation »La compilation a lieu une seule fois, au déploiement.
- Le cache de l’application du benchmark se construit en moins d’une demi-seconde.
- Une application de 2 047 fichiers a demandé 2,2 s avec un worker et 1,1 s avec 4 workers sur 4 CPU.
- Chaque fichier analysé gardé en mémoire pendant la compilation occupe ~0,2 Mo. L’option de noyau
parsedFilesLimit(par défaut100) limite leur nombre.
Ce qui garde la compilation rapide :
- Le chemin d’un succès de cache n’analyse rien. Un enregistrement à jour est servi comme contenu en cache avant même qu’un transformateur existe. Le stream filter et la chaîne de transformateurs ne sont construits qu’au premier échec de cache.
- Toutes les règles de réécriture partagent un seul parcours de l’arbre syntaxique. Une règle dont le marqueur source n’apparaît pas dans le fichier est ignorée, et un fichier sans aucune règle applicable n’est pas parcouru du tout. C’est le cas de la plupart des fichiers.
- Ce sont vos behavior classes qui mettent la machinerie en marche. Les expressions
newne sont réécrites que tant qu’une règleinitialization(...)est enregistrée. Les proxies de fonctions n’existent que pour les règles de fonctions. - La vérification des behavior classes, qui réfléchit chaque ancêtre, ne s’exécute que pour les classes qui ont des behaviors.
- Les behaviors d’une behavior class sont mis en cache sous forme de fichier PHP ordinaire composé d’expressions de constructeur statiques, environ deux fois plus rapide à charger qu’un
unserialize(). - Les proxies sont construits comme des arbres syntaxiques et imprimés une seule fois (−43 % de temps de compilation). Le trait généré est produit par des modifications de tokens qui conservent vos numéros de ligne pour Xdebug.
Ce que fait une requête de production
Section intitulée « Ce que fait une requête de production »| Étape | debug => false (+ PREBUILT_CACHE) |
debug => true |
|---|---|---|
init() du noyau |
options, conteneur, factories de services (rien n’est instancié) | la même chose, plus la surveillance des modifications du noyau et des fichiers des behavior classes |
_include.cache (class map, ensemble des fichiers ignorés) |
un seul include, servi depuis OPcache, aucun stat() du répertoire de cache |
la même chose |
| Classe compilée | class map de Composer → fichier en cache, depuis OPcache | contrôle de fraîcheur, puis le stream filter, pour que les points d’arrêt Xdebug et les constantes magiques pointent vers vos fichiers d’origine |
| Classe non transformée sous les chemins d’inclusion | ensemble des fichiers ignorés → le fichier d’origine, depuis OPcache | contrôle de fraîcheur → le fichier d’origine, depuis OPcache |
| Parseur, transformateurs, stream filter | jamais chargés | stream filter enregistré, aucun transformateur construit |
| Un fichier source modifié | le cache construit au déploiement est servi tel quel | recompilé à la requête suivante |
Appels au système de fichiers d’une requête à chaud, comptés par le profileur :
| Appel | PREBUILT_CACHE |
debug => false |
debug => true |
Sans le framework |
|---|---|---|---|---|
filemtime / filesize |
0 | 0 | 323 / 239 | 0 |
file_get_contents |
0 | 0 | 94 | 0 |
file_exists (Composer PSR-4) |
307 | 307 | 412 | 357 |
Une requête de production ne vérifie aucun fichier source. Elle fait même moins de recherches Composer que l’application seule, car les classes générées proviennent directement de la class map. Une class map Composer optimisée supprime les recherches restantes, voir Autoloader Composer.
Deux autres détails de l’index d’exécution :
_include.cachene contient que ce dont une requête a besoin : la class map, l’ensemble des fichiers ignorés et l’include map. Les enregistrements de build complets se trouvent dans_transformation.cache, que la production ne lit jamais.- Les deux fichiers de métadonnées sont des tableaux produits par
var_export(), avec des chemins relatifs à__DIR__. OPcache les garde immuables en mémoire partagée : les inclure ne copie rien, et le cache reste valide quand le répertoire de l’application est déplacé.
Le mode debug est fait pour le développement. Ses requêtes à chaud prennent ~13 ms dans le benchmark, contre ~5,5 ms en production. Le mode debug inclut toujours un fichier non transformé et à jour par son chemin d’origine, si bien qu’OPcache le met en cache (~38 µs → ~10 µs par fichier, requêtes debug 27–40 % plus rapides).
Liste de contrôle pour la production
Section intitulée « Liste de contrôle pour la production »-
Définissez
'debug' => falseet'features' => Features::PREBUILT_CACHE. -
Construisez le cache au déploiement ou au build de l’image avec
cache:warmup:aop. -
Gardez
includePathsrestreint : votresrc/, pasvendor/. -
Enregistrez les behavior classes avec
addLazyService(). -
Installez les dépendances avec
composer install --no-dev --classmap-authoritative. -
Faites tourner OPcache avec
opcache.validate_timestamps=0et assez de mémoire et d’emplacements de fichiers pour les fichiers générés. -
Dans les conteneurs, intégrez le cache à l’image, et ajoutez un
opcache.file_cacheamorcé ou le préchargement.
Le noyau de production :
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::PREBUILT_CACHE,]);Construire le cache au déploiement
Section intitulée « Construire le cache au déploiement »rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc)Partez d’un répertoire vide, pour que le cache contienne exactement la release courante. L’argument est le fichier qui initialise votre noyau : le contrôleur frontal ou un fichier de bootstrap. La commande l’exécute, si bien que le noyau démarre avec les mêmes options qu’en production.
La commande :
- compile chaque fichier sous
includePaths(moinsexcludePaths) et écrit les fichiers générés, les proxies, les caches des behavior classes et les deux fichiers de métadonnées ; - signale sur stderr chaque fichier qui ne peut pas être compilé et se termine avec un code non nul, pour qu’un script de déploiement ou un
docker builds’arrête là au lieu de livrer un cache incomplet.
Reconstruisez le cache dès que le code, les behavior classes, les options du noyau ou composer.lock changent. En pratique, cela signifie à chaque déploiement. Le mode debug n’a besoin d’aucune reconstruction : il recompile de lui-même les classes, les behavior classes et les fichiers du noyau modifiés.
La signature complète de la commande :
cache:warmup:aop [<loader>] [--fail-fast] [--workers=N] [--cached-files=N] [--cache-dir=DIR] [--preload[=FILE]]Dans une application qui a déjà initialisé son noyau (la console d’une intégration de framework), l’argument loader est omis et la commande utilise le noyau du processus. Voir Intégrations.
--workers=N compile dans N processus workers, les plus gros fichiers d’abord. La valeur par défaut est 1, qui compile dans le processus de la commande. Utilisez le nombre de CPU. Le coordinateur écrit les métadonnées une seule fois, et chaque processus garde en mémoire un nombre borné d’arbres syntaxiques.
--cached-files=N fixe cette borne par processus. Elle vaut par défaut l’option de noyau parsedFilesLimit (100). Plus de fichiers en cache signifie moins de réanalyses ; moins de fichiers, moins de mémoire. Ajoutez -v pour lister chaque fichier au lieu de la barre de progression.
Construire à côté de la release en cours
Section intitulée « Construire à côté de la release en cours »--cache-dir=DIR construit le cache dans un autre répertoire, à partir de zéro, pendant que le noyau continue de servir depuis le sien. Utilisez-le pour préparer le cache de la release suivante à côté de celle qui tourne, puis basculez de façon atomique, par exemple en échangeant un lien symbolique.
Un cache construit ainsi est complet et indépendant de son emplacement, y compris quand un noyau de production le construit alors que son propre cache est chaud. Le compilateur lit toujours les sources d’origine des classes qu’il réfléchit, jamais les fichiers générés que Composer sert en production.
Lancée sur un répertoire existant, la commande recompile chaque fichier dont la source a changé (taille ou date de modification) et conserve les autres. C’est vrai aussi avec PREBUILT_CACHE : seules les requêtes font confiance au cache tel quel, pas la commande de préchauffage.
PREBUILT_CACHE et systèmes de fichiers en lecture seule
Section intitulée « PREBUILT_CACHE et systèmes de fichiers en lecture seule »Features::PREBUILT_CACHE fait que les requêtes se fient entièrement au cache construit au déploiement. Il supprime :
- les sondes du répertoire de cache et de ses droits d’écriture ;
- les comparaisons de
filemtimedes sources ; - les vérifications des ressources surveillées ;
- les contrôles de fraîcheur des caches des behavior classes.
Une requête ne compile jamais et n’écrit jamais dans le répertoire de cache : elle fonctionne donc sur des systèmes de fichiers en lecture seule. Le cache doit par conséquent être complet. Une classe ou un fichier inclus sous les chemins d’inclusion dont le cache n’a aucun enregistrement, ou un enregistrement dont le fichier en cache a disparu, fait échouer la requête avec une WeavingException avant toute compilation. Cela vaut aussi pour un fichier ajouté après le build, même s’il n’a besoin d’aucune compilation.
Les fichiers que le compilateur ne prend jamais en charge sont chargés tels quels : fichiers en dehors des chemins d’inclusion, fichiers exclus, et fichiers non .php comme un template inclus.
Chaque fichier de cache est écrit dans un fichier temporaire unique, renommé à sa place puis invalidé dans OPcache. Les requêtes concurrentes ne voient jamais un fichier à moitié écrit, aucun verrou n’est nécessaire, et les écritures concurrentes des métadonnées fusionnent leurs enregistrements.
Autoloader Composer
Section intitulée « Autoloader Composer »Les classes qui ne sont pas compilées sont trouvées par Composer comme d’habitude. Avec une class map optimisée, chaque recherche est un accès à un tableau au lieu d’un file_exists(), et la class map des classes générées y est fusionnée avec addClassMap(). Classes générées et classes non transformées sont alors servies de la même façon.
Requête à chaud du benchmark :
| Autoloader | PREBUILT_CACHE |
debug => false |
Sans le framework |
|---|---|---|---|
PSR-4 (composer install) |
5,5 ms | 6,7 ms | 2,3 ms |
--optimize-autoloader (-o) |
5,2 ms | 5,0 ms | 1,6 ms |
--classmap-authoritative (-a) |
4,8 ms | 4,6 ms | 1,9 ms |
Avec --classmap-authoritative, Composer ne cherche jamais une classe en dehors de la class map. Lancez dump-autoload après toute génération de code et avant le préchauffage.
Réglage d’OPcache
Section intitulée « Réglage d’OPcache »Chaque classe compilée donne deux fichiers en cache : son corps d’origine sous forme de trait, et le proxy. Chaque behavior class reçoit son propre fichier de cache. Laissez de la place à OPcache pour eux.
| Réglage | Valeur en production | Pourquoi |
|---|---|---|
opcache.enable |
1 |
Le code généré est du PHP ordinaire, mis en cache comme le reste de l’application. |
opcache.memory_consumption |
128–256 (Mo) |
Vérifiez opcache_get_status()['memory_usage'] sous charge. |
opcache.interned_strings_buffer |
16–32 (Mo) |
Les proxies et les traits générés partagent les noms de classes et de méthodes. |
opcache.max_accelerated_files |
≥ 2 × les fichiers PHP de l’application et de vendor/ |
Chaque classe compilée ajoute un fichier. |
opcache.validate_timestamps |
0 |
Releases et conteneurs immuables : aucun stat par include. Rechargez PHP-FPM après un déploiement. |
opcache.file_update_protection |
0 |
Le framework écrit chaque fichier de cache de façon atomique : OPcache peut donc mettre en cache les fichiers fraîchement générés immédiatement, au lieu d’attendre 2 secondes (la valeur par défaut). |
opcache.file_cache |
un répertoire | Un cache de second niveau sur disque : un nouveau master PHP-FPM ou un nouveau processus CLI charge les scripts compilés au lieu de les compiler. Amorcez-le au build. |
opcache.preload |
facultatif | Lie les classes générées une seule fois au démarrage du serveur, voir Préchargement. |
realpath_cache_size / realpath_cache_ttl |
4096K / 600 |
Avec validate_timestamps=1 : moins de résolutions de chemin par include. |
Le code généré est du PHP ordinaire, compilé par le JIT comme le reste de l’application. Une requête web typique passe son temps dans de nombreux appels courts, où le JIT apporte peu : mesurez avant de l’activer.
Préchargement
Section intitulée « Préchargement »Les fichiers générés sont des déclarations de classes ordinaires : un cache préconstruit peut donc être préchargé. --preload écrit le script opcache.preload du cache qu’il construit : _preload.php dans le répertoire de cache, ou le fichier indiqué par --preload=FILE.
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc) --preloadopcache.preload=/app/var/cache/aop/_preload.phpopcache.preload_user=www-dataLe --preload sans valeur doit venir après l’argument loader, sinon il prend le loader comme valeur.
Au démarrage de PHP-FPM, le script charge l’autoloader de Composer, lui transmet la class map des classes générées et lie dans OPcache chaque classe compilée, son proxy et chaque classe non transformée connue du cache.
- Les autoloads
filesde Composer (fonctions utilitaires, amorçages de polyfills) ne sont pas préchargés. Les requêtes les incluent comme avant. - Le script ne contient aucun chemin absolu. Tout est localisé via
__DIR__, comme pour les fichiers de métadonnées : un cache déplacé avec l’application reste valide. - Il liste les classes du cache exact avec lequel il a été construit. Reconstruisez-le avec le cache.
- Une classe qui ne peut pas être liée pendant le préchargement (une dépendance facultative manque) est écrite dans le journal d’erreurs et laissée à l’autoloader de la requête.
- Une classe dotée d’un behavior sur son initialisation statique est elle aussi laissée à l’autoloader : le behavior a besoin du noyau, c’est donc la requête qui la charge.
Le noyau est toujours initialisé à chaque requête ; l’autoloader n’a simplement jamais à charger les classes préchargées. Dans le benchmark, le préchargement a fait passer les fichiers inclus par requête de 517 à 174, la requête à chaud de 5,2 ms à 4,9 ms, et la première requête après un démarrage du serveur de 71 ms à 24 ms (10 ms avec, en plus, un file cache amorcé).
Les classes préchargées ne changent qu’au redémarrage de PHP-FPM, ce qui est de toute façon la manière dont les conteneurs sont déployés. Rien n’est préchargé en CLI, sauf si opcache.enable_cli=1 est défini.
Docker et Kubernetes
Section intitulée « Docker et Kubernetes »Intégrez le cache du framework à l’image. Chaque conteneur démarre alors avec un cache complet en lecture seule, chaque réplique sert exactement le même code généré, et aucun pod ne compile jamais. La démo de boutique fournit cette configuration sous forme d’image fonctionnelle.
Dockerfile
Section intitulée « Dockerfile »FROM php:8.5-fpm
# OPcache is part of PHP 8.5, no docker-php-ext-install neededCOPY docker/opcache.ini /usr/local/etc/php/conf.d/opcache.iniCOPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /appCOPY composer.json composer.lock ./RUN composer install --no-dev --no-scripts --no-autoloader --prefer-distCOPY . .RUN composer dump-autoload --no-dev --classmap-authoritative
# 1. The framework's cache: generated classes, proxies, behavior caches, metadata, owned by the user that serves it# (cache files get the `cacheFileMode` kernel option, by default 0770 minus the umask)RUN rm -rf var/cache/aop \ && php vendor/bin/aspect cache:warmup:aop public/index.php --workers="$(nproc)" --preload \ && chown -R www-data:www-data var/cache/aop \ && chmod -R a-w var/cache/aop
# 2. The OPcache file cache: a new PHP-FPM master loads compiled scripts instead of compiling them.# Built in the final image, as the file cache belongs to this PHP build and these paths.RUN mkdir -p /var/cache/opcache \ && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=/var/cache/opcache \ vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php \ && chown -R www-data /var/cache/opcache
USER www-datacache:warmup:opcache compile ce que l’application charge : le cache du framework (fichiers générés, proxies, caches des behavior classes et métadonnées), la class map et les fichiers autochargés de Composer, les sources sous les chemins d’inclusion qui ne sont pas compilées, le fichier loader et les points d’entrée indiqués avec --entry.
- Les scripts compilés ne sont écrits sur disque que par un processus démarré avec
opcache.enable_cli=1,opcache.file_cache_only=1etopcache.file_cache=DIR. Ces réglages ne peuvent pas être définis à l’exécution. La commande les vérifie, ainsi que le fait que--file-cache=DIRsoit bien le répertoire configuré, et affiche sinon la commande exacte à lancer. - Le cache du framework, le loader et les points d’entrée doivent compiler, sinon la commande échoue. Un fichier de la class map Composer qui ne compile pas (un stub de test d’un paquet vendor écrit pour un PHP plus récent) est listé et ignoré ; PHP journalise l’erreur de compilation.
- Lancez-la après
cache:warmup:aop, dans l’image finale, avec le binaire PHP qui sert les requêtes. Le file cache est indexé par le build de PHP et par les chemins absolus des fichiers.
opcache.ini
Section intitulée « opcache.ini »opcache.enable=1opcache.memory_consumption=192opcache.interned_strings_buffer=32opcache.max_accelerated_files=50000opcache.validate_timestamps=0opcache.file_cache=/var/cache/opcacheopcache.file_cache_consistency_checks=0; PHP 8.5: the primed file cache is only read at runtime, also on a read-only root file systemopcache.file_cache_read_only=1; required on PHP 8.5.11 / 8.5.12, see "JIT"opcache.jit=disable; optional, see "Preloading" (written by cache:warmup:aop --preload); opcache.preload=/app/var/cache/aop/_preload.php; opcache.preload_user=www-dataLe noyau de l’image est le noyau de production de la liste de contrôle : debug => false, includePaths limité à src/, et Features::PREBUILT_CACHE.
Dans le benchmark, cette configuration sert la première requête d’un serveur neuf en 19 ms avec le file cache, et en 10 ms avec le file cache plus le préchargement, contre 71 ms sans l’un ni l’autre. Les pods sont rapides dès leur première requête.
Kubernetes
Section intitulée « Kubernetes »- Système de fichiers racine en lecture seule (
readOnlyRootFilesystem: true).PREBUILT_CACHElit le cache intégré à l’image et n’écrit rien à l’exécution. - Une image, un cache. Gardez le cache dans l’image plutôt que sur un volume partagé, pour que chaque release serve exactement le code à partir duquel elle a été construite.
- Les rolling updates ne demandent rien de particulier. Les nouveaux pods apportent leur propre cache, les anciens gardent le leur.
- Quand l’image ne peut pas contenir le cache, lancez
cache:warmup:aopdans un init container qui écrit dans un volumeemptyDirmonté sur le chemin de cache du conteneur applicatif. Vous conservez ainsiPREBUILT_CACHE, et le pod devient prêt avec un cache complet. - Les conteneurs CLI (consommateurs de files de messages, tâches cron) utilisent la même image et le même cache. Activez
opcache.enable_cli=1avec leopcache.file_cacheamorcé, voir Processus CLI.
Workers de longue durée
Section intitulée « Workers de longue durée »Les workers de longue durée (RoadRunner, mode worker de FrankenPHP, Swoole, ReactPHP) démarrent le noyau une fois par worker. Les call contexts restent initialisés d’une requête à l’autre.
Écrire des behaviors rapides
Section intitulée « Écrire des behaviors rapides »- Ciblez précisément. Seuls les membres sélectionnés sont interceptés et seules les classes sélectionnées sont compilées : une règle précise est une règle rapide.
execution(public App\Service\*->*(*))sélectionne aussi les constructeurs. Ajoutez&& !execution(**->__construct(*))si vous n’en avez pas besoin. - Préférez les règles de méthode à
initialization(...). Tant qu’une règleinitializationest enregistrée, chaquenewdes fichiers générés passe par le transformateur. Une classe sans behavior d’initialisation (et dotée d’un constructeur public) est toujours créée par unnewnatif, qui coûte environ 130 ns de plus qu’un simplenew. Une classe avec des behaviors d’initialisation passe par le call context complet. - Enregistrez les behavior classes en différé avec
addLazyService(). La behavior class et ses dépendances sont créées au premier appel d’un behavior, et non à chaque requête. - Gardez des behaviors légers.
getMethod()etgetField()créent un objet de réflexion à la première utilisation, par call context. Dérivez-en une fois les attributs ou les noms et conservez-les dans la behavior class, indexés parclass::method. - Formatez les call contexts à la demande.
(string) $invocationconstruit une chaîne à chaque appel. Ne l’utilisez que pour des messages réellement écrits. - Includes natifs.
Features::INTERCEPT_INCLUDESfait passer lesinclude/requiredes fichiers générés par le compilateur, pour du code legacy qui n’est pas chargé par Composer. Avec cette option, en production, unincluded’un fichier connu du cache est servi par son chemin d’origine ou par son chemin en cache, sans le stream filter (~250 µs → ~11 µs par include).
Une behavior class enregistrée en différé :
use Go\Core\AspectContainer;use Go\Core\AspectKernel;use Psr\Log\LoggerInterface;
class ApplicationAspectKernel extends AspectKernel{ protected function configureAop(AspectContainer $container): void { // Runs when one of its behaviors first runs, after the application container is attached $container->addLazyService( MonitorAspect::class, static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)), ); }}L’écriture des behaviors et des matching rules est traitée dans Behaviors et matching rules.
Dépannage
Section intitulée « Dépannage »Préchauffage et cache préconstruit
Section intitulée « Préchauffage et cache préconstruit »| Message ou symptôme | Signification et marche à suivre |
|---|---|
cache:warmup:aop écrit des erreurs sur stderr et se termine avec un code non nul |
Un fichier ne peut pas être compilé. Le déploiement ou le docker build s’arrête pour qu’un cache incomplet ne soit jamais livré. Corrigez le fichier et relancez le préchauffage. |
WeavingException : ... is missing from the prebuilt AOP cache in ... |
Avec PREBUILT_CACHE, une classe ou un fichier inclus sous les chemins d’inclusion n’a aucun enregistrement dans le cache, ou son fichier en cache a disparu. Reconstruisez le cache avec cache:warmup:aop. |
cache:warmup:opcache affiche une commande au lieu d’amorcer le cache |
Le processus n’a pas été démarré avec -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR, ou --file-cache désigne un autre répertoire. Lancez la commande affichée. |
Erreurs de préchargement
Section intitulée « Erreurs de préchargement »PHP signale les problèmes de préchargement une seule fois, au démarrage du master PHP-FPM (ou de php -S), dans son journal d’erreurs.
| Message | Signification et marche à suivre |
|---|---|
Fatal Error "opcache.preload" requires "opcache.preload_user" when running under uid 0 |
Le master tourne en root. Définissez opcache.preload_user sur l’utilisateur sous lequel tournent les workers (www-data). |
Failed opening required '.../_preload.php' |
Le script est absent : le cache a été construit sans --preload, ou opcache.preload pointe vers un autre répertoire de cache. Reconstruisez avec cache:warmup:aop --preload. |
Go! AOP preload: <class> is left to the autoloader: ... |
Le script n’a pas pu charger une classe du cache, le plus souvent parce qu’une dépendance facultative n’est pas installée (une image --no-dev). Sans gravité : la classe n’est pas préchargée, et une requête qui en a besoin l’autocharge comme d’habitude. |
Can't preload unlinked class <class>: Unknown parent/trait/interface <name> in <file> |
OPcache n’a pas pu lier une classe d’un fichier inclus par le préchargement, pour la même raison. Ce message accompagne la ligne précédente pour une classe du cache. Sans gravité : la classe n’est simplement pas préchargée. |
Can't preload unlinked class class@anonymous: Unknown trait ... dans un fichier utilitaire d’un paquet vendor |
Une classe anonyme d’un autoload files de Composer, par exemple Illuminate/Reflection/helpers.php de Laravel. Le script du cache laisse ces fichiers de côté ; l’avertissement vient d’un autre script qui charge vendor/autoload.php avant lui. Chargez d’abord le script du cache : Composer renvoie alors son loader sans inclure à nouveau les fichiers. |
Reproduire les benchmarks
Section intitulée « Reproduire les benchmarks »L’application, les scripts de benchmark et l’image Docker se trouvent dans goaop/shop-demo. Un seul script reproduit tous les tableaux de cette page :
bash bench/run-all.shComment les chiffres ont été mesurés
Section intitulée « Comment les chiffres ont été mesurés »- Application : ~45 classes écrites à la main (domaine, repositories, services, contrôleurs, infrastructure en mémoire), 40 modules générés (service et repository compilés ; DTO, validateur et événement non compilés) et 120 classes de bibliothèque en dehors des chemins d’inclusion.
- Behavior classes : journalisation (
#[Before]sur un attribut), cache et transactions (#[Around]sur des attributs), monitoring (#[Around]sur les repositories,#[AfterThrowing]sur les services), audit des stocks (#[Around]sur une propriété), sécurité (#[Before]sur les services des modules). - Référence : le même code sans le noyau. Ses behaviors ne s’exécutent pas.
- Environnement d’exécution : PHP 8.5.12 NTS, 4 CPU, OPcache avec
opcache.jit=disableetopcache.file_update_protection=0. - Requêtes web : le serveur web intégré (
php -S, un worker, mémoire partagée d’OPcache conservée entre les requêtes). À tiède, c’est la première requête d’un serveur fraîchement démarré (7 échantillons) ; à chaud, la médiane de 350 requêtes. Les durées sont mesurées dans le script avechrtime(). - Profils : exécutions Xdebug 3.5 en
xdebug.mode=profilede chaque mode et de chaque état, utilisées pour le nombre d’appels et la répartition du temps. Les durées proviennent d’exécutions sans Xdebug.
Ce sont les rapports entre les modes qui se transposent à d’autres machines.
© 2026 Alexander Lisachenko
