Aller au contenu
Documentation

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.

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.

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

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

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.

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

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.

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.

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.

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 dans init(), 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.

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.

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éfaut 100) 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 new ne sont réécrites que tant qu’une règle initialization(...) 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.
É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.cache ne 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).

  1. Définissez 'debug' => false et 'features' => Features::PREBUILT_CACHE.

  2. Construisez le cache au déploiement ou au build de l’image avec cache:warmup:aop.

  3. Gardez includePaths restreint : votre src/, pas vendor/.

  4. Enregistrez les behavior classes avec addLazyService().

  5. Installez les dépendances avec composer install --no-dev --classmap-authoritative.

  6. Faites tourner OPcache avec opcache.validate_timestamps=0 et assez de mémoire et d’emplacements de fichiers pour les fichiers générés.

  7. Dans les conteneurs, intégrez le cache à l’image, et ajoutez un opcache.file_cache amorcé ou le préchargement.

Le noyau de production :

public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::PREBUILT_CACHE,
]);
Fenêtre de terminal
rm -rf var/cache/aop
vendor/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 (moins excludePaths) 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 build s’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.

--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 filemtime des 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.

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.

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.

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.

Fenêtre de terminal
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc) --preload
opcache.ini
opcache.preload=/app/var/cache/aop/_preload.php
opcache.preload_user=www-data

Le --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 files de 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.

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
FROM php:8.5-fpm
# OPcache is part of PHP 8.5, no docker-php-ext-install needed
COPY docker/opcache.ini /usr/local/etc/php/conf.d/opcache.ini
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --no-autoloader --prefer-dist
COPY . .
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-data

cache: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=1 et opcache.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=DIR soit 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.
docker/opcache.ini
opcache.enable=1
opcache.memory_consumption=192
opcache.interned_strings_buffer=32
opcache.max_accelerated_files=50000
opcache.validate_timestamps=0
opcache.file_cache=/var/cache/opcache
opcache.file_cache_consistency_checks=0
; PHP 8.5: the primed file cache is only read at runtime, also on a read-only root file system
opcache.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-data

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

  • Système de fichiers racine en lecture seule (readOnlyRootFilesystem: true). PREBUILT_CACHE lit 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:aop dans un init container qui écrit dans un volume emptyDir monté sur le chemin de cache du conteneur applicatif. Vous conservez ainsi PREBUILT_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=1 avec le opcache.file_cache amorcé, voir Processus CLI.

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.

  • 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ègle initialization est enregistrée, chaque new des 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 un new natif, qui coûte environ 130 ns de plus qu’un simple new. 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() et getField() 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 par class::method.
  • Formatez les call contexts à la demande. (string) $invocation construit une chaîne à chaque appel. Ne l’utilisez que pour des messages réellement écrits.
  • Includes natifs. Features::INTERCEPT_INCLUDES fait passer les include/require des fichiers générés par le compilateur, pour du code legacy qui n’est pas chargé par Composer. Avec cette option, en production, un include d’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é :

src/ApplicationAspectKernel.php
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.

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.

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.

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 :

Fenêtre de terminal
bash bench/run-all.sh
  • 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=disable et opcache.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 avec hrtime().
  • Profils : exécutions Xdebug 3.5 en xdebug.mode=profile de 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