Aller au contenu principal
Retour au blog

PHP-FPM, OPcache, Preload, Symfony : qui fait quoi ?

Une requête Symfony traverse nginx, PHP-FPM, OPcache, le preload et le kernel : le rôle de chaque couche, ce qu’elle garde, et laquelle accuser en cas de panne.

Flavien Métivier · 11 min de lecture
Sommaire · 9 parties

Le déploiement est vert. Le health check répond 200, la CI a tout validé, le tag est en production. Pourtant, un utilisateur signale l’ancien libellé d’un bouton. Vous rechargez : le nouveau libellé s’affiche. Vous rechargez encore : l’ancien revient. Une même URL sert deux versions de votre code, et personne dans l’équipe ne sait dire laquelle des couches situées entre nginx et votre contrôleur est en cause.

Ce flou est ordinaire. PHP-FPM, OPcache, le preload, l’autoloader Composer, le realpath cache et le container compilé de Symfony se superposent. Chacun a sa durée de vie, son périmètre de partage et sa méthode d’invalidation. Cet article pose la carte : ce que fait chaque couche, ce qu’elle garde en mémoire, qui la partage et comment la vider. C’est le premier d’une série de cinq ; les quatre suivants détaillent le dimensionnement de FPM, les réglages d’OPcache, le preload et le déploiement sans vieux code.

Valeurs par défaut et recommandations vérifiées le 2 novembre 2026 dans la documentation PHP (configuration OPcache, preloading, FPM, directives core), la page Performance de Symfony et la documentation Composer sur l’optimisation de l’autoloader. Vérifiez-les sur votre version avant de les appliquer.

Quel chemin suit une requête, de nginx à votre contrôleur ?

Sur un hébergement classique nginx + PHP-FPM + Symfony, une requête traverse sept couches. Trois d’entre elles vivent bien plus longtemps que la requête elle-même, et c’est là que se cachent la plupart des surprises.

  • nginx termine HTTP et transmet la requête à FPM en FastCGI, par socket Unix ou TCP. Il ne sait rien de PHP.
  • Le master PHP-FPM lit la configuration, ouvre le socket, charge le moteur et les extensions, initialise OPcache et exécute le preload. Il crée ensuite les workers par fork et les remplace quand ils meurent.
  • Un worker FPM traite une requête à la fois, puis la suivante. Il porte des structures privées, dont le realpath cache.
  • OPcache évite de relire et recompiler chaque fichier PHP : les opcodes sont stockés dans une mémoire partagée entre tous les workers issus du même master.
  • L’autoloader Composer traduit un nom de classe en chemin de fichier, par classmap ou par règles PSR-4.
  • Le realpath cache mémorise la résolution des chemins pour éviter des appels système répétés.
  • Symfony démarre le kernel, charge le container compilé, route, exécute le contrôleur, puis tout l’état applicatif est jeté : c’est le modèle share-nothing.

La règle de lecture tient en une phrase : OPcache et le preload vivent au niveau du master (partagés), le realpath cache vit au niveau du worker (privé), et les caches Symfony vivent sur disque. Trois portées différentes, donc trois façons différentes de servir un état périmé.

PHP-FPM gère des processus, il ne compile rien

PHP-FPM est un process manager. Son master ne traite aucune requête : il maintient un pool de workers selon la stratégie pm (static, dynamic ou ondemand), plafonné par pm.max_children. Quand tous les workers sont occupés, les requêtes s’empilent dans la file du socket, puis nginx finit par répondre 502 ou 504 selon que la connexion échoue ou expire. Un worker peut être recyclé après un nombre de requêtes fixé par pm.max_requests ; la documentation PHP donne 0 comme valeur par défaut, c’est-à-dire jamais.

Ce qui compte pour la suite, c’est la relation entre le master et ses workers. Les workers sont des enfants du master : ils héritent de ce qu’il a préparé au démarrage, à commencer par le segment OPcache et les classes préchargées. Si vous construisez vos images avec nginx et FPM dans des conteneurs séparés, notre article sur Docker Bake avec PHP-FPM et nginx montre une organisation qui garde ces deux rôles bien distincts. Le calcul de pm.max_children à partir de la mémoire réellement consommée fera l’objet du deuxième article de la série.

OPcache est partagé par le master, pas par le worker

OPcache stocke les scripts compilés (opcodes) dans une mémoire partagée. Chaque worker lit ce segment au lieu de recompiler : le coût de compilation est payé une fois par fichier, pas une fois par worker ni par requête. Les chaînes internées, comme les noms de classes et de méthodes, y sont aussi dédupliquées dans un tampon dédié, réglé par opcache.interned_strings_buffer.

La documentation PHP fixe les défauts suivants : opcache.memory_consumption=128 (Mo), opcache.interned_strings_buffer=8 (Mo), opcache.max_accelerated_files=10000, opcache.validate_timestamps=1 et opcache.revalidate_freq=2 (secondes). La page Performance de Symfony juge ces valeurs trop faibles pour un projet Symfony et recommande 256 Mo, 32 Mo de chaînes internées, 32 531 fichiers et validate_timestamps=0. Ce dernier réglage est décisif : PHP ne vérifie plus jamais si un fichier a changé sur disque, et seul un reset explicite fera prendre en compte un nouveau code.

Le piège le plus courant tient au fait que le CLI et FPM ne partagent pas le même OPcache. opcache.enable_cli vaut 0 par défaut, et même activé, un processus CLI a son propre segment qui disparaît avec lui. Lancer opcache_get_status() en SSH ne vous dit rien sur ce que voient vos requêtes web, et php bin/console cache:clear ne vide pas l’OPcache de FPM. La documentation Symfony le dit explicitement : avec validate_timestamps=0, il faut après chaque déploiement redémarrer FPM, appeler opcache_reset() depuis une requête web, ou passer par cachetool.

bash
# Trompeur : interroge l'OPcache du processus CLI, pas celui de FPM
php -r 'var_dump(opcache_get_status(false));'

# Interroger le vrai OPcache de FPM via son socket FastCGI (cachetool)
php cachetool.phar opcache:status --fcgi=/run/php/php-fpm.sock
php cachetool.phar opcache:reset --fcgi=/run/php/php-fpm.sock

Côté JIT, un point de vigilance : depuis PHP 8.4, le défaut de opcache.jit est disable (il était tracing auparavant), tandis que opcache.jit_buffer_size est passé de 0 à 64M. Le JIT reste donc inactif sans configuration explicite, mais pour une raison différente selon la version. Son intérêt réel pour une application web Symfony sera traité dans le troisième article.

Le preload n’est pas un cache de plus : c’est un état figé au démarrage

Selon la documentation PHP, opcache.preload désigne un script exécuté une seule fois, au démarrage du serveur. Les fonctions, classes, interfaces et traits qu’il charge deviennent disponibles pour toutes les requêtes sans include ni autoload ; les constantes, elles, ne le sont pas. Pour modifier ce qui a été préchargé, il faut redémarrer le processus PHP : même avec validate_timestamps=1, une modification d’un fichier préchargé ne sera pas vue.

  • Le preload s’exécute dans le master. Il se configure dans php.ini, de façon globale : on ne le règle pas pool par pool.
  • opcache.preload_user est requis quand le master démarre en root, car l’exécution du preload en root est refusée par défaut. Donnez-lui l’utilisateur de vos workers.
  • Symfony fournit config/preload.php via sa recette Flex. C’est ce fichier qu’il faut référencer, et non le fichier généré dans var/cache/prod qu’il inclut.
  • Depuis PHP 8.1, un cache d’héritage réduit déjà le coût de liaison des classes sans preload. Le gain du preload est donc à mesurer, pas à supposer.

Le quatrième article de la série mesurera ce gain sur une application Symfony réelle et listera les cas où il vaut mieux s’en passer.

Votre dette technique s'accumule ?

Audit complet en 10 jours. Recommandations priorisées et actionnables.

Calculer mon audit →

Autoloader Composer et realpath cache : les caches qu’on oublie

La documentation Composer décrit trois niveaux d’optimisation. -o convertit les règles PSR-4 en classmap. --classmap-authoritative va plus loin : toute classe absente de la classmap est réputée inexistante, sans recherche sur disque. --apcu-autoloader ajoute un cache APCu des résolutions. Les modes authoritative et APCu s’excluent mutuellement. Symfony recommande composer dump-autoload --no-dev --classmap-authoritative au déploiement, avec un risque à connaître : une classe générée à l’exécution, hors classmap, provoquera un « class not found » en production.

Le realpath cache est d’une autre nature : c’est une mémoire par processus, donc privée à chaque worker FPM, qui mémorise la résolution des chemins. La documentation PHP donne realpath_cache_size=4M et realpath_cache_ttl=120 secondes par défaut ; Symfony recommande 4096K et 600. La directive open_basedir le désactive. Avec un déploiement par lien symbolique (current pointant vers releases/42), deux mécanismes peuvent servir l’ancienne release après la bascule : OPcache, qui indexe par défaut les scripts sous le chemin demandé, lien symbolique compris, et ce realpath cache, propre à chaque worker, qui peut résoudre l’ancien chemin pendant toute la durée de son TTL. C’est le terrain du scénario des deux libellés, et le cœur du cinquième article.

Le cache Symfony vit sur disque, puis dans OPcache

À chaque requête, FPM exécute public/index.php, instancie le kernel, charge le container, route et appelle le contrôleur. Rien ne subsiste ensuite côté application. Ce qui évite de tout recalculer, ce sont des fichiers PHP générés dans var/cache/prod lors du warmup : container compilé, routes, métadonnées, templates Twig compilés. Ils sont inclus comme n’importe quel script, donc servis depuis OPcache.

Conséquence directe : avec validate_timestamps=0, un cache:clear suivi d’un warmup réécrit bien les fichiers, mais FPM continue d’exécuter les opcodes de l’ancien container tant qu’OPcache n’a pas été invalidé. var/cache et OPcache sont deux étages distincts, et le premier dépend du second. Les améliorations récentes du warmup sont détaillées dans notre article sur la performance de Symfony 8.2. Les pools cache.app et cache.system forment encore une couche à part : ils stockent des données applicatives, pas du code, et leur durée de vie dépend de l’adaptateur choisi.

Qu’est-ce qui survit à quoi ?

Les signaux du master FPM définissent quatre événements. USR2 déclenche un rechargement gracieux : le master se relance avec sa configuration, puis recrée ses workers. QUIT arrête proprement, TERM et INT arrêtent immédiatement. Voici ce que chaque événement conserve.

  • Fin de requête : OPcache, preload, realpath cache du worker et fichiers var/cache survivent. Le container instancié, les services et les objets disparaissent.
  • Worker recyclé (pm.max_requests atteint, ou inactivité en mode ondemand) : OPcache et preload survivent, car ils appartiennent au master. Le realpath cache du worker disparaît avec lui.
  • Rechargement FPM (USR2, souvent systemctl reload) : le master se relance, le preload est réexécuté et OPcache repart de zéro. C’est le moyen le plus simple de garantir que le nouveau code est servi.
  • Redémarrage complet : tout disparaît. Le premier trafic repaie la compilation ; prévoyez un échauffement avant de remettre le serveur dans le load balancer.
  • Fichiers remplacés sans rechargement, avec validate_timestamps=0 : rien ne change côté PHP. Les workers exécutent l’ancien code jusqu’à une invalidation explicite.

Symptôme → couche : la grille de diagnostic

Face à un incident, demandez-vous d’abord si l’état périmé est partagé (OPcache, preload), privé à un worker (realpath cache) ou sur disque (var/cache, classmap). Ce seul réflexe réduit déjà de moitié la liste des suspects. La grille ci-dessous donne la première vérification pour chaque symptôme.

  • Ancien code servi par moments → invalidation partielle : reset d’OPcache encore en attente, une seule instance réinitialisée, ou realpath cache d’un worker sur un symlink → vérifier le statut OPcache sur chaque instance, puis recharger FPM.
  • Ancien code servi partout, de façon stable → OPcache non invalidé → cachetool opcache:status sur le socket FPM, pas en CLI.
  • cache:clear sans effet en production → OPcache de FPM toujours plein de l’ancien container → reset via FPM.
  • Modification d’une classe préchargée ignorée → preload figé au démarrage du master → rechargement ou redémarrage de FPM.
  • 502 ou 504 sous charge → pool FPM saturé (pm.max_children atteint) ou requêtes trop longues → status page FPM et slowlog.
  • Mémoire qui grimpe par worker → fuite applicative ou workers jamais recyclés → pm.max_requests et mesure de la RSS.
  • Pic CPU juste après le déploiement → OPcache froid, compilation concurrente → warmup avant la mise en trafic.
  • « Class not found » après un déploiement → classmap authoritative qui ignore une classe générée → régénérer l’autoload et contrôler var/cache.
  • Lenteur applicative stable → aucune de ces couches : c’est le code, souvent la base de données. Commencez par traquer les requêtes N+1 Doctrine.

Pour fixer les idées, voici un point de départ de configuration de production qui reprend les recommandations de la documentation Symfony. Ce n’est pas un optimum universel : les bonnes valeurs se lisent dans opcache_get_status() côté FPM et dans la mémoire réellement consommée par vos workers.

bash
; php.ini de production (FPM), recommandations de la doc Symfony
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=32
opcache.max_accelerated_files=32531
; PHP ne revalide plus les fichiers : reset obligatoire à chaque déploiement
opcache.validate_timestamps=0
opcache.preload=/var/www/app/config/preload.php
; requis si le master FPM démarre en root
opcache.preload_user=www-data
realpath_cache_size=4096K
realpath_cache_ttl=600

Par où commencer cette semaine ?

Ouvrez la configuration FPM et OPcache de votre production, telle que FPM la voit et non telle que le CLI l’affiche. Notez la valeur de pm, de pm.max_children, de pm.max_requests, d’opcache.validate_timestamps et d’opcache.preload, puis comparez-les à ce que vous pensiez avoir réglé. L’écart, quand il existe, est votre premier sujet. Vérifiez ensuite que votre script de déploiement invalide OPcache via FPM, et pas seulement via la console.

Si votre application supporte un modèle à processus persistant, une autre voie existe : garder le kernel en mémoire entre les requêtes, ce que fait le worker mode de FrankenPHP. Il change la carte décrite ici, notamment pour le preload et la gestion de l’état entre requêtes. La série reste centrée sur le couple nginx et FPM, encore majoritaire en production.

Les quatre prochains articles partent chacun d’un symptôme de cette grille : dimensionner PHP-FPM, régler et surveiller OPcache, mesurer le gain réel du preload, puis déployer sans servir de vieux code. Chacun se termine par une vérification à lancer sur votre propre serveur.

Savoir quelle couche accuser demande de mesurer, et cette lecture se fait rarement à chaud, en pleine alerte. Si vous voulez un regard extérieur sur votre configuration d’exécution, sur votre chaîne de déploiement et sur le code qui tourne dessus, ce sont des axes que couvre un Bear Scan.

Cet article vous a été utile ? Partagez-le.

Portrait de Flavien Métivier, fondateur de The Bearded Bear : barbe longue, lunettes, sur fond sombre

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours

À lire ensuite

Votre dette technique s'accumule ?

Audit complet en 10 jours. Recommandations priorisées et actionnables.

Newsletter Bear Bytes

Veille Claude Code, Symfony et PHP, retours d'expérience terrain et conseils techniques, directement dans votre boîte mail.