"post-install-cmd": [
    "bin/console cache:clear --env=prod",
    "bin/console doctrine:migrations:migrate --no-interaction"
]

post-install-cmd s’exécute pendant composer install, qui dans le Dockerfile de production tourne au moment du build de l’image. Il n’y a pas de base de données disponible pendant un build Docker. La commande de migration échouait silencieusement, se connectait à rien, ou était ignorée par Doctrine faute de schéma à comparer. Dans tous les cas, elle ne migrait rien.

C’est une violation nette du Facteur XII : les processus d’administration — migrations, scripts ponctuels, commandes console — doivent s’exécuter dans le même environnement que l’application, contre les vraies données de production. Les faire tourner au build inverse la relation. L’image ne devrait pas savoir qu’il y a une base de données. La base devrait être là quand l’image en a besoin.

Le déplacement vers l’entrypoint

La commande de migration a quitté composer.json pour docker-entrypoint.sh. Le changement semble petit dans un diff. Les implications ne le sont pas.

L’entrypoint s’exécute quand le container démarre, pas quand l’image est construite. La base de données est accessible. L’entrypoint l’attend — jusqu’à 60 secondes, une tentative par seconde — avant de faire quoi que ce soit :

ATTEMPTS_LEFT_TO_REACH_DATABASE=60
until [ $ATTEMPTS_LEFT_TO_REACH_DATABASE -eq 0 ] || \
  DATABASE_ERROR=$(php bin/console dbal:run-sql -q "SELECT 1" 2>&1); do
    sleep 1
    ATTEMPTS_LEFT_TO_REACH_DATABASE=$((ATTEMPTS_LEFT_TO_REACH_DATABASE - 1))
done

if [ $ATTEMPTS_LEFT_TO_REACH_DATABASE -eq 0 ]; then
    echo "$DATABASE_ERROR"
    exit 1
fi

Si la base ne répond pas dans les 60 secondes, le container sort en erreur et Kubernetes le redémarre. Une fois la base prête, la migration tourne :

if [ "$( find ./migrations -iname '*.php' -print -quit )" ]; then
    php bin/console doctrine:migrations:migrate --no-interaction --all-or-nothing
fi

Deux changements par rapport à la commande d’origine : --all-or-nothing garantit que si une migration dans un batch échoue, le batch entier est annulé. Et le guard find passe la commande si aucun fichier de migration n’existe — utile pour les services qui n’utilisent pas les migrations Doctrine.

C’est franchement mieux. La base est là. La migration tourne dans le vrai environnement. Le flag --all-or-nothing apporte une atomicité que la version au build n’avait jamais eue.

Ce que ça ne résout pas

Deux pods qui redéploient simultanément exécutent tous les deux l’entrypoint. Tous les deux atteignent la base. Tous les deux trouvent des migrations en attente. Tous les deux appellent doctrine:migrations:migrate.

Doctrine a un mécanisme de verrouillage : une table doctrine_migration_versions qui enregistre quelles migrations ont tourné, et la commande la consulte avant d’appliquer quoi que ce soit. Dans les conditions normales c’est suffisant : le deuxième pod trouve la table à jour et sort proprement. Les cas de défaillance réels sont plus précis : une migration assez longue pour dépasser le timeout du verrou de base de données, ce qui laisse un deuxième runner démarrer la même migration avant que le premier ait terminé ; ou un pod qui se vautre à mi-migration avant d’avoir enregistré la version dans la table, laissant le schéma dans un état appliqué-mais-non-enregistré que le pod suivant va tenter d’appliquer à nouveau.

La position de l’équipe est explicite : un downtime léger au déploiement est acceptable. Les versions d’application ne sont pas nécessairement compatibles avec des versions de schéma plus anciennes, donc faire tourner N et N+1 simultanément contre la même base ne serait de toute façon pas sûr. La stratégie de déploiement est Recreate : tous les anciens pods sont terminés avant que les nouveaux ne démarrent. La migration tourne au premier démarrage, sans chevauchement entre les versions. Ça fonctionne.

Mais “ça fonctionne” et “c’est la bonne architecture” sont deux réponses différentes.

Ce que feraient les alternatives

Le Facteur XII dit que les processus d’administration doivent tourner dans des “processus ponctuels”. Un processus qui tourne une fois, dans un but précis, contre l’environnement de production. L’entrypoint n’est pas ponctuel — il tourne à chaque démarrage de container, y compris les redémarrages, les événements de scaling, et les déplacements de pods par Kubernetes.

Trois alternatives existent, chacune avec une réponse différente à la question de la propriété :

Un init container Kubernetes tourne avant le container principal, dans le même pod. Il peut exécuter la migration, sortir, et laisser le container principal démarrer seulement après son succès. La migration est isolée du runtime applicatif. Le problème : l’init container est une image supplémentaire à construire et maintenir, et il tourne à chaque démarrage de pod — une plateforme de 14 services démarrant simultanément a toujours une race potentielle.

Un Kubernetes Job tourne une fois, à la demande ou déclenché par le pipeline de déploiement. Il peut être configuré pour s’exécuter avant la mise à jour des pods — séquentiel, isolé, avec un signal clair de succès ou d’échec. La race condition disparaît. La complexité se déplace vers le processus de déploiement : le Job doit se terminer avant que le rollout du Deployment commence, et le pipeline CI doit coordonner les deux.

Un hook Helm est le même concept exprimé de façon déclarative dans le chart Helm. Un hook pre-upgrade exécute la migration avant la mise à jour des pods applicatifs. C’est la réponse la plus idiomatique pour Kubernetes. Ça signifie aussi que le chart Helm est désormais responsable de l’exécution des migrations — une décision qui appartient à qui possède le chart.

Cette dernière phrase explique pourquoi l’entrypoint n’a pas changé. Déplacer les migrations hors de l’application signifie décider que l’infrastructure de déploiement — pas l’application elle-même — est responsable du schéma. C’est une question de gouvernance autant que de technique, et les questions de gouvernance prennent plus de temps à résoudre que les changements de code.

La fin honnête

Le bloc de migration dans l’entrypoint, c’est deux lignes. Littéralement : le guard if [ "$( find ./migrations... )" ], et le php bin/console doctrine:migrations:migrate qui suit. Onze autres facteurs ont des résolutions nettes. Le cache est passé sur Redis. Les logs vont vers stdout. Le système de fichiers est un bucket S3. Le CI assemble les images de production depuis le même commit qu’il teste. Les secrets ne voyagent plus dans les layers d’image.

Le Facteur XII a une réponse. Ce n’est juste pas la réponse finale.

Les migrations tournent au démarrage, avec une vraie base de données, avec atomicité, avec une fenêtre de retry bornée. C’est mieux que de tourner au build contre rien. La question de savoir si elles finiront dans un Job ou un hook Helm est une conversation sur qui possède le schéma — une question à laquelle un kubectl apply ne peut pas répondre.

Pendant les quarante secondes suivantes — sur les soixante possibles — ce container était en train de poller la base de données.

Les requêtes qui atterrissaient dessus pendant cette fenêtre récoltaient des erreurs. Pas beaucoup — la fenêtre était courte — mais assez pour apparaître comme du bruit dans le monitoring. Le genre de bruit qu’on classe comme « problème réseau transitoire » et qu’on ne signale nulle part. Le déploiement a réussi. Le pod a fini par devenir prêt. Le mécanisme qui en était la cause était toujours là, attendant le prochain déploiement.

Le script d’entrypoint fait cinq choses avant que FrankenPHP démarre : copier un fichier de version, vérifier le répertoire vendor, attendre jusqu’à soixante secondes la base de données, jouer les migrations en attente, installer les assets et configurer les permissions filesystem. Sous Docker Compose, c’est invisible. Sur Kubernetes, l’écart devient du trafic en erreur.

L’écart entre démarré et prêt

Kubernetes décide d’envoyer du trafic à un pod en surveillant sa readiness probe. Un pod dont la readiness probe passe reçoit des requêtes. Un pod dont la readiness probe échoue est retiré de la rotation du load balancer jusqu’à ce qu’il récupère. C’est le mécanisme qui rend les rolling deploys sûrs : Kubernetes ne bascule pas vers un nouveau pod tant que ce pod n’indique pas qu’il est prêt.

Le compose.yaml définit un healthcheck sur chaque service :

healthcheck:
    test: [ "CMD", "php", "-v" ]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 10s

php -v réussit dès que le binaire PHP est présent — ce qui est vrai depuis la première milliseconde de vie du container. Le start_period: 10s donne dix secondes avant que les vérifications commencent. Mais la boucle de polling de l’entrypoint tourne jusqu’à soixante secondes avant que FrankenPHP démarre. À la dixième seconde, le healthcheck passe. L’application attend toujours la base de données.

Le Dockerfile a un meilleur signal :

HEALTHCHECK --start-period=60s CMD curl -f http://localhost:2019/metrics || exit 1

Le port 2019 est le serveur de métriques intégré à Caddy, embarqué directement dans FrankenPHP. L’endpoint est compatible Prometheus et ne répond qu’une fois que la stack HTTP de Caddy est pleinement initialisée et que les workers PHP acceptent des connexions. php -v se termine en cinquante millisecondes quel que soit l’état de l’application — il vérifie le binaire, pas le serveur. :2019/metrics ne répond que quand le serveur sert vraiment. Ce n’est pas non plus un endpoint ajouté exprès pour la probe : chaque service de la plateforme l’a déjà scraped par Prometheus, donc le signal est actif indépendamment de toute configuration de healthcheck.

C’est plus proche. Mais sur Kubernetes, l’instruction HEALTHCHECK du Dockerfile est totalement ignorée. Kubernetes utilise sa propre configuration de probes. Sans définitions de probes explicites dans les manifests Kubernetes, il n’y a aucune vérification de readiness — et un pod est considéré prêt dès que son container démarre.

Ce qui signifie : le pod démarre, l’entrypoint commence à poller, Kubernetes route du trafic, l’application n’est pas encore en état de le traiter. Les requêtes arrivent sur un container qui n’est pas prêt à les gérer.

Trois signaux, trois questions

Kubernetes sépare le cycle de vie d’un container en trois questions distinctes, chacune avec son propre type de probe :

startupProbe — « L’application a-t-elle fini de démarrer ? » Se déclenche à répétition jusqu’à ce qu’elle passe, puis passe la main à la liveness. Empêche la liveness probe de tuer un container qui est légitimement long à initialiser. Pour un container dont l’entrypoint peut prendre soixante secondes, c’est l’outil adapté.

readinessProbe — « L’application est-elle prête à traiter des requêtes ? » Échoue et passe tout au long de la vie du container. Quand elle échoue, le pod est retiré du load balancer. C’est ce qui rend un rolling deploy sûr.

livenessProbe — « L’application est-elle toujours vivante ? » Si elle échoue, Kubernetes redémarre le container. Conçue pour détecter les processus bloqués, pas les démarrages lents.

La boucle de polling de soixante secondes appartient à la patience de la startupProbe, pas au code applicatif :

startupProbe:
    httpGet:
        path: /metrics
        port: 2019
    failureThreshold: 12    # 12 tentatives × 5s = 60s max
    periodSeconds: 5

Une fois la startupProbe passée, une readinessProbe sur le même endpoint prend le relais — indiquant à Kubernetes quand le pod peut recevoir du trafic — et une livenessProbe surveille les processus bloqués. Mais c’est la startupProbe qui absorbe le démarrage lent. La boucle de polling de l’entrypoint devient redondante : son rôle était de maintenir le container en vie pendant que la base de données devenait disponible. Sans elle, l’application tente de se connecter, échoue, et le container quitte — Kubernetes redémarre alors le pod, et la startupProbe maintient son cycle de tentatives jusqu’à ce que la base réponde et que l’application démarre proprement. La responsabilité du retry passe de l’intérieur de l’entrypoint à l’orchestrateur, ce qui est exactement là où elle devrait être.

Le problème des migrations

La boucle de polling est le problème le plus visible, mais les migrations en créent un plus subtil.

Avec un rolling deploy et deux replicas, Kubernetes démarre un nouveau pod pendant que l’ancien sert encore du trafic. Les deux pods jouent le même entrypoint. Les deux atteignent doctrine:migrations:migrate.

La table de migrations de Doctrine trace quelles migrations ont déjà été exécutées, donc une migration complétée ne se jouera pas deux fois. Mais si deux pods démarrent simultanément et voient tous les deux une migration en attente, les deux tentent de la jouer en même temps. Si c’est sûr ou non dépend de la migration : les changements de schéma additifs passent en général bien ; les destructifs moins. Et on ne choisit pas lesquels s’exécutent lors d’un déploiement qui n’a pas prévu de se coordonner. --all-or-nothing enveloppe les migrations dans une transaction et fait un rollback si l’une échoue — c’est une question d’atomicité au sein d’une seule exécution, pas de coordination entre processus.

L’approche plus propre sépare ces deux préoccupations en deux init containers : l’un qui attend la base de données, l’autre qui joue les migrations. Le container principal ne démarre qu’une fois les deux terminés :

initContainers:
    - name: wait-for-db
      image: authentication:latest
      command: ["php", "bin/console", "dbal:run-sql", "-q", "SELECT 1"]
    - name: migrate
      image: authentication:latest
      command: ["php", "bin/console", "doctrine:migrations:migrate", "--no-interaction", "--all-or-nothing"]

Les deux init containers réutilisent la même image que l’application. Ce n’est pas du gaspillage : ils ont besoin du même binaire PHP et du même câblage d’environnement pour atteindre la base de données et trouver les classes de migration. Une image dédiée plus légère réduirait le temps de démarrage, mais nécessiterait de maintenir une installation PHP séparée en synchronisation avec l’image principale.

Même avec des init containers, plusieurs pods démarrant simultanément — déploiement initial, après une défaillance de nœud, ou sous pression d’autoscaling — tenteront chacun de jouer les migrations. Le résoudre proprement — via un hook pre-upgrade Helm, une stratégie maxSurge: 0, ou un Job de migration séparé — est un sujet en soi. Ce qui compte ici, c’est que l’entrypoint est le mauvais endroit pour prendre cette décision : il ne peut pas se coordonner entre pods, et il lie l’exécution des migrations au démarrage de l’application d’une façon difficile à démêler plus tard. La question de quelle alternative convient à cette codebase — et pourquoi l’entrypoint n’a pas encore été remplacé — fait l’objet de l’article suivant dans cette série .

Le Facteur XII de la méthodologie twelve-factor — les processus d’administration tournent dans le même environnement que l’application — est respecté dans les deux cas. La question est de savoir si « même environnement » signifie « même script d’entrypoint » ou « même image, processus séparé ». Sur Kubernetes, le second est plus sûr.

La vraie responsabilité de l’entrypoint

Enlever l’attente de la base de données (maintenant une startupProbe ou un init container), les migrations (maintenant un init container ou un Job), et l’installation des assets (une opération de build-time qui appartient au Dockerfile), et l’entrypoint n’a plus qu’une seule responsabilité : démarrer l’application.

exec docker-php-entrypoint "$@"

Le Facteur IX de la twelve-factor app demande un démarrage rapide et un arrêt propre. Un container dont le démarrage prend soixante secondes parce qu’il attend des dépendances externes n’est pas rapide. Ça signifie des rolling deploys lents, une reprise après crash lente, et un scale-out horizontal qui crée une fenêtre de soixante secondes avant que chaque nouveau pod contribue.

Le démarrage rapide n’est pas juste un confort. C’est ce qui fait fonctionner le reste du modèle cloud. Quand un pod peut démarrer en secondes, l’orchestrateur peut scaler agressivement et récupérer vite. Quand ça prend une minute, on ajoute des marges partout — timeouts de probes plus longs, fenêtres de déploiement plus larges, politiques de scaling plus conservatrices — et le système devient rigide.

La taxe Docker Compose

L’entrypoint accumule ces responsabilités pour une raison. Sous Docker Compose, il n’y a pas de concept d’init container. Pas de startupProbe. Les services déclarent depends_on, mais sans conditions de santé, c’est juste de l’ordre de démarrage — pas de la readiness. L’entrypoint comble le vide.

Ce n’est pas un défaut de conception. C’est une adaptation raisonnable aux contraintes de Docker Compose. Le script fonctionne. Il gère les cas limites (le timeout de la base, les erreurs irrécupérables, le répertoire de migrations absent). Quelqu’un l’a testé.

Le problème, c’est l’hypothèse que le même script fonctionne aussi bien sur Kubernetes. Il tourne. L’application finit par démarrer. Mais il contourne le système de probes qui rend les déploiements Kubernetes fiables, et il place la responsabilité des migrations à un endroit où la coordination entre pods est difficile à raisonner.

Plusieurs des changements de cette série — stockage des médias , secrets dans les images , handlers de logs , dépendances de services , parité d’environnement CI , adaptateurs de cache — étaient des changements au code applicatif ou à la configuration. Celui-ci est différent. Il demande à l’infrastructure de comprendre ce que « prêt » signifie pour cette application, et il demande à l’entrypoint de céder des responsabilités qu’il détient actuellement.

C’est une conversation plus difficile. Mais la startupProbe attend.

Puis quelqu’un a remarqué que le rate limiter se comportait bizarrement. Cinq appels à l’API, accès bloqué. Cinq appels supplémentaires à la requête suivante, accès accordé. Selon quel pod répondait, on était une personne différente.

C’était le cache qui parlait. Une ligne de config, répliquée sur treize services, bloquait le scaling horizontal dans sa totalité.

Un fichier de config, treize fois

On préparait une plateforme de treize microservices Symfony pour passer sur Kubernetes. La stack était déjà en bon état : FrankenPHP pour le serveur HTTP, des Dockerfiles multi-étapes, un GitLab CI qui poussait des images taguées vers un registre cloud. Les pièces étaient là. Il fallait juste vérifier que rien ne casserait quand on commencerait à scaler les pods horizontalement.

Une bonne checklist pour ce type d’audit, c’est la méthodologie twelve-factor app — douze principes pour construire des logiciels qui tournent proprement dans des environnements cloud. La plupart des facteurs étaient déjà couverts sans qu’on y ait pensé délibérément.

Le Facteur VII (port binding) était gratuit. FrankenPHP embarque Caddy directement dans le processus PHP. Le container expose son propre endpoint HTTP, sans Apache ni Nginx à ajouter. L’image est autonome, ce que le facteur demande exactement :

HEALTHCHECK --start-period=60s CMD curl -f http://localhost:2019/metrics || exit 1

Le Facteur II (dépendances) était géré par composer.json et les extensions du Dockerfile. Le Facteur X (parité dev/prod) était suffisamment couvert pour notre périmètre : même image, mêmes backing services en local et en CI, ce qui est la partie qui compte vraiment pour l’audit.

Puis j’en suis arrivé au Facteur VI.

Le problème avec « ça marche sur un seul serveur »

Le Facteur VI dit que les processus ne doivent rien partager. Rien d’écrit sur disque entre les requêtes, rien en mémoire locale qu’une autre instance ne puisse pas voir. Si on a besoin de persister de l’état, on le met dans un backing service — une base de données, un cluster de cache, une queue. Le processus lui-même reste jetable.

J’ai ouvert authentication/config/packages/cache.yaml. Puis content/config/packages/cache.yaml. Puis media/config/packages/cache.yaml.

framework:
    cache:
        app: cache.adapter.filesystem

Treize services. Treize fois, mot pour mot.

Chaque instance de chaque service écrivait son cache sur le filesystem local. Ce qui signifiait que chaque pod avait son propre cache privé, invisible pour tous les autres pods. Quand le load balancer envoyait une requête au pod A, il obtenait la version mise en cache par le pod A. Le pod B avait construit la sienne. Elles pouvaient avoir été générées à des moments différents, depuis des données sources différentes, ou l’une d’elles pouvait ne pas encore avoir été construite du tout.

Le rate limiter était le symptôme le plus visible parce qu’il avait un compteur. Mais la même divergence affectait chaque donnée qu’on mettait en cache : métadonnées du sérialiseur, collections de routes, caches de résultats Doctrine. Deux utilisateurs envoyant des requêtes identiques pouvaient obtenir des réponses différentes selon quel nœud avait récupéré la connexion.

Redis était déjà là

C’est la partie qui pique un peu. Redis était déjà dans la stack. Chaque service l’avait configuré via SncRedisBundle :

# config/packages/snc_redis.yaml — présent sur les 13 services
snc_redis:
    clients:
        default:
            type: 'phpredis'
            alias: 'default'
            dsn: '%env(IN_MEM_STORE__URI)%'

Le Facteur IV de la twelve-factor app dit que les backing services doivent être des ressources attachées, interchangeables via la configuration. Redis était exactement ça : joignable via une variable d’environnement, prêt à être remplacé par une instance managée dans le cloud. La plomberie était faite. On ne s’en servait juste pas pour le cache applicatif.

Certains services l’avaient même juste pour des pools spécifiques. Le rate limiter dans le service d’authentification :

pools:
    rate_limiter.cache:
        adapter: cache.adapter.redis

Ce qui explique l’incohérence qu’on a vue en premier. Le compteur du rate limit allait vers Redis (partagé entre les pods). Le cache qui alimentait la vérification du rate limit allait vers le filesystem (local au pod). Deux sources de vérité, l’une invisible à l’autre.

La correction tenait en une ligne par service :

framework:
    cache:
        app: cache.adapter.redis
        default_redis_provider: snc_redis.default

Treize fichiers. Treize changements identiques. Le genre de correction qui donne l’impression qu’on aurait dû la repérer avant, sauf qu’elle est parfaitement invisible quand on tourne sur une seule instance.

Ce qui doit migrer vers Redis

Le cache filesystem violait le Facteur VI (les processus portent de l’état local qu’ils ne devraient pas) et le Facteur VIII (on ne peut pas scaler sans partager cet état). C’est le même problème vu sous deux angles : VI décrit ce qui ne va pas, VIII décrit ce qu’on ne peut pas faire à cause de ça.

Avec un backend de cache partagé, un deuxième pod est sûr. Les deux pods construisent le même cache, voient les mêmes invalidations, s’accordent sur les mêmes limites de rate. On peut ajouter un troisième pod sous charge et le retirer quand le trafic baisse. L’orchestrateur s’en occupe ; l’application n’a pas besoin de le savoir.

Sans ça, le scaling horizontal est un risque. Plus de pods, c’est plus de divergence, plus de bugs « ça marche chez moi » qu’il est impossible de reproduire en local parce qu’en local on tourne avec un seul container.

Les sessions avaient le même problème — et potentiellement pire. Douze des treize services utilisaient session.storage.factory.native — qui écrit les sessions sur le filesystem par défaut. Un utilisateur dont la requête atterrit sur le pod A obtient une session liée au pod A. Sa requête suivante va sur le pod B. Session perdue, il est déconnecté. Un seul service avait RedisSessionHandler configuré.

La mitigation partielle : la plupart de la plateforme tourne sur des APIs stateless avec des JWT, donc l’usage des sessions est limité. Mais « limité » n’est pas « zéro ». Les services qui créent des sessions — flows d’authentification, état temporaire pendant les handshakes OAuth — ont un mode de défaillance visible par l’utilisateur qui attend le deuxième pod. Soit ces sessions migrent vers Redis, soit le code qui les crée est supprimé. Les laisser en l’état est une décision qui attend le premier utilisateur dont la session disparaît sans explication.

L’autre genre d’état

Redis résout le problème cross-pod. FrankenPHP introduit un autre problème qu’il vaut la peine de connaître.

Dans le modèle PHP-FPM standard, chaque requête forke un processus frais. Tout objet en mémoire — toute valeur mise en cache, tout résultat calculé — meurt avec la réponse. Le processus est stateless par construction.

FrankenPHP a un mode worker qui ne suit pas ce modèle. En mode worker, un seul processus PHP démarre une fois, charge le kernel, câble le container, et gère plusieurs requêtes successives sans redémarrer. Le débit de requêtes s’améliore : pas de cold start de l’autoloader, pas de rebuild du container par requête, moins d’allocations. La contrepartie : le processus PHP a maintenant un cycle de vie qui enjambe les requêtes.

Pour le cache, ça ajoute une complexité. Un adaptateur array ou un pool APCu accumule des entrées à travers les requêtes sur le même worker. Une invalidation de cache poussée vers Redis atteint immédiatement les autres pods — mais ne vide pas ce qui est assis dans la mémoire du worker. Deux requêtes sur le même pod peuvent voir des choses différentes : l’une touche une entrée en mémoire chaude, la suivante déclenche un fetch Redis après expiration de l’entrée in-process.

La plateforme garde le mode worker désactivé (APP__WORKER_MODE__ENABLED=false). Il est disponible — l’infrastructure est là, le flag est câblé — mais pas actif. Le gain de performance ne justifiait pas l’audit. Chaque pool de cache aurait besoin d’être vérifié contre la sémantique du mode worker ; chaque endroit où de l’état fuit entre les requêtes deviendrait un bug potentiel.

La position conservatrice : garder PHP stateless au niveau du processus même quand le runtime ne l’exige pas. Le principe shared-nothing du Facteur VI s’applique non seulement au filesystem — il s’applique au processus lui-même.

Ce qui fonctionnait déjà

Pour être juste envers la codebase : le Scheduler Symfony utilisait déjà Redis pour les locks distribués :

$schedule->lock($this->lockFactory->createLock('schedule_purge'));

Dans un environnement multi-pod, on ne veut pas cinq instances lancer le même job de purge simultanément. Le lock l’empêche. Redis rend le lock visible entre les pods. Celui qui a écrit le scheduler savait exactement ce qu’il faisait.

Le même raisonnement ne s’était juste pas propagé à la configuration du cache — probablement parce qu’en tournant sur une seule instance, cache.adapter.filesystem est invisible. Ça fonctionne, c’est rapide, ça ne demande aucune configuration. Le problème n’apparaît qu’à deux.

Les quatre questions

Le Facteur VI prend la plupart des applications par surprise lors d’une migration cloud. Pas parce que les développeurs ne connaissent pas les processus stateless — ils le savent généralement — mais parce que le filesystem est toujours là, et le problème reste caché jusqu’à ce qu’on essaie de lancer une deuxième instance.

Avant de scaler un service Symfony horizontalement, quatre questions méritent une réponse :

• Où va le cache applicatif ? (cache.adapter.filesystem doit devenir cache.adapter.redis)
• Où vont les sessions ? (session.storage.factory.native a besoin de Redis — ou supprimer les sessions entièrement si on est full JWT)
• Est-ce que quelque chose écrit dans var/ à l’exécution qu’un autre pod aurait besoin de lire ?
• Est-ce qu’il y a quelque chose dans le chemin de code qui doit être mutuellement exclusif entre pods ? (si oui, c’est un job pour le composant Lock de Symfony adossé à Redis, pas un mutex local)

Si toutes les réponses pointent vers des backing services partagés, on est prêt. Si l’une d’elles pointe vers le filesystem local, la production finira par trouver le pod qui a construit son cache il y a trois heures et le servira à l’utilisateur qui s’y attend le moins.

stages:
  - build
  - provision
  - phpunit
  - phpmetrics
  - behat
  - deprovision
  - deploy

Avant que la première assertion s’exécute, quinze minutes s’étaient écoulées. Terraform avait cloné un dépôt d’infrastructure, s’était authentifié sur Azure, avait appliqué une configuration de VM. Ansible s’était connecté à la nouvelle VM, avait installé PHP, configuré l’application, câblé une base de données et une instance Redis. Ensuite les tests tournaient. Ensuite Terraform détruisait ce qu’Ansible avait construit.

Pour chaque pipeline. Depuis chaque branche. Pour chaque pull request, de l’ouverture au merge.

Ce que ces quinze minutes ne contenaient pas

Le stage provision mettait en place deux services : PostgreSQL et Redis. Trois services dont l’application dépendait en production étaient absents : RabbitMQ, MinIO et Varnish.

RabbitMQ traitait tout le travail asynchrone — 56 consumers sur 14 microservices. MinIO gérait le stockage de médias. Varnish était devant le cache HTTP. En CI, aucun d’eux n’existait. Les tests qui couvraient les files de messages ou le stockage de fichiers avaient deux options : ignorer ces chemins, ou les laisser non testés jusqu’au staging. Varnish est un cas à part : les tests tapent directement dans l’application et contournent intentionnellement la couche de cache, son absence en CI est donc un choix délibéré plutôt qu’un manque.

C’est le problème que le Facteur X décrit comme l’écart d’environnement. L’écart ici n’était pas une question de configuration — il était structurel. La VM était construite par Ansible depuis un script dans un dépôt séparé. Ce n’était pas une image de container. Elle n’était pas versionnée aux côtés de l’application. Si une branche modifiait la topologie de messages RabbitMQ, il n’y avait aucun moyen de tester cette modification en CI. Le changement de topologie et le code qui en dépendait ne se rencontreraient qu’en staging.

Le script de provisioning Ansible lui-même fait partie du problème :

launch_vm:
  stage: provision
  script:
    - git clone git@gitlab.internal/infra/ci-vm.git
    - cd ci-vm
    - az login --service-principal -u $ARM_CLIENT_ID ...
    - terraform apply -var "prefix=${CI_PIPELINE_ID}-vm" ...
    - sleep 45
    - ansible-playbook behat/test-env.yml ...

Le sleep 45 est là parce qu’Ansible a besoin que la VM finisse de booter avant de pouvoir s’y connecter. Ce n’est pas un oubli — c’est le délai minimum qu’une VM fraîchement provisionnée nécessite avant que SSH fonctionne. C’est inscrit dans le processus.

Ce qui l’a remplacé

Le nouveau pipeline n’a pas de stage provision. Il n’a pas de stage deprovision. L’environnement, ce sont les images, et les images existent avant que les tests commencent.

Chaque job de test déclare ses dépendances comme des services Docker :

services:
  - name: $REGISTRY_URL/platform/rabbitmq:$CI_COMMIT_REF_SLUG
    alias: rabbitmq
  - name: $REGISTRY_URL/platform/minio:$CI_COMMIT_REF_SLUG
    alias: minio
  - name: redis:7.4.1
    alias: redis
  - name: $ARTIFACTORY_URL/postgresql:13
    alias: postgresql

Les services démarrent en parallèle quand le job commence. Avant que le script de test tourne, un before_script attend qu’ils soient tous prêts :

before_script:
  - $CI_PROJECT_DIR/dockerize
      -wait tcp://postgresql:5432
      -wait tcp://rabbitmq:5672
      -wait tcp://minio:9000
      -wait tcp://redis:6379
      -timeout 120s

Du démarrage du pipeline à la première assertion : quatre-vingt-dix secondes — en supposant que les images sont déjà dans le cache du runner ; un cold pull rallonge les choses, mais devient négligeable une fois que le pipeline a tourné une fois sur une branche donnée.

Ce que signifie $CI_COMMIT_REF_SLUG

Le timing est le résultat visible. Ce qui le produit est plus intéressant encore : les noms des images.

$REGISTRY_URL/platform/rabbitmq:$CI_COMMIT_REF_SLUG n’est pas l’image officielle RabbitMQ de Docker Hub. C’est une image construite par le même pipeline, depuis la même branche, au même commit que le code testé. L’image RabbitMQ embarque la topologie : un definitions.json avec chaque exchange, chaque queue, chaque binding, chaque configuration de dead-letter — versionné dans git aux côtés de l’application qui en dépend.

Si une branche modifie la topologie de messages, le pipeline CI construit une nouvelle image RabbitMQ qui inclut ces modifications, puis exécute les tests contre elle. Le changement de topologie et le code qui en dépend sont testés ensemble, au même commit, avant que quoi que ce soit n’atteigne le staging.

La même logique s’applique à MinIO, décrite dans le premier article de cette série : l’image MinIO embarque des fixtures de test préchargées. L’environnement CI n’a pas besoin d’une étape de setup pour peupler le stockage. L’état est intégré à l’artefact.

Le runner de tests lui-même suit le même pattern. Chaque job utilise une variante debug de l’image applicative — construite depuis la même branche, au même commit — avec les dépendances de test incluses :

image: $REGISTRY_URL/platform/$service:$CI_COMMIT_REF_SLUG-debug

Tout l’environnement s’assemble depuis des artefacts construits au même point de l’historique git.

Ce que ça a demandé d’abandonner

Behat et la VM provisionnée étaient couplés. La suite de tests Behat tournait contre un serveur HTTP sur la VM ; supprimer la VM signifiait supprimer Behat.

Ça s’est révélé moins bloquant que ça n’en avait l’air. La suite Behat vivait dans un dépôt séparé, nécessitait la VM pour tourner, et avait accumulé une charge de maintenance significative. PHPUnit, tournant dans le container applicatif avec les services Docker, couvrait les mêmes scénarios par un chemin plus direct : tests fonctionnels qui exercent la couche HTTP, tests unitaires pour les composants individuels, suites organisées par domaine fonctionnel et générées dynamiquement en jobs CI parallèles.

La couche BDD a disparu. La couverture de tests est restée — et pouvait désormais tourner contre les vrais services.

Le Facteur X, appliqué

Le Facteur X se lit souvent comme “utilise la même base de données en local qu’en production.” C’est la version la plus simple. La version plus profonde concerne l’écart entre ce qu’on teste et ce qu’on livre.

L’écart dans l’ancien pipeline était large : une VM configurée manuellement, privée de services clés, reconstruite de zéro à chaque run. L’écart dans le nouveau pipeline est étroit : le CI assemble l’environnement depuis les mêmes images que la production, construites au même commit que le code sous test.

Les quinze minutes de Terraform et Ansible n’étaient pas seulement lentes. Elles construisaient quelque chose qui n’était pas ce que la production faisait tourner, à chaque fois, avant que le moindre test puisse commencer. Les quatre-vingt-dix secondes de docker pull construisent exactement ce que la production fait tourner — et les tests qui suivent testent ça, pas une approximation.

APP__GATEWAY__PRIVATE__HOST="platform.internal"
APP__GATEWAY__PRIVATE__PORT=80
APP__GATEWAY__PRIVATE__SCHEME="http"
APP__GATEWAY__PUBLIC__HOST="platform.internal"
APP__GATEWAY__PUBLIC__PORT=80
APP__GATEWAY__PUBLIC__SCHEME="http"

Treize services, six variables chacun, une seule valeur. En lisant la config d’un service quelconque, l’architecture semblait plate. Tout parlait au même hôte. C’était tout le tableau.

Ce ne l’était pas.

Comment fonctionnait la gateway

La gateway se trouvait devant chaque service et gérait tout le trafic inter-services. Un service appelant l’API content construisait une requête vers http://platform.internal/content/api/ — la gateway la recevait, identifiait la cible depuis le chemin de l’URL, et la transmettait au bon backend. Chaque client HTTP inter-service dans framework.yaml suivait le même schéma :

content.client:
    base_uri: "%http_client.gateway.base_uri%/content/api/"
    headers:
        Host: "%env(APP__GATEWAY__PRIVATE__HOST)%"

Le paramètre http_client.gateway.base_uri était assemblé depuis les variables GATEWAY. La gateway savait où tournait chaque service. Les services n’avaient pas besoin de le savoir. De leur point de vue, tout était platform.internal.

Ça fonctionnait. Pendant des années, ça fonctionnait bien. Ajouter un service signifiait ajouter un alias DNS dans la config de la gateway, pas toucher treize fichiers .env. La gateway abstraisait la topologie. Les services restaient découplés du détail d’infrastructure de qui tournait où.

Ce que la gateway absorbait

L’abstraction avait un coût qui n’apparaissait pas tant qu’on n’essayait pas de lire le système.

En regardant le fichier env de content, on voyait six variables de gateway et rien d’autre sur la communication inter-services. Pour découvrir que content appelait conversion, shorty et media, il fallait lire framework.yaml. Pour découvrir que pilot appelait dix services externes, il fallait tracer les clients HTTP un par un et compter.

Le chiffre était dix. Authentication, bam, config, content, conversion, media, product, shorty, sitemap, social. Dix des treize services de la plateforme dont pilot dépendait à l’exécution, aucun d’eux visible depuis sa configuration. Six variables disaient : parle à la gateway. Elles ne disaient rien de la forme de ce qui se trouvait derrière.

Cette information existait — dans le code, dans la config framework, dans les têtes des gens qui avaient construit ces intégrations. Elle ne vivait juste nulle part où on pouvait la lire d’un coup d’œil.

Ce que Kubernetes a rendu explicite

On-premise, la gateway était un seul hostname résolvable. Un enregistrement DNS, un jeu de variables, un seul endroit à mettre à jour. Kubernetes ne fonctionne pas comme ça. Chaque service obtient son propre nom DNS à l’intérieur du cluster — content.namespace.svc.cluster.local, conversion.namespace.svc.cluster.local. Le trafic inter-services passe directement, service à service, sans gateway partagée.

Passer à Kubernetes signifiait que l’abstraction de la gateway devait céder la place. Chaque service devait savoir, concrètement, où vivait chacune de ses dépendances. Les six variables génériques ne pouvaient pas exprimer ça.

Le refacto les a remplacées par des variables HOST par cible — une par dépendance de service, nommée d’après la cible :

# content/.env — content appelle ces quatre services
APP__CONFIG__HOST="platform.internal"
APP__CONVERSION__HOST="platform.internal"
APP__MEDIA__HOST="platform.internal"
APP__SHORTY__HOST="platform.internal"

# pilot/.env — dix dépendances de service
APP__AUTHENTICATION__HOST="platform.internal"
APP__BAM__HOST="platform.internal"
APP__CONFIG__HOST="platform.internal"
APP__CONTENT__HOST="platform.internal"
APP__CONVERSION__HOST="platform.internal"
APP__MEDIA__HOST="platform.internal"
APP__PRODUCT__HOST="platform.internal"
APP__SHORTY__HOST="platform.internal"
APP__SITEMAP__HOST="platform.internal"
APP__SOCIAL__HOST="platform.internal"

Chaque client HTTP dans framework.yaml a reçu sa propre base_uri construite depuis la variable HOST de sa cible, et le header Host a cédé la place à un User-Agent qui identifie l’appelant :

content.client:
    base_uri: "%env(APP__HTTP__SCHEME)%://%env(APP__CONTENT__HOST)%:%env(APP__HTTP__PORT)%/content/api/"
    headers:
        User-Agent: "Platform Content - %semver%"

Le changement n’est pas cosmétique. Dans l’ancienne configuration, le header Host explicite garantissait que les requêtes atteignaient le bon virtual host de la gateway quelle que soit la résolution DNS. Dans la nouvelle, chaque client pointe directement vers le nom DNS de sa cible — le Host correct est dérivé automatiquement de la base_uri. L’emplacement du header ne reste pas vide : le User-Agent identifie désormais le service appelant, ce qui remonte dans les logs et le traçage distribué sans instrumentation supplémentaire.

L’inconfort de la lisibilité

Le fichier env de pilot est passé de neuf variables de gateway à dix variables HOST spécifiques par service. Le fichier est devenu plus long. L’architecture n’est pas devenue plus simple — les dix dépendances étaient là avant et elles sont toujours là. Ce qui a changé, c’est qu’elles sont lisibles.

Le Facteur III dit de stocker la config dans l’environnement. L’ancienne approche satisfaisait ça à la lettre : six variables, toutes dans des fichiers env, aucune en dur dans le code. Mais des variables qui effondrent le graphe de dépendances entier dans un seul hostname opaque ne sont pas vraiment de la configuration — elles sont un raccourci qui échange la lisibilité contre la commodité. Le Facteur III ne demande pas seulement que la config soit externalisée — il suppose implicitement qu’elle reste informative une fois externalisée.

Le refacto n’a rien simplifié. Il a rendu la complexité visible. Les dix variables HOST de pilot documentent, dans le fichier .env lui-même, les dix services dont il dépend. Un nouveau membre d’équipe qui lit ce fichier apprend quelque chose de réel sur l’architecture. L’ancien fichier lui apprenait qu’il y avait une gateway.

Il y a une version de cette histoire où on lit l’état final et on conclut que l’équipe a fait un travail inutile — elle a remplacé six variables par dix, toutes pointant vers le même hôte de toute façon. En développement local, platform.internal résout toujours au même endroit. Le comportement fonctionnel n’a pas changé.

Le changement est dans ce que la config communique. Dans Kubernetes, les valeurs HOST divergent : chaque cible obtient son propre nom DNS interne au cluster, différent par environnement. Les variables portent maintenant une vraie information. Le refacto a préparé la config à être honnête sur une topologie qu’elle simplifiait silencieusement depuis des années.

Ce qu’on n’avait pas, c’était les logs des cinq minutes précédant le crash.

Promtail tournait. Il était healthy. Il collectait les logs de tous les autres services sans problème. Mais pour celui-ci, dans la fenêtre qui comptait, il n’y avait rien. Le service s’était crashé sans laisser de trace.

Le setup qui semblait correct

La stack de logging était raisonnable. Chaque service écrivait du JSON structuré vers stdout avec le formatter logstash de Monolog :

stdout:
    type: stream
    path: "php://stdout"
    level: "%env(MONOLOG_LEVEL__DEFAULT)%"
    formatter: 'monolog.formatter.logstash'

Promtail collectait la sortie des containers via la socket Docker, parsait le JSON, extrayait des labels, poussait vers Loki :

scrape_configs:
    -
        job_name: docker
        docker_sd_configs:
            -
                host: unix:///var/run/docker.sock
                refresh_interval: 5s
        pipeline_stages:
            -
                drop:
                    older_than: 168h
            -
                json:
                    expressions:
                        level: level
                        msg: message
                        service: service
            -
                labels:
                    level:
                    service:
        relabel_configs:
            -
                source_labels: [ '__meta_docker_container_log_stream' ]
                target_label: stream

Deux stages font plus de travail que les autres. Le stage json extrait level et service de chaque ligne de log ; le stage labels qui suit immédiatement les promeut en labels d’index Loki, ce qui fait de {service="content", level="error"} une lookup directe plutôt qu’un scan plein texte sur les lignes stockées. Le relabeling stream conserve si une ligne venait de stdout ou stderr — une distinction requêtable dès que Monolog envoie les erreurs vers stderr et le reste vers stdout. Le stage drop older_than: 168h est une soupape de sécurité : si Promtail redémarre après une longue interruption et rejoue des lignes bufferisées, tout ce qui est plus vieux de sept jours est écarté avant d’atteindre Loki.

En théorie : les logs vont vers stdout, Promtail lit stdout, les logs apparaissent dans Loki. La méthodologie twelve-factor décrit exactement ce modèle pour le Facteur XI — traiter les logs comme des flux d’événements, écrire vers stdout, laisser l’environnement gérer la collecte et le routage.

L’application avait stdout. Promtail lisait stdout. Qu’est-ce qui pouvait mal tourner.

Ce que fingers_crossed emporte avec lui

En production, le bloc when@prod remplaçait le simple handler stream par quelque chose de plus sophistiqué :

when@prod:
    monolog:
        handlers:
            main:
                type: fingers_crossed
                action_level: error
                handler: main_group
                excluded_http_codes: [404]

La ligne excluded_http_codes: [404] est elle-même révélatrice : sans elle, chaque 404 d’un scanner ou d’un crawler déclenche un flush complet du buffer, déversant des mégaoctets de logs debug pour des URLs malformées. Quelqu’un avait déjà appris ça à ses dépens.

fingers_crossed est un pattern Monolog bien connu. L’idée est élégante : ne pas noyer les logs de production dans le bruit debug, mais si quelque chose tourne mal, retrouver rétrospectivement ce qui s’est passé avant l’erreur. Le handler bufferise chaque entrée de log en mémoire. Au moment où il voit une error, il flush le buffer entier vers le handler imbriqué — en donnant le contexte complet qui a précédé la défaillance.

Le problème, c’est ce qui se passe quand la défaillance n’est pas une erreur loguée. C’est un OOM kill. Un SIGKILL de l’orchestrateur. Un segfault. Un process qui arrête de répondre et est tué de force.

Dans ces cas, fingers_crossed n’atteint jamais son action_level. Le buffer existe, plein des cinq dernières minutes d’activité, et il disparaît avec le process. Les logs étaient là. Ils étaient en mémoire. Ils sont morts avant d’atteindre stdout.

Le Facteur IX du twelve-factor parle de disposabilité : les processus doivent démarrer vite et s’arrêter proprement. Sur un arrêt normal (SIGTERM), un processus bien élevé finit son travail en cours et quitte. Mais les crashes ne sont pas des arrêts propres, et les buffers mémoire ne sont pas résistants aux crashes. Le service était disposable au sens où on pouvait le redémarrer ; il ne l’était pas au sens où sa sortie était transparente.

Les fichiers que personne ne lisait

Il y avait un deuxième problème, plus silencieux mais tout aussi persistant.

Chaque service avait un handler main_group qui routait les logs vers deux destinations en parallèle :

main_group:
    type: group
    members: [main_file, stdout]

main_file:
    type: stream
    path: "%kernel.logs_dir%/%kernel.environment%.log"
    formatter: "monolog.formatter.logstash"

var/log/prod.log était écrit sur chaque service, dans chaque environnement, y compris en production. Le même contenu qui allait vers stdout allait aussi vers un fichier à l’intérieur du container. Le fichier grossissait sans rotation. Le fichier n’était pas accessible à Promtail (qui lisait depuis la socket Docker, pas depuis le filesystem du container). Le fichier consommait de l’espace disque. Personne ne le lisait.

Le channel audit était pire :

audit_file:
    type: stream
    path: "%kernel.logs_dir%/audit.log"
    formatter: 'monolog.formatter.line'

audit:
    type: group
    members: [audit_file, stderr]
    channels: ['audit']

Les logs d’audit allaient vers stderr (visible par Promtail) et vers audit.log (invisible à Promtail). Le format dans le fichier était une ligne brute, pas le JSON structuré qu’attendait Promtail. En pratique, la piste d’audit existait à deux endroits : l’une requêtable, l’autre enfouie dans un répertoire de container qui ne survivait que le temps du container.

Ce que le Facteur XI demande vraiment

Le onzième facteur est direct là-dessus : une application ne doit pas se soucier du routage ou du stockage de son flux de sortie. Elle écrit vers stdout. Tout le reste est le job de l’environnement.

Ça veut dire pas de handlers de fichiers en production. Pas en backup. Pas pour les pistes d’audit. Pas “au cas où”. Du moment qu’une application se met à gérer des fichiers, elle prend en charge la rotation, la rétention, l’espace disque, et l’accessibilité — rien de tout ça n’appartient à l’intérieur d’un container.

La correction pour les handlers de fichiers est directe. Dans when@prod, supprimer chaque handler *_file et chaque group qui en inclut un. Le channel audit reçoit le même traitement : stderr uniquement, JSON structuré, pas de fichier :

when@prod:
    monolog:
        handlers:
            stdout:
                type: stream
                path: "php://stdout"
                # défaut "warning" — configurable par déploiement via variable d'env pour du debug ciblé
                level: "%env(default:default_log_level:MONOLOG_LEVEL__DEFAULT)%"
                formatter: 'monolog.formatter.logstash'

            stderr:
                type: stream
                path: "php://stderr"
                level: error
                formatter: 'monolog.formatter.logstash'

            main:
                type: group
                members: [stdout]
                channels: ['!event', '!http_client', '!doctrine', '!deprecation', '!audit']

            audit:
                type: stream
                path: "php://stderr"
                level: debug
                formatter: 'monolog.formatter.logstash'
                channels: ['audit']

stdout pour le channel principal. stderr pour les erreurs et l’audit. Rien d’autre. Promtail récupère les deux via la socket Docker. Le container n’écrit rien sur disque. Et les logs d’audit sont maintenant du JSON structuré, requêtable dans Loki avec tout le reste.

La question plus dure sur fingers_crossed

Les handlers de fichiers, c’était simple. fingers_crossed est plus nuancé.

Le pattern résout un vrai problème : dans un service de production actif, tout logger en debug crée du bruit et des coûts. fingers_crossed permet de capturer le contexte sans le payer sauf si quelque chose tourne vraiment mal. C’est un compromis raisonnable quand le mode de défaillance contre lequel on protège est une erreur applicative (une exception, une 500, une requête lente).

Ce n’est pas un compromis raisonnable quand le mode de défaillance est un crash de process. Et dans un environnement Kubernetes, les crashes de process arrivent : évictions OOM, échecs de liveness probe, pression sur les nodes. Exactement les cas où on a le plus besoin des logs.

Une approche : garder fingers_crossed mais réduire la taille du buffer. Par défaut il garde tout depuis le dernier reset. Mettre buffer_size: 50 plafonne l’usage mémoire, ce qui limite aussi ce qui se perd lors d’un crash. On n’aura pas le contexte complet, mais on aura les cinquante dernières entrées. Cette voie réduit le périmètre de perte sans supprimer la cause : l’opacité dépend toujours d’un seuil d’erreur qui peut ne jamais se déclencher.

Une autre approche : accepter que les logs debug soient coûteux et monter le niveau par défaut en production. Alors on n’a plus besoin de fingers_crossed du tout — si info et au-dessus vont directement vers stdout, rien n’est jamais bufferisé.

L’approche retenue : supprimer fingers_crossed, monter le niveau par défaut à warning, garder un override debug disponible via variable d’env pour les investigations ciblées. Les logs qui comptent apparaissent immédiatement. Ceux qui ne comptent pas ne sont jamais écrits. Rien n’est bufferisé.

Les crashes ne flushent pas

Le Facteur XI et le Facteur IX se rejoignent au même point : un process qui meurt en plein milieu d’une requête. un autre article de cette série décrivait l’illusion d’un service qui fonctionnait parfaitement sur un pod mais se comportait silencieusement mal sur deux. C’est la même illusion, un niveau au-dessus : un service qui semblait logger correctement, jusqu’au moment où il en avait le plus besoin.

La règle pour Monolog en production est sans appel : si ça n’atteint pas stdout ou stderr avant que le process quitte, ça n’existe pas. Un handler de fichier à l’intérieur d’un container est invisible pour le collecteur de logs et meurt avec le pod. Un buffer fingers_crossed est invisible pour le collecteur de logs et meurt avec le process.

La production tend à créer les conditions où on a le plus besoin des logs — pression OOM, défaillances en cascade, mauvais déploiements — et c’est exactement les conditions où ces deux patterns échouent simultanément. Écrire vers stdout, adopter un niveau par défaut qui ne nécessite pas de bufferisation, et rendre l’override disponible pour quand on en a vraiment besoin. Les logs seront là. Ils n’attendront pas un seuil d’erreur qui ne se déclenche jamais.

docker run --rm <image> php -r "var_dump(require '.env.local.php');"

La sortie montrait tout ce que composer dump-env prod avait compilé dans l’image au moment du build. Ce qui voulait dire tout ce qui se trouvait dans le fichier .env quand l’image avait été construite. Ce qui voulait dire, entre autres, ça :

INFLUXDB_INIT_ADMIN_TOKEN=<influxdb-admin-token>
GF_SECURITY_ADMIN_USER=admin
GF_SECURITY_ADMIN_PASSWORD=admin123
BLACKFIRE_CLIENT_ID=<blackfire-client-id>
BLACKFIRE_CLIENT_TOKEN=<blackfire-client-token>
BLACKFIRE_SERVER_ID=<blackfire-server-id>
BLACKFIRE_SERVER_TOKEN=<blackfire-server-token>
NGROK_AUTHTOKEN=replace-me-optionnal

Vingt-cinq variables au total. Chaque credential accumulé dans le .env racine sur trois ans, désormais permanent dans un layer d’image.

Comment dump-env fonctionne

composer dump-env prod est une optimisation Symfony légitime. Au lieu de parser les fichiers .env à chaque requête, le runtime charge un tableau PHP pré-compilé depuis .env.local.php. Plus rapide et plus simple.

Le problème, c’est ce qu’il lit. Le Dockerfile copie le dépôt dans l’image avec COPY . ./, .env inclus. Ensuite dump-env prod lit ce fichier et compile chaque variable dans .env.local.php. L’image est livrée avec une capture figée des credentials qui se trouvaient dans .env au moment du build.

Les layers Docker sont des archives immuables. Même si une étape ultérieure supprimait .env du système de fichiers du container, le layer qui le contient existerait toujours dans l’image. docker save <image> produit une archive tar de chaque layer ; extraire un fichier spécifique de n’importe quel point de l’historique de build est une opération simple. Les credentials sont invisibles à l’exécution. Ils ne sont pas partis.

Le Facteur V est explicite là-dessus : un artefact de build doit être agnostique à l’environnement, la config arrivant à l’étape de release depuis l’extérieur. Dès que des credentials sont compilés dedans, l’image n’est plus portable. On ne peut plus la promouvoir entre environnements. On builde deux fois en espérant que le deuxième se comporte comme le premier.

Comment vingt-cinq variables s’accumulent

Avant de voir comment on a réparé ça, il vaut la peine de comprendre comment on en est arrivé là.

Les tokens BLACKFIRE_* sont le cas facile à comprendre. Un membre de l’équipe configure le profiling, a besoin de partager la configuration, et le dépôt est déjà ouvert à tout le monde. Une ligne dans .env est la voie de moindre résistance. Les credentials InfluxDB et Grafana suivent la même logique — outillage partagé, dépôt partagé, un commit.

Puis il y a les variables qui révèlent une autre dérive. Dans certains .env de services :

APP__RATINGS__SERIALS='{"marque1":{"fr":"12345"},...}'  # ~40 lignes de JSON
APP__YOUTUBE__CREDENTIALS='{"marque1":{"client_id":"xxx","refresh_token":"yyy"},...}'

Des numéros de série pour la mesure d’audience. Des refresh tokens YouTube par marque. Ce ne sont pas des secrets au sens des tokens Blackfire. Ce sont des données métier — le genre de valeurs qui varient entre marques et environnements, que quelqu’un a décidé de versionner dans .env parce qu’elles se comportaient comme de la configuration et que .env était l’endroit où vivait la configuration.

Vingt-cinq variables, c’est la somme de décisions incrémentales, dont aucune ne semblait fausse isolément. Le problème est structurel : quand .env est la seule réponse disponible, tout finit par y ressembler.

Où les choses appartiennent vraiment

Vider le fichier exigeait de répondre à une question pour chaque variable : où est-ce que ça appartient vraiment ?

Les réponses ont révélé trois catégories que l’équipe n’avait jamais explicitement nommées :

La config statique vit dans le code. Règles métier, logique de routing, fichiers de paramètres Symfony — tout ce qui ne varie pas entre les déploiements. Un changement exige un rebuild. Les blocs JSON de numéros de série se sont révélés ne pas être de la config statique du tout : ils étaient interrogés depuis un service Config dédié à l’exécution. Ils n’avaient rien à faire dans un fichier.

La config environnementale varie entre les déploiements : hostnames, chaînes de connexion, credentials de services tiers. C’est ce que le Facteur III désigne par “config dans les variables d’environnement” — de vraies variables au niveau OS, injectées à l’exécution, jamais des fichiers qui voyagent avec le code. Dans Kubernetes, c’est un ConfigMap pour les valeurs non sensibles et un Kubernetes Secret pour les credentials. Le choix retenu pour les secrets a été SOPS — les credentials sont chiffrés et committés dans git, plutôt que stockés dans un coffre-fort externe comme Azure Key Vault ou HashiCorp Vault. Un coffre-fort échange la simplicité contre l’auditabilité : rotation automatique, logs d’audit centralisés, accès via workload identity sans clé à protéger. SOPS échange ces capacités contre un modèle opérationnel plus simple — pas de service externe à interroger au déploiement, les secrets transitent par le processus de review normal du code, l’historique git fait office de piste d’audit. Les contreparties acceptées sont la rotation manuelle et la responsabilité de protéger la clé de déchiffrement elle-même. Pour la taille de l’équipe, le compromis était délibéré.

La config dynamique change sans déploiement : paramètres éditoriaux, seuils par marque, configuration de modération de contenu. Elle appartient à une base de données, gérée via le service Config de l’application. Une partie de ce qui s’était accumulé dans les .env de services était cette catégorie depuis le début, passant pour des valeurs par défaut statiques parce qu’elle changeait assez rarement pour que personne ne le remarque.

Une fois les catégories nommées, les variables se sont triées. Le .env racine est arrivé à quatre lignes :

DOMAIN=platform.127.0.0.1.sslip.io
XDEBUG_MODE=off
SERVER_NAME=:80
APP_ENV=dev

Des valeurs par défaut sûres. Rien de sensible. dump-env prod compile maintenant des chaînes vides ; les vraies valeurs arrivent à l’exécution depuis Kubernetes.

L’image PostgreSQL

L’image PostgreSQL utilisée en CI a un mot de passe codé en dur :

FROM postgres:15
ENV POSTGRES_PASSWORD=admin123

Ça ressemble au même problème. Ce n’en est pas un, parce que le modèle de menace est différent. La base CI est éphémère — elle existe le temps d’un run de pipeline, ne contient pas de vraies données, tourne dans un réseau isolé. Un mot de passe codé en dur sur une base de test jetable est un risque acceptable, pas une entorse à la règle.

En production, la question ne se pose pas : la plateforme utilise Azure Flexible Server, un service PostgreSQL managé. Il n’y a pas d’image Docker. Les credentials arrivent via injection dans les charts Helm, sans jamais toucher un layer.

Ce qui survit au build maintenant

L’image qui part en production contient maintenant une garantie : var_dump(require '.env.local.php') ne retourne que des chaînes vides et des valeurs par défaut sûres. Les credentials ne sont pas là parce qu’ils n’y ont jamais été mis — ils arrivent à l’exécution, depuis l’extérieur.

C’est la frontière de responsabilité que dump-env avait silencieusement effacée : l’image est l’application, le runtime est l’environnement. Ils ne devraient pas connaître les secrets de l’autre.

Ces lignes se trouvaient dans le .env de production du service media. Pas le staging. Pas un override local. La production, committée dans le dépôt, lue à chaque démarrage.

Les chemins se terminent là où on s’y attendrait : /media, /share_storage. Ils commencent ailleurs : /home/jenkins-slave, le répertoire home d’un runner CI issu d’une ancienne installation Jenkins.

Comment le home d’un runner atterrit dans la config de production

La plateforme avait grandi depuis une seule machine. Un serveur faisait tout tourner — l’application, le runner CI, la base de données, le stockage de fichiers. Les fichiers transitaient entre l’app et le système CI via NFS : un répertoire monté sur le même hôte, accessible aux containers comme au runner.

Le chemin /home/jenkins-slave/share_media était là où le partage NFS atterrissait sur cette machine. Quand l’équipe a migré vers Docker Compose, les containers ont hérité du montage NFS. Le chemin est entré dans le .env parce que l’application devait savoir où trouver les fichiers. Personne ne l’a changé parce que ça marchait. Le montage était toujours là. Le chemin était valide. L’application démarrait. Les fichiers apparaissaient où ils devaient.

Trois ans plus tard, personne n’y pensait plus du tout. C’était juste comme ça que le chemin media était configuré.

Ce que kubectl apply a trouvé

Le premier kubectl apply du service media s’est terminé avec un pod bloqué en CrashLoopBackOff. Le container démarrait. L’entrypoint tournait. L’application essayait d’accéder à /home/jenkins-slave/share_media/media. Fichier ou répertoire inexistant. Pas de montage NFS. Pas de runner.

Le chemin ne documentait pas une décision de design. Il documentait la machine qui tournait par hasard au moment où le .env avait été écrit.

C’est exactement le problème que le Facteur IV de l’application twelve-factor décrit. Les backing services — stockage, files, bases de données — doivent être des ressources attachées, configurées via URL ou chaîne de connexion, interchangeables entre environnements sans toucher au code. Un chemin de fichier sur un hôte partagé n’est pas un backing service. C’est une hypothèse physique sur la machine. Quand la machine change, l’hypothèse lâche.

Le chemin était le symptôme

La première étape évidente était de supprimer la référence au runner :

APP__COLD_STORAGE__FILESYSTEM_PATH="/share_media/media"
APP__SHARE_STORAGE__FILESYSTEM_PATH="/share_storage"

Plus propre. Plus de références CI dans une config de production. Toujours incorrect. L’application supposait encore un système de fichiers POSIX — soit un volume monté, soit un répertoire sur le nœud. Dans Kubernetes, un volume partagé entre plusieurs pods nécessite un PersistentVolumeClaim en mode ReadWriteMany. La plupart des fournisseurs de stockage ne le supportent pas. Ceux qui le font ont tendance à être lents et coûteux. Et même là où ça fonctionne, on a juste remplacé une hypothèse sur le système de fichiers par une autre.

Renommer le chemin gagnait du temps. Ça ne réglait pas le problème.

Le problème, c’est qu’environ douze téraoctets d’images — originaux et déclinaisons pré-générées dans différents formats — pour plusieurs marques éditoriales — étaient traités comme un répertoire. Un répertoire ne se monte pas proprement sur plusieurs pods. Un backing service, si.

Flysystem comme forme de la solution

Le service media avait déjà Flysystem de configuré. Trois adaptateurs concrets — système de fichiers local, AWS S3, Azure Blob — et un adaptateur lazy par-dessus :

# config/packages/flysystem.yaml
flysystem:
    storages:
        media.storage.local:
            adapter: 'local'
            options:
                directory: "/"

        media.storage.aws:
            adapter: 'aws'
            options:
                client: 'aws_client_service'
                bucket: 'media'
                streamReads: true

        media.storage:
            adapter: 'lazy'
            options:
                source: '%env(APP__FLYSYSTEM_MEDIA_STORAGE)%'

Tout le code de l’application dépend de media.storage. Il ne sait pas si les fichiers vivent sur le système de fichiers ou dans un bucket cloud. Une variable d’environnement détermine quel backend est actif :

APP__FLYSYSTEM_MEDIA_STORAGE=media.storage.aws   # production
APP__FLYSYSTEM_MEDIA_STORAGE=media.storage.local  # fallback local toujours disponible

Le chemin est parti. L’hypothèse sur le système de fichiers est partie. Ce qui reste, c’est un nom de service — une ressource attachée au sens twelve-factor, configurable sans rebuilder l’image.

Le même pattern s’étend au cache de vignettes. LiipImagine génère des images redimensionnées à la demande ; les originaux et le cache généré passent par des adaptateurs Flysystem séparés :

liip_imagine:
    loaders:
        default:
            flysystem:
                filesystem_service: 'media.storage'
        default_cache:
            flysystem:
                filesystem_service: 'media.cache.storage'

Deux variables d’environnement, deux buckets. Toute la chaîne — recevoir l’upload, stocker l’original, générer la vignette, la mettre en cache — est portable vers le cloud sans toucher une ligne de PHP.

Ce que l’article ne couvre pas, c’est le déplacement des données. Le lazy adapter change une variable d’environnement. Faire passer douze téraoctets d’un montage NFS vers un bucket S3, c’est un autre projet — une fenêtre de migration, une double-écriture pendant le cutover, une vérification qu’il ne manque rien.

Ce que Minio rend possible en CI

La production utilise S3. Le développement local utilise Minio , un stockage objet compatible S3 qui tourne dans un container Docker. L’adaptateur AWS parle à Minio en local et à S3 en production. L’application ne voit pas la différence :

# local/CI
APP__FLYSYSTEM_MEDIA_STORAGE=media.storage.aws
APP__MINIO_ENDPOINT=http://minio:9000
APP__MINIO_ACCESS_KEY=minioadmin
APP__MINIO_SECRET_KEY=minioadmin

Le même code, le même adaptateur, un endpoint différent. Pas de mock, pas de chemins de test spéciaux, pas de branches conditionnelles par environnement.

Mais la configuration CI va un cran plus loin. L’image Minio utilisée dans le pipeline n’est pas l’image officielle upstream — c’est une image custom buildée avec des fixtures de test préchargées :

FROM minio/minio:latest
COPY tests/fixtures/ /fixtures_media/

Chaque run CI démarre avec une instance Minio qui contient déjà les données attendues par la suite de tests. Pas de script de setup, pas de commande de seed, pas d’étape “attendre le chargement des fixtures” avant que les tests commencent. L’état initial de l’environnement de test fait partie de l’artefact de build.

Le Facteur V appliqué à l’infrastructure de test : l’état de l’environnement est buildé, versionné, immuable. Le pipeline CI construit l’image Minio depuis la même source et au même commit que l’image applicative. Les fixtures de test et le code qui les exploite sont toujours synchronisés.

Le compromis S3, honnêtement

S3 introduit un coût de latence que le stockage local n’a pas. Les premières données d’un fichier prennent 10 à 30 millisecondes à arriver depuis S3 — c’est la latence first-byte documentée du service, pas une mesure sur ce trafic spécifique.

À 300 requêtes par seconde, le raisonnement pour accepter ce compromis était le suivant : la majorité des lectures touche des vignettes déjà générées dans le cache S3, pas les fichiers originaux. Une image fraîchement uploadée paie la pénalité du cold miss une fois, à la première demande de vignette. Tout ce qui suit est un cache hit. Savoir si la latence de queue sous charge réelle confirmait ce raisonnement nécessitait des tests de charge suivis séparément — la décision d’architecture et la validation étaient découplées.

Le compromis a été accepté : comportement prévisible sur plusieurs pods, pas de problèmes d’état partagé, une couche de stockage qui scale sans coordination. L’histoire complète des mesures appartient au rapport de tests de performance, pas ici.

Le fantôme s’en va

Le chemin /home/jenkins-slave n’apparaît plus dans la configuration. Mais ce à quoi il pointait était un couplage qui précédait Docker, précédait les microservices, précédait n’importe quelle conversation sur la migration cloud. Le runner CI et l’application de production partageaient un système de fichiers parce qu’ils vivaient sur la même machine. Personne ne l’avait conçu comme ça. Ça s’était accumulé.

Une erreur kubectl apply sur un chemin qui n’aurait pas dû exister a forcé la question : pourquoi cette application suppose-t-elle qu’un runner CI spécifique est présent sur l’hôte ? La réponse était “parce que ça a toujours été comme ça.” Ce n’est pas une raison. C’est une histoire.

Renommer le chemin était un correctif en carton. L’adaptateur lazy de Flysystem était la vraie réponse — pas parce qu’il est plus élégant, mais parce qu’il fait du backend de stockage une décision qui appartient à l’environnement, pas à l’application. Le container démarre, lit une variable, se connecte à ce qui est à l’autre bout. Il ne sait pas si c’est un bucket dans un datacenter ou un container sur un laptop.

Le répertoire home du runner a disparu de la config. Ce qui l’a remplacé, c’est un nom de service. C’est la différence.

Les objets paresseux natifs

Le système de proxy de Symfony, utilisé pour l’initialisation paresseuse des services et les proxies d’entités de Doctrine, a historiquement reposé sur la génération de code. Les classes proxy étaient générées au cache warmup, stockées sous forme de fichiers, et chargées à la demande. Ça fonctionnait, mais ça ajoutait une vraie complexité : des fichiers générés à gérer, un cache à invalider, du code qui ne ressemblait en rien à la classe qu’il proxyifiait.

PHP 8.4 a ajouté des objets paresseux natifs. Symfony 8.0 les utilise. Le LazyGhostTrait et le LazyProxyTrait qui alimentaient l’ancien système sont supprimés. La création de proxy est maintenant une opération à l’exécution soutenue par le moteur lui-même, pas une étape de génération de code.

Pour les développeurs d’applications, le changement est essentiellement invisible : les services paresseux fonctionnent toujours. Pour les auteurs de frameworks et bibliothèques, une surface significative de complexité vient de disparaître.

FormFlow

Les formulaires multi-étapes ont toujours été un exercice DIY dans Symfony. Gestion de session, suivi des étapes, validation partielle, navigation entre les étapes : chaque projet roulait sa propre solution ou importait un bundle tiers.

8.0 introduit FormFlow : un mécanisme intégré pour les wizards de formulaires multi-étapes. Les étapes sont définies comme une séquence de types de formulaires, la validation partielle est scopée à l’étape courante, et la gestion de session est gérée automatiquement.

#[AsFormFlow]
class CheckoutFlow extends AbstractFormFlow
{
    protected function defineSteps(): Steps
    {
        return Steps::create()
            ->add('shipping', ShippingType::class)
            ->add('payment', PaymentType::class)
            ->add('review', ReviewType::class);
    }
}

La config XML et PHP fluent supprimées

La dépréciation de 7.4 du format de configuration PHP fluent devient une suppression définitive dans 8.0. La configuration XML sort aussi comme format de première classe. Les formats supportés pour la configuration applicative sont maintenant YAML et tableaux PHP. L’empreinte rétrécit, mais ce qui reste est genuinement meilleur.

Ce qui est supprimé d’autre

• Le support PHP 8.2 et 8.3 (8.4 minimum)
• ContainerAwareInterface et ContainerAwareTrait
• L’usage interne de LazyGhostTrait et LazyProxyTrait par Symfony
• La surcharge de méthode HTTP pour GET et HEAD (seul POST a du sens sémantiquement)

Symfony 8.0 est une rupture propre, et ce genre de rupture ne devient possible que quand le plancher PHP s’élève. Les objets paresseux de PHP 8.4 sont l’exemple le plus clair : la fonctionnalité existe maintenant dans le langage, donc le framework peut simplement arrêter de l’implémenter.

Console devient plus ergonomique pour les commandes invocables

Les commandes invocables reçoivent une mise à niveau significative. L’attribut #[Input] transforme un DTO en bag d’arguments/options de la commande. Fini d’appeler $input->getArgument() dans le handler :

#[AsCommand(name: 'app:send-report')]
class SendReportCommand
{
    public function __invoke(
        #[Input] SendReportInput $input,
    ): int {
        // $input->email, $input->dryRun, etc.
        return Command::SUCCESS;
    }
}

BackedEnum est supporté dans les commandes invocables, donc une option déclarée comme enum Status est validée et castée automatiquement. Les commandes interactives reçoivent les attributs #[Interact] et #[Ask] pour déclarer les prompts de questions en ligne. CommandTester fonctionne avec les commandes invocables sans câblage supplémentaire.

Le Routing trouve ses propres contrôleurs

Les routes définies via #[Route] sur les classes de contrôleurs sont auto-enregistrées sans avoir besoin d’une entrée resource: explicite dans config/routes.yaml. Le tag routing.controller est appliqué automatiquement. On contrôle toujours quels répertoires sont scannés, mais la config YAML rétrécit jusqu’à un pointeur vers un répertoire plutôt qu’une liste de fichiers manuelle.

#[Route] reçoit aussi un paramètre _query pour définir des paramètres de query à la génération, et plusieurs environnements dans l’option env.

Sécurité : CSRF et OIDC reçoivent de meilleurs outils

#[IsCsrfTokenValid] reçoit un argument $tokenSource pour spécifier d’où vient le token (header, cookie, champ de formulaire) plutôt que de s’appuyer sur une convention fixe. SameOriginCsrfTokenManager ajoute la validation du header Sec-Fetch-Site, un mécanisme de protection CSRF natif au navigateur qui n’a pas besoin d’injection de token du tout.

La commande security:oidc-token:generate crée des tokens pour tester les endpoints protégés OIDC en local. Plusieurs endpoints de découverte OIDC sont maintenant supportés, utile dans les setups multi-tenant où chaque tenant a son propre identity provider.

Deux nouvelles fonctions Twig : access_decision() et access_decision_for_user() exposent le résultat du voter d’autorisation dans les templates sans passer par la façade de sécurité. #[IsGranted] peut être sous-classé pour les patterns d’autorisation répétés qui méritent leur propre attribut nommé.

ObjectMapper et JsonStreamer sortent d’expérimental

Les deux composants introduits dans 7.x sont stables dans 8.0. ObjectMapper mappe entre objets sans transformateurs écrits à la main, via une configuration basée sur des attributs. JsonStreamer lit et écrit de grands JSON sans charger le document entier en mémoire, et il supporte maintenant les propriétés synthétiques : des champs virtuels calculés à la sérialisation.

JsonStreamer abandonne aussi sa dépendance sur nikic/php-parser. La génération de code pour le reader/writer utilise maintenant un mécanisme interne plus simple, supprimant une lourde dépendance de dev.

Uid par défaut vers UUIDv7

UuidFactory génère maintenant UUIDv7 par défaut au lieu d’UUIDv4. La différence : v7 est ordonné dans le temps, donc les UUIDs générés se trient chronologiquement. Ça compte beaucoup pour la performance des index de base de données. MockUuidFactory fournit une génération déterministe d’UUID dans les tests.

Yaml lève une erreur sur les clés dupliquées

Auparavant, un fichier YAML avec deux clés identiques gardait silencieusement la dernière. 8.0 lève une erreur de parsing. Ça attrape de vrais bugs : les clés dupliquées dans services.yaml ou config/packages/*.yaml sont presque toujours des erreurs de copier-coller et on veut définitivement être informé.

Validator : contrainte Video et protocoles wildcard

Une contrainte Video rejoint la contrainte Image pour valider les fichiers vidéo uploadés (type MIME, durée, codec). La contrainte Url accepte protocols: ['*'] pour autoriser n’importe quel schéma conforme à la RFC 3986, utile pour stocker des URLs arbitraires qui incluent git+ssh://, file://, ou des schémas d’application personnalisés.

Messenger : retry natif SQS et nouveaux événements

Le transport SQS peut maintenant utiliser sa propre configuration native de retry et de dead-letter queue au lieu du middleware de retry de Symfony. Pour les queues à haut volume sur AWS, ça supprime un aller-retour par PHP pour les échecs transitoires. Un MessageSentToTransportsEvent se déclenche après qu’un message est dispatché, portant des informations sur quels transports l’ont réellement reçu.

messenger:consume reçoit --exclude-receivers pour se combiner avec --all.

Mailer : transport Microsoft Graph

Un nouveau transport envoie des emails via l’API Microsoft Graph, ce que Microsoft recommande pour les applications sur Azure Active Directory ces jours-ci. Les autres options (relai SMTP, Exchange EWS) fonctionnent encore, mais Graph est le bon choix pour les nouveaux déploiements Azure.

Workflow : transitions pondérées

Les transitions peuvent maintenant déclarer des poids. Quand plusieurs transitions sont activées depuis la même place, celle avec le poids le plus élevé gagne. Ça permet d’exprimer la priorité directement dans la définition du workflow sans ajouter un guard qui lit un compteur externe.

return (new Definition(states: ['draft', 'review', 'published']))
    ->addTransition(new Transition('publish', 'review', 'published', weight: 10))
    ->addTransition(new Transition('reject', 'review', 'draft', weight: 1));

Lock : LockKeyNormalizer

LockKeyNormalizer normalise une clé de lock vers une string cohérente avant le hachage. Utile quand la clé est dérivée d’entrées utilisateur ou de données externes qui peuvent varier en espaces blancs ou casse : le normalizer s’assure que la même clé logique correspond toujours au même lock.

HttpFoundation : méthode QUERY et parsing de corps plus propre

La méthode IETF QUERY (une méthode sûre et idempotente avec un corps, contrairement à GET) est maintenant supportée partout dans la stack : Request, cache HTTP, WebProfiler et HttpClient. Si on construit des APIs de recherche qui nécessitent un corps de requête structuré et veulent aussi du cache, QUERY est le bon choix sémantique.

Request::createFromGlobals() parse maintenant automatiquement le corps des requêtes PUT, DELETE, PATCH et QUERY.

Config : schéma JSON pour la validation YAML

Symfony 8.0 auto-génère un fichier JSON Schema pour chaque section de configuration. Les IDEs qui supportent JSON Schema pour les fichiers YAML (VS Code, PhpStorm) peuvent maintenant valider config/packages/*.yaml contre ces schémas et fournir de l’autocomplétion sans plugin. Le schéma est généré pendant le cache warmup et placé dans config/reference.php.

Runtime : auto-détection FrankenPHP

Le composant Runtime détecte FrankenPHP automatiquement et active le mode worker sans package supplémentaire ni variable d’environnement. Si $_SERVER['APP_RUNTIME'] est défini, cette classe de runtime a la priorité. On peut aussi choisir le renderer d’erreurs basé sur APP_RUNTIME_MODE, ce qui est utile quand on fait tourner la même codebase dans des contextes HTTP et CLI avec des besoins de présentation d’erreurs différents.

La signature de messages dans Messenger

La sécurité des transports dans Messenger a toujours été le problème de l’application à résoudre. 7.4 ajoute la signature de messages : un mécanisme basé sur des stamps qui signe les messages dispatchés et valide les signatures à la réception.

Le cas d’usage cible est les scénarios multi-tenant ou de transport externe où on a besoin d’une preuve cryptographique qu’un message n’a pas été altéré ni injecté depuis l’extérieur. La configuration vit au niveau du transport :

framework:
    messenger:
        transports:
            async:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                options:
                    signing_key: '%env(MESSENGER_SIGNING_KEY)%'

Configuration en tableaux PHP

Les formats de configuration de Symfony ont toujours été YAML (défaut), XML et PHP. Le format PHP existait mais était maladroit : un DSL builder fluent qui nécessitait du chaînage de méthodes et ne donnait rien d’utile à l’IDE.

7.4 remplace le format fluent par des tableaux PHP standard. Les IDEs peuvent maintenant vraiment l’analyser, config/reference.php est auto-généré comme référence avec annotations de types, et le résultat ressemble à des données plutôt qu’à du code :

return static function (FrameworkConfig $framework): void {
    $framework->router()->strictRequirements(null);
    $framework->session()->enabled(true);
};

Le format fluent est déprécié. Les tableaux sont l’avenir, et honnêtement c’est un meilleur format.

Améliorations OIDC

#[IsSignatureValid] valide les URLs signées directement dans les contrôleurs, supprimant le boilerplate de la validation manuelle. OpenID Connect supporte maintenant plusieurs endpoints de découverte, et une nouvelle commande security:oidc-token:generate rend le dev et les tests beaucoup moins pénibles.

La fenêtre de support

7.4 LTS : bugs jusqu’en novembre 2028, correctifs de sécurité jusqu’en novembre 2029. Le chemin vers 8.4 LTS (la prochaine cible long terme) passe par les notices de dépréciation de 7.4 et la mise à jour PHP 8.4. Corriger les dépréciations maintenant et le saut vers 8.x sera beaucoup moins douloureux.

Les attributs deviennent plus précis

#[CurrentUser] accepte maintenant les types union, ce qui compte en pratique quand une route est accessible par plus d’une classe utilisateur :

public function index(#[CurrentUser] AdminUser|Customer $user): Response

#[Route] accepte un tableau pour l’option env, donc une route de debug active seulement en dev et test n’a plus besoin de deux définitions séparées. #[AsDecorator] est maintenant répétable, ce qui signifie qu’une classe peut décorer plusieurs services à la fois. Les signatures de méthode #[AsEventListener] acceptent les types d’événements union. #[IsGranted] reçoit une option methods pour limiter une vérification d’autorisation à des verbes HTTP spécifiques sans dupliquer la route.

La classe Request arrête d’en faire trop

Request::get() est dépréciée, et franchement bonne débarrassance. La méthode cherchait dans les attributs de route, puis les paramètres de query, puis le corps de la requête, dans cet ordre, retournant silencieusement ce qu’elle trouvait en premier. Cette ambiguïté causait de vrais bugs. Elle est supprimée dans 8.0 ; dans 7.4 elle fonctionne encore mais déclenche une dépréciation. Les remplacements sont explicites : $request->attributes->get(), $request->query->get(), $request->request->get().

Le parsing du corps pour les requêtes PUT, PATCH, DELETE et QUERY arrive en même temps. Auparavant Symfony ne parsait application/x-www-form-urlencoded et multipart/form-data que pour POST. Ces mêmes types de contenu sont maintenant parsés pour les autres méthodes accessibles en écriture aussi, ce qui tue un contournement REST API courant.

La surcharge de méthode HTTP pour GET, HEAD, CONNECT et TRACE est dépréciée. Surcharger une méthode sûre avec un header était de toute façon toujours sémantiquement cassé. On peut maintenant autoriser explicitement seulement les méthodes qui ont du sens pour son application :

Request::setAllowedHttpMethodOverride(['PUT', 'PATCH', 'DELETE']);

Les Workflows acceptent les BackedEnums

Les places et transitions de Workflow peuvent maintenant être définies avec des backed enums PHP, à la fois en YAML (via le tag !php/enum) et en config PHP. Le marking store fonctionne avec les valeurs d’enum directement, donc le modèle de domaine et la définition du workflow utilisent enfin les mêmes types :

framework:
    workflows:
        blog_publishing:
            initial_marking: !php/enum App\Status\PostStatus::Draft
            places: !php/enum App\Status\PostStatus
            transitions:
                publish:
                    from: !php/enum App\Status\PostStatus::Review
                    to: !php/enum App\Status\PostStatus::Published

Étendre la validation et la sérialisation pour les classes tierces

Besoin d’ajouter des métadonnées de validation ou de sérialisation à une classe d’un bundle qu’on ne possède pas ? 7.4 a #[ExtendsValidationFor] et #[ExtendsSerializationFor] pour ça. On écrit une classe compagnon avec ses annotations supplémentaires, on pointe l’attribut vers la classe cible, et Symfony fusionne les métadonnées à la compilation du conteneur :

#[ExtendsValidationFor(UserRegistration::class)]
abstract class UserRegistrationValidation
{
    #[Assert\NotBlank(groups: ['my_app'])]
    #[Assert\Length(min: 3, groups: ['my_app'])]
    public string $name = '';

    #[Assert\Email(groups: ['my_app'])]
    public string $email = '';
}

Symfony vérifie à la compilation que les propriétés déclarées existent réellement sur la classe cible. Un renommage ne cassera pas silencieusement la validation.

DX : ce qui ne fait pas la une mais compte

Le helper Question dans Console accepte un timeout. Demander à l’utilisateur de confirmer quelque chose, et s’il ne répond pas en N secondes, la réponse par défaut s’applique. Très pratique dans les scripts de déploiement qui ne peuvent pas se permettre d’attendre éternellement un humain.

messenger:consume reçoit --exclude-receivers. Combiné avec --all, il permet de consommer depuis tous les transports sauf des spécifiques :

bin/console messenger:consume --all --exclude-receivers=low_priority

Le mode worker FrankenPHP est maintenant auto-détecté. Si le processus tourne dans FrankenPHP, Symfony bascule en mode worker automatiquement. Pas de package supplémentaire nécessaire.

La commande debug:router cache les colonnes Scheme et Host quand toutes les routes utilisent ANY, ce qui supprime beaucoup de bruit de la sortie par défaut. Les méthodes HTTP sont maintenant aussi colorées.

Les tests fonctionnels reçoivent $client->getSession() avant la première requête. Auparavant il fallait faire au moins une requête pour accéder à la session, ce qui était agaçant. Maintenant on peut pré-remplir les tokens CSRF ou les flags A/B en amont :

$session = $client->getSession();
$session->set('_csrf/checkout', 'test-token');
$session->save();

Lock : store DynamoDB

DynamoDbStore arrive comme nouveau backend de Lock. Utile dans les déploiements AWS-natifs où Redis n’est pas dans la stack, et ça fonctionne exactement comme n’importe quel autre store :

$store = new DynamoDbStore('dynamodb://default/locks');
$factory = new LockFactory($store);

Bridge Doctrine : types day point et time point

Deux nouveaux types de colonnes Doctrine : day_point stocke une valeur date uniquement (sans composant heure) et time_point stocke une valeur heure uniquement, tous deux mappant vers DatePoint. Bien quand le domaine sépare genuinement la date de l’heure :

#[ORM\Column(type: 'day_point')]
public DatePoint $birthDate;

#[ORM\Column(type: 'time_point')]
public DatePoint $openingTime;

Routing : paramètres de query explicites

La clé _query dans la génération d’URL permet de définir les paramètres de query explicitement, séparément des paramètres de route. Ça compte quand un paramètre de route et un paramètre de query partagent le même nom :

$url = $urlGenerator->generate('report', [
    'site' => 'fr',
    '_query' => ['site' => 'us'],
]);
// /report/fr?site=us

WebLink : parsing des en-têtes Link entrants

HttpHeaderParser parse les en-têtes de réponse Link en objets structurés. Avant ça, parser des en-têtes Link depuis des réponses d’API nécessitait soit d’importer une bibliothèque tierce, soit d’écrire des regex. Le cas d’usage : les APIs HTTP qui annoncent des ressources liées ou la pagination via des en-têtes Link, comme le fait l’API GitHub.

Le parsing HTML5 est plus rapide sur PHP 8.4

DomCrawler et HtmlSanitizer basculent vers le parser HTML5 natif de PHP 8.4 quand il est disponible. Pas de changements de code nécessaires de votre côté. Le parser natif est plus rapide et plus conforme à la spec que le fallback précédent. Sur PHP 8.2 ou 8.3, rien ne change.

Translation : StaticMessage

StaticMessage implémente TranslatableInterface mais ne traduit intentionnellement pas. Elle passe la string inchangée quelle que soit la locale. Le cas d’usage : les réponses d’API qui doivent rester dans une langue fixe quelle que soit la locale de l’utilisateur, ou les entrées de log d’audit où on doit préserver le texte original tel quel.

L’opérateur pipe

Les pipelines fonctionnels en PHP ont toujours été un bazar. Enchaîner des transformations nécessitait soit d’imbriquer les appels de fonctions à l’envers, soit de les découper en variables intermédiaires :

// avant — se lit de droite à gauche
$result = array_sum(array_map('strlen', array_filter($strings, 'strlen')));

// ou verbeux mais lisible
$filtered   = array_filter($strings, 'strlen');
$lengths    = array_map('strlen', $filtered);
$result     = array_sum($lengths);

// après — se lit de gauche à droite
$result = $strings
    |> array_filter(?, 'strlen')
    |> array_map('strlen', ?)
    |> array_sum(?);

L’opérateur |> passe la valeur de gauche dans l’expression de droite. Le placeholder ? marque où elle va. Les pipelines se lisent maintenant dans l’ordre où les opérations se produisent : gauche à droite, haut en bas.

Ça se marie bien avec les callables de première classe de PHP 8.1. Les deux fonctionnalités se composent bien :

$result = $input |> trim(...) |> strtolower(...) |> $this->normalize(...);

L’extension URI

Gérer les URIs en PHP a toujours signifié soit se tourner vers une bibliothèque tierce, soit assembler parse_url() (retourne un tableau, pas un objet), http_build_query(), et de la concaténation manuelle de strings.

La nouvelle extension Uri donne une vraie API orientée objet :

$uri = Uri\Uri::parse('https://example.com/path?query=value#fragment');
$modified = $uri->withPath('/new-path')->withQuery('key=val');
echo $modified; // https://example.com/new-path?key=val#fragment

Des objets-valeur immutables, un parsing conforme aux RFC, modifier des composants individuels sans parser et reconstruire la string entière. Attendu depuis longtemps.

#[\NoDiscard]

Un nouvel attribut qui génère un avertissement quand la valeur de retour est ignorée :

#[\NoDiscard("Use the returned collection, the original is unchanged")]
public function filter(callable $fn): static { ... }

Utile pour les méthodes immutables où ignorer la valeur de retour est presque certainement un bug. Courant dans d’autres langages depuis des années, maintenant en PHP où ça appartient.

clone with

Cloner un objet avec des propriétés modifiées sans utiliser de property hooks ni une méthode with() personnalisée :

$updated = clone($point) with { x: 10, y: 20 };

Syntaxe propre pour un pattern que les objets readonly nécessitaient : on clone pour “modifier” puisque la mutation directe n’est pas permise.

PHP 8.5 a une tendance fonctionnelle. L’opérateur pipe et l’extension URI ensemble rendent le code de transformation de données significativement plus lisible. Le langage continue dans une direction cohérente.

Les closures dans les expressions constantes

Une contrainte qui existait depuis PHP 5 : les expressions constantes (arguments d’attributs, valeurs par défaut de propriétés, valeurs par défaut de paramètres, déclarations const) ne pouvaient pas contenir de closures ni de callables de première classe. 8.5 supprime ça.

#[Validate(fn($v) => $v > 0)]
public int $count = 0;

const NORMALIZER = strtolower(...);

class Config {
    public function __construct(
        public readonly Closure $transform = trim(...),
    ) {}
}

C’est la pièce manquante qui rend les attributs vraiment expressifs pour les règles de validation et de transformation. Avant 8.5, il fallait passer des noms de classes ou des références string aux attributs et laisser le framework les retrouver. Maintenant le callable vit directement dans l’attribut.

Les attributs sur les constantes

L’attribut #[\Deprecated] de 8.4 ne pouvait pas être appliqué aux déclarations const. 8.5 ajoute le support des attributs pour les constantes en général :

const OLD_LIMIT = 100;

#[\Deprecated('Use RATE_LIMIT instead', since: '3.0')]
const API_TIMEOUT = 30;

const RATE_LIMIT = 60;

ReflectionConstant, une nouvelle classe de réflexion dans 8.5, expose getAttributes() pour que les outils puissent les lire. Combiné avec les closures dans les expressions constantes, les attributs sur les constantes deviennent une vraie couche de métadonnées pour les valeurs à la compilation.

#[\Override] s’étend aux propriétés

PHP 8.3 a apporté #[\Override] pour les méthodes. 8.5 l’étend aux propriétés :

class Base {
    public string $name = 'default';
}

class Derived extends Base {
    #[\Override]
    public string $name = 'derived';
}

Si la propriété n’existe pas dans le parent, PHP lève une erreur. Particulièrement utile avec les property hooks de 8.4 : on peut maintenant signaler qu’une propriété hookée surcharge intentionnellement celle d’un parent.

La visibilité asymétrique statique

8.4 a introduit la visibilité asymétrique (public private(set)) pour les propriétés d’instance. 8.5 l’apporte aussi aux propriétés static :

class Registry {
    public static private(set) array $items = [];

    public static function register(string $key, mixed $value): void {
        self::$items[$key] = $value;
    }
}

echo Registry::$items['foo']; // lisible
Registry::$items['bar'] = 1; // Error: cannot write outside class

Pattern direct : exposer une collection statique en lecture, bloquer la mutation externe.

La promotion de constructeur pour les propriétés final

La promotion de propriétés dans les constructeurs existe depuis PHP 8.0. Le modificateur final sur les propriétés promuées était la pièce manquante, 8.5 l’ajoute :

class ValueObject {
    public function __construct(
        public final readonly string $id,
        public final readonly string $name,
    ) {}
}

Une sous-classe ne peut pas surcharger $id ni $name avec une propriété du même nom. La combinaison final readonly sur les propriétés promuées rend les objets-valeur aussi verrouillés que possible sans sceller la classe entière.

Les casts dans les expressions constantes

Autre lacune dans les expressions constantes : pas de casts de type. 8.5 les permet :

const PRECISION = (int) 3.7;      // 3
const THRESHOLD = (float) '1.5';  // 1.5
const FLAG = (bool) 1;            // true

Ça semble mineur jusqu’à ce qu’on ait des constantes de configuration dérivées de variables d’environnement qui nécessitent une coercition de type directement à la déclaration.

Les erreurs fatales incluent les backtraces

Avant 8.5, une erreur fatale (mémoire insuffisante, dépassement de pile, erreur de type dans certains contextes) produisait un message sans contexte sur où dans le code ça s’est passé. Trouver la cause signifiait insérer des logs de debug et reproduire.

8.5 ajoute des backtraces à la stack aux messages d’erreur fatale, dans le même format que les backtraces d’exceptions. Une nouvelle directive INI, fatal_error_backtraces, contrôle le comportement. Elle est activée par défaut.

array_first() et array_last()

PHP avait reset() et end() pour accéder au premier et dernier élément d’un tableau depuis PHP 3. Les deux mutent le pointeur interne du tableau (pas sûr à appeler sur une référence), et ils retournent false pour les tableaux vides d’une façon indiscernable d’une valeur false stockée.

$values = [10, 20, 30];

$first = array_first($values);  // 10
$last  = array_last($values);   // 30

$first = array_first([]);       // null

Les nouvelles fonctions retournent null pour les tableaux vides, ne touchent pas le pointeur interne, et fonctionnent sur n’importe quelle expression de tableau sans avoir besoin d’une variable. reset($this->getItems()) était un avertissement de dépréciation en attente de se produire.

get_error_handler() et get_exception_handler()

PHP a set_error_handler() et set_exception_handler(). Obtenir le handler courant nécessitait soit de le stocker soi-même avant de le définir, soit d’appeler set_error_handler(null) et de capturer ce qui revenait, ce qui effaçait aussi le handler au passage.

8.5 ajoute :

$current = get_error_handler();
$current = get_exception_handler();

Pratique dans les chaînes de middleware où on veut envelopper le handler existant sans le perdre, ou dans les tests où on veut vérifier qu’un handler a bien été installé.

IntlListFormatter

Formater une liste avec les conjonctions appropriées à la locale nécessitait toujours un assemblage manuel de strings. 8.5 ajoute IntlListFormatter :

$formatter = new IntlListFormatter('en_US', IntlListFormatter::TYPE_AND);
echo $formatter->format(['apples', 'oranges', 'pears']);
// "apples, oranges, and pears"

$formatter = new IntlListFormatter('fr_FR', IntlListFormatter::TYPE_OR);
echo $formatter->format(['rouge', 'bleu', 'vert']);
// "rouge, bleu ou vert"

La classe enveloppe le ListFormatter d’ICU. Trois types : TYPE_AND, TYPE_OR, TYPE_UNITS. Les constantes de largeur contrôlent si on obtient “et” ou “&”. Gestion de la virgule d’Oxford, placement de conjonction spécifique à la locale, tout géré par ICU.

FILTER_THROW_ON_FAILURE pour filter_var()

filter_var() retourne false en cas d’échec de validation, ce qui produit l’ambiguïté classique false vs null vs 0 quand on filtre des entrées non fiables. Un nouveau flag change ça :

try {
    $email = filter_var($input, FILTER_VALIDATE_EMAIL, FILTER_THROW_ON_FAILURE);
} catch (Filter\FilterFailedException $e) {
    // explicitement invalide, pas faussement false
}

Les classes Filter\FilterFailedException et Filter\FilterException sont nouvelles dans 8.5. Le flag ne peut pas être combiné avec FILTER_NULL_ON_FAILURE : les comportements sont mutuellement exclusifs.

Les dépréciations qui nettoient des années de dette technique

L’opérateur backtick (`commande` comme alias de shell_exec()) est déprécié. C’est une syntaxe obscure qui surprend quiconque lit le code et est incohérente avec tous les autres appels de fonctions PHP.

Les noms de cast non canoniques ((boolean), (integer), (double), (binary)) sont dépréciés au profit de leurs formes courtes : (bool), (int), (float), (string). Les formes longues sont non documentées depuis des années ; 8.5 commence la suppression formelle.

Les instructions case terminées par un point-virgule sont dépréciées :

// déprécié
switch ($x) {
    case 1;
        break;
}

// correct
switch ($x) {
    case 1:
        break;
}

La forme avec point-virgule est syntaxiquement valide depuis PHP 4 mais personne ne l’utilise intentionnellement. C’est une faute de frappe que PHP acceptait.

__sleep() et __wakeup() sont dépréciés au profit de __serialize() et __unserialize(), qui retournent et reçoivent des tableaux et se composent correctement avec l’héritage. Les anciennes méthodes avaient une sémantique confuse autour de la visibilité des propriétés.

max_memory_limit plafonne les allocations incontrôlées

Une nouvelle directive INI accessible seulement au démarrage : max_memory_limit. Elle définit un plafond que memory_limit ne peut pas dépasser à l’exécution. Si un script appelle ini_set('memory_limit', '10G') et que max_memory_limit est à 512M, PHP avertit et plafonne la valeur.

Utile dans les environnements d’hébergement partagé, ou partout où on veut s’assurer qu’un bug ou un payload malveillant ne peut pas convaincre PHP d’élever sa propre limite et de dévorer toute la RAM de la machine.

Opcache est toujours présent

Dans 8.5, Opcache est toujours compilé dans le binaire PHP et toujours chargé. L’ancienne situation (Opcache comme extension chargeable qui pouvait ou non être présente selon la configuration de build) est révolue.

On peut toujours le désactiver : opcache.enable=0 fonctionne bien. Ce qui change, c’est la garantie que l’API Opcache (opcache_get_status(), opcache_invalidate(), etc.) est toujours disponible, quelle que soit la façon dont PHP a été compilé. Tout code qui vérifie extension_loaded('opcache') avant d’appeler les fonctions Opcache peut supprimer la vérification.

JSON streamer pour les grandes collections

Le serializer Symfony par défaut construit la réponse complète en mémoire avant de l’écrire dans la sortie. Pour une collection de 10 000 éléments, cela signifie allouer un tableau PHP, le sérialiser en string, et garder les deux en mémoire jusqu’au flush de la réponse. À grande échelle, c’est la source des erreurs OOM qui forcent à ajouter de la pagination partout.

La 4.2 ajoute un encodeur JSON en streaming qui écrit la réponse de façon incrémentale :

api_platform:
    serializer:
        enable_json_streamer: true

Avec le streaming activé, la réponse est écrite directement dans le buffer de sortie au fur et à mesure que chaque élément est sérialisé. L’utilisation mémoire reste approximativement constante quelle que soit la taille de la collection. La contrepartie : on ne peut pas définir de headers de réponse après le début du streaming, et le code de statut HTTP doit être validé avant que le premier octet soit écrit.

ObjectMapper remplace le câblage DTO manuel

La 3.1 avait introduit stateOptions avec DoctrineOrmOptions pour séparer la ressource API de l’entité Doctrine. Le provider recevait des objets entité et le serializer les mappait sur le DTO. Ça fonctionnait, mais le mapping était implicite — le serializer utilisait les noms de propriétés pour faire correspondre les champs, et tout ce qui ne correspondait pas était soit ignoré soit causait une erreur de normalisation.

La 4.2 introduit ObjectMapper, une couche de mapping déclarative entre entités et DTOs :

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    public string $title;
    public string $authorName;
}

L’attribut #[Map] indique à ObjectMapper que BookDto peut être peuplé depuis BookEntity. Les noms de champs sont mis en correspondance par convention ; les inadéquations sont déclarées explicitement au niveau de chaque propriété :

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    #[Map(source: 'author.fullName')]
    public string $authorName;
}

La notation pointée traverse les objets imbriqués. Le mapping s’exécute avant la sérialisation et remplace le comportement implicite de correspondance de propriétés du serializer. Les champs non mappés lèvent une erreur au moment de la configuration, pas à l’exécution.

ObjectMapper fonctionne avec stateOptions :

use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use Symfony\Component\ObjectMapper\Attribute\Map;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
#[Map(source: BookEntity::class)]
class BookDto {}

Le provider récupère les objets BookEntity depuis Doctrine. ObjectMapper les convertit en instances BookDto. Le serializer écrit le DTO. Trois étapes distinctes, chacune avec un contrat clair.

Intégration TypeInfo dans toute la pile

Symfony 7.1 a introduit le composant TypeInfo , une couche unifiée d’introspection des types qui comprend les types union, intersection, les collections génériques et les types nullable à travers la reflection, PHPDoc et la syntaxe PHP 8.x.

La 4.2 remplace la résolution de types interne d’API Platform par TypeInfo. Cela affecte la génération de schémas de filtres, l’inférence de schéma OpenAPI, et la coercition de types du serializer. Le bénéfice visible est que les types qui généraient auparavant des schémas OpenAPI incorrects ou manquants — Collection<int, Book>, list<string>, types intersection — produisent maintenant des schémas précis sans annotations @ApiProperty manuelles.

Autoconfigure #[ApiResource]

Avant la 4.2, ajouter #[ApiResource] à une classe suffisait pour qu’Hugo la découvre uniquement si la classe était dans un chemin scanné par le chargeur de ressources d’API Platform. En dehors de ce chemin, une configuration de service explicite était nécessaire.

La 4.2 se branche sur le système d’autoconfigure de Symfony. Toute classe taguée avec #[ApiResource] est automatiquement enregistrée comme ressource indépendamment de son emplacement, tant qu’elle est dans un répertoire couvert par le scan de composants de Symfony. Aucune entrée dans config/services.yaml nécessaire.

Pour Laravel, l’équivalent utilise l’autoloading du service provider de Laravel — les modèles Eloquent avec #[ApiResource] sont récupérés automatiquement sans enregistrement manuel.

Doctrine ExistsFilter

L’ExistsFilter contraint une collection selon qu’une relation ou un champ nullable est défini :

#[ApiFilter(ExistsFilter::class, properties: ['publishedAt'])]
class Book {}

GET /books?exists[publishedAt]=true retourne les livres où publishedAt n’est pas null. exists[publishedAt]=false retourne les livres où il l’est.

Validation stricte des paramètres de requête

La 3.3 avait introduit la validation des paramètres de requête en opt-in. La 3.4 avait déprécié le comportement permissif. La 4.1 la formalise avec une propriété native strictQueryParameterValidation sur les ressources et opérations : quand elle est à true, les paramètres de requête inconnus renvoient 400.

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    strictQueryParameterValidation: true,
    parameters: [
        new QueryParameter(key: 'utm_source', required: false, schema: ['type' => 'string']),
        new QueryParameter(key: 'feature_flag', required: false, schema: ['type' => 'string']),
    ]
)]
class Book {}

Les paramètres déclarés passent ; les paramètres non déclarés sont rejetés. Pour désactiver la validation stricte sur une opération spécifique quand elle est activée au niveau de la ressource, passer strictQueryParameterValidation: false sur cette opération.

x-apiplatform-tag pour OpenAPI multi-spec

Les grandes APIs ont souvent besoin de plusieurs specs OpenAPI : une par équipe, une par version d’API, une interne et une publique. Avant la 4.1, la spec générée était un seul document, et la diviser nécessitait un post-traitement ou des instances API Platform séparées.

La 4.1 ajoute une extension vendor x-apiplatform-tag (sans s final). On tague les opérations avec des noms de groupes logiques via les extensionProperties d’un objet Operation OpenAPI, puis on demande la spec filtrée sur un ou plusieurs groupes :

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\OpenApi\Factory\OpenApiFactory;
use ApiPlatform\OpenApi\Model\Operation;

#[GetCollection(
    openapi: new Operation(
        extensionProperties: [OpenApiFactory::API_PLATFORM_TAG => ['public', 'v2']]
    )
)]
class Book {}

Demander /api/docs.json?filter_tags[]=public retourne uniquement les opérations taguées public. La spec complète reste disponible sans filtre. Les groupes n’affectent pas le comportement réel de l’API — c’est uniquement une préoccupation de couche documentation.

Cela rend faisable de maintenir une configuration API Platform unique tout en servant différentes vues de spec à différents consommateurs : un Swagger UI public, un portail partenaire, et un outil interne qui expose les endpoints d’administration.

Authentification HTTP dans Swagger UI

Avant la 4.1, le Swagger UI fourni avec API Platform supportait l’authentification par token Bearer via son dialogue “Authorize”. L’authentification par clé API et HTTP Basic n’étaient pas câblées.

La 4.1 ajoute le support de plusieurs schémas de sécurité dans le document OpenAPI généré. Les schémas de sécurité sont ajoutés en décorant l’OpenApiFactory et en modifiant l’objet components.securitySchemes de la spec. Chaque schéma déclaré apparaît ensuite dans le dialogue “Authorize” de Swagger UI et est appliqué aux requêtes faites depuis l’UI. C’est une amélioration de la documentation et de l’expérience développeur — la logique d’authentification réelle dans votre application n’est pas affectée.

Limites de profondeur et complexité des requêtes GraphQL

La structure de requête récursive de GraphQL rend triviale la construction d’une requête petite en octets mais énorme en coût d’exécution. Sans limites, une requête imbriquée sur quatre niveaux à travers une relation many-to-many peut frapper la base de données des centaines de fois.

La 4.1 ajoute des limites configurables de profondeur et complexité :

api_platform:
    graphql:
        max_query_depth: 10
        max_query_complexity: 100

max_query_depth est le niveau d’imbrication maximum. max_query_complexity assigne un coût à chaque champ et rejette les requêtes dont le coût total dépasse le seuil. Les requêtes qui dépassent l’une ou l’autre limite sont rejetées avant exécution avec une réponse 400.

Il n’y a pas de valeur universellement correcte pour ces limites — elles dépendent de la forme de votre schéma et des patterns de requête attendus. Les valeurs par défaut sont intentionnellement permissives pour éviter de casser des APIs existantes lors de la mise à jour. Les resserrer est un choix de configuration délibéré.

Formats de sortie au niveau opération

La 4.0 et les versions antérieures configuraient les types de contenu acceptés et retournés au niveau de l’API. La 4.1 permet de les restreindre par opération :

use ApiPlatform\Metadata\GetCollection;

#[GetCollection(
    outputFormats: ['jsonld' => ['application/ld+json']],
    inputFormats: ['json' => ['application/json']],
)]
class Book {}

Les opérations qui ne spécifient pas de formats héritent de la configuration au niveau de l’API. C’est utile pour les endpoints qui doivent retourner un format spécifique (une export CSV, un flux binaire) sans changer les défauts pour le reste de l’API.

PostgreSQL embarque une recherche full-text depuis plus de quinze ans. La plateforme tournait déjà sous PostgreSQL. Le hic: le projet utilise Doctrine ORM, et Doctrine ne sait pas nativement ce qu’est un tsvector.

Une bibliothèque communautaire, postgresql-for-doctrine, couvre une partie de cette lacune. Elle enregistre des fonctions DQL basiques comme TO_TSQUERY, TO_TSVECTOR, et l’opérateur de correspondance @@ en tant que pièces atomiques séparées. La fondation était là. Trois choses restaient à construire par-dessus.

Le type que Doctrine n’a jamais vu

La recherche full-text de PostgreSQL repose sur deux types: tsvector (une liste pré-traitée de tokens normalisés) et tsquery (une expression de recherche). On maintient une colonne tsvector, on l’indexe avec GIN, et on interroge avec l’opérateur @@.

Le DBAL de Doctrine ne livre aucun type tsvector. Déclarer #[ORM\Column(type: 'tsvector')] sans l’enregistrer au préalable lève une UnknownColumnTypeException. La solution: un type DBAL personnalisé:

class TsVector extends Type
{
    final public const string DBAL_TYPE = 'tsvector';

    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        return self::DBAL_TYPE;
    }

    public function getName(): string
    {
        return self::DBAL_TYPE;
    }

    public function convertToDatabaseValueSQL(string $sqlExpr, AbstractPlatform $platform): string
    {
        return sprintf("to_tsvector('simple', %s)", $sqlExpr);
    }

    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): mixed
    {
        if (is_array($value) && isset($value['data'])) {
            return $value['data'];
        }

        return is_string($value) ? $value : null;
    }

    public function getMappedDatabaseTypes(AbstractPlatform $platform): array
    {
        return [self::DBAL_TYPE];
    }
}

La méthode intéressante est convertToDatabaseValueSQL(). Doctrine l’appelle pour envelopper le placeholder SQL avant que la valeur n’atteigne la base de données. La valeur écrite devient automatiquement to_tsvector('simple', ?) à la frontière DBAL, sans étape supplémentaire côté appelant.

On enregistre le type dans doctrine.yaml, puis on mappe la colonne sur l’entité:

doctrine:
    dbal:
        types:
            tsvector: App\Doctrine\DBAL\Types\TsVector

#[ORM\Column(type: 'tsvector', nullable: true)]
protected ?string $textSearch = null;

Côté PHP, la valeur est une simple chaîne. La conversion en vrai tsvector se fait invisiblement au niveau DBAL.

Nous avons utilisé le dictionnaire 'simple', qui tokenise sur les espaces et la ponctuation sans stemming spécifique à une langue. La plateforme gère plusieurs langues, et les règles de stemming français auraient cassé l’espagnol. Simple suffit largement pour la phonétique.

Garder la colonne à jour

Une colonne tsvector est une donnée dérivée: elle doit rester synchronisée avec les champs source chaque fois que l’entité change. Un event listener Doctrine s’en charge:

#[AsDoctrineListener(event: Events::prePersist)]
#[AsDoctrineListener(event: Events::preUpdate)]
class MediaTsVectorSubscriber
{
    public function prePersist(PrePersistEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    public function preUpdate(PreUpdateEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    private function updateTextSearch(Media $entity): void
    {
        $entity->setTextSearch(
            sprintf('%s %s', $entity->getTitle(), $entity->getCaption())
        );
    }
}

Avant chaque persist et update, le subscriber concatène les champs qui doivent être recherchables dans textSearch. Doctrine flush la chaîne combinée, le type DBAL l’enveloppe dans to_tsvector('simple', ...), et PostgreSQL stocke la forme tokenisée.

Une subtilité: la valeur côté PHP est "title caption", pas la sortie tsvector réelle. La base affiche 'caption' 'title' (tokens triés), mais l’entité contient une chaîne brute. C’est attendu: la conversion est une responsabilité DBAL, pas PHP. Ça peut dérouter le débogage jusqu’à ce qu’on se souvienne où se situe la frontière.

Étendre DQL avec les opérateurs FTS

Le DQL de Doctrine couvre les opérations SQL courantes, mais tout ce qui est spécifique à PostgreSQL est hors périmètre. C’est là que postgresql-for-doctrine entre en jeu: il enregistre TO_TSQUERY, TO_TSVECTOR, et TSMATCH comme fonctions DQL individuelles. Écrire une requête full-text en DQL sans lui signifierait basculer en SQL natif.

Les fonctions de la bibliothèque sont atomiques, cependant. Chacune correspond à un appel SQL. Exprimer une vérification de correspondance complète en DQL ressemble à TSMATCH(o.textSearch, TO_TSQUERY(:term)). Assez lisible, mais l’équipe voulait quelque chose de plus compact: une seule fonction DQL encodant à la fois l’opérateur de correspondance et le type de requête, y compris websearch_to_tsquery que postgresql-for-doctrine ne fournissait pas.

La solution: des fonctions DQL personnalisées via FunctionNode. On parse la syntaxe DQL, puis on émet du SQL. Toutes les fonctions FTS partagent la même signature à deux arguments, donc une classe abstraite de base gère le parsing:

abstract class TsFunction extends FunctionNode
{
    public PathExpression|Node|null $ftsField = null;
    public PathExpression|Node|null $queryString = null;

    public function parse(Parser $parser): void
    {
        $parser->match(TokenType::T_IDENTIFIER);
        $parser->match(TokenType::T_OPEN_PARENTHESIS);
        $this->ftsField = $parser->StringPrimary();
        $parser->match(TokenType::T_COMMA);
        $this->queryString = $parser->StringPrimary();
        $parser->match(TokenType::T_CLOSE_PARENTHESIS);
    }
}

Chaque classe concrète implémente getSql() pour émettre son expression PostgreSQL:

// e.textSearch @@ websearch_to_tsquery('simple', :term)
class TsWebsearchQueryFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return $this->ftsField->dispatch($sqlWalker)
            ." @@ websearch_to_tsquery('simple', "
            .$this->queryString->dispatch($sqlWalker).')';
    }
}

// ts_rank(e.textSearch, to_tsquery(:term)) pour le tri par pertinence
class TsRankFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ts_rank('
            .$this->ftsField->dispatch($sqlWalker)
            .', to_tsquery('.$this->queryString->dispatch($sqlWalker).'))';
    }
}

doctrine:
    orm:
        entity_managers:
            default:
                dql:
                    string_functions:
                        tswebsearchquery: App\Doctrine\ORM\Query\AST\Functions\TsWebsearchQueryFunction
                        tsrank: App\Doctrine\ORM\Query\AST\Functions\TsRankFunction
                        tsquery: App\Doctrine\ORM\Query\AST\Functions\TsQueryFunction
                        tsplainquery: App\Doctrine\ORM\Query\AST\Functions\TsPlainQueryFunction

websearch_to_tsquery est le bon choix pour la recherche côté utilisateur: les espaces deviennent des AND, les chaînes entre guillemets deviennent des phrases, -mot exclut un terme. Inutile d’apprendre aux utilisateurs à taper interview & président. C’est disponible depuis PostgreSQL 11. Sur les versions antérieures, plainto_tsquery est l’équivalent le plus proche.

Le filtre API Platform et l’index GIN

Avec les fonctions DQL enregistrées, le filtre API Platform est simple. Un AbstractFilter personnalisé appelle directement la fonction DQL dans le QueryBuilder:

class TextSearchFilter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        $value,
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = []
    ): void {
        if ('textSearch' !== $property || empty($value)) {
            return;
        }

        $queryBuilder
            ->andWhere('tswebsearchquery(o.textSearch, :value) = true')
            ->setParameter(':value', $value);
    }

    public function getDescription(string $resourceClass): array
    {
        return [];
    }
}

On l’applique sur l’entité avec la déclaration d’index:

#[ORM\Index(
    columns: ['text_search'],
    name: 'media_text_search_idx_gin',
    options: ['USING' => 'gin (text_search)']
)]
#[ApiFilter(TextSearchFilter::class, properties: ['textSearch' => 'partial'])]
class Media
{
    // ...
    #[ORM\Column(type: 'tsvector', nullable: true)]
    protected ?string $textSearch = null;
}

L’option USING gin n’est pas négociable. Un index B-tree standard sur une colonne tsvector est inutile: PostgreSQL ne peut pas l’utiliser pour les requêtes @@. GIN (Generalized Inverted Index) fonctionne différemment: il indexe chaque token individuellement, donc les recherches par n’importe quel token sont en O(log n) plutôt que O(n). Sans ça, on a construit un système qui donne l’impression d’être rapide mais qui fait quand même un full table scan.

Un GET /media?textSearch=interview+president touche maintenant l’index GIN et répond en quelques millisecondes quel que soit la taille de la table.

Ce que la répartition ressemblait vraiment

La bibliothèque couvrait les fonctions atomiques bas niveau. Le code personnalisé couvrait les lacunes: un type DBAL tsvector que la bibliothèque ne fournissait pas, des wrappers DQL pratiques combinant @@ et websearch_to_tsquery en un seul appel, et la colle applicative reliant tout ça au système d’événements de Doctrine et à API Platform. Aucune requête native n’a été nécessaire.

La répartition vaut d’être notée en général: postgresql-for-doctrine donne les briques atomiques PostgreSQL, mais il faut quand même les composer en quelque chose que le reste du code peut utiliser sans y penser. Le pattern FunctionNode et le hook convertToDatabaseValueSQL() sont les deux points d’extension qui rendent cette composition propre. Les deux valent d’être connus, quelle que soit la bibliothèque de départ.

Les property hooks

Pendant vingt ans, si on voulait du comportement à l’accès d’une propriété en PHP, il fallait écrire des getters et setters :

class User {
    private string $_name;
    
    public function getName(): string { return $this->_name; }
    public function setName(string $name): void {
        $this->_name = strtoupper($name);
    }
}

PHP 8.4 ajoute des hooks directement sur la propriété :

class User {
    public string $name {
        set(string $name) {
            $this->name = strtoupper($name);
        }
    }
}

On peut définir les hooks get et set indépendamment. Une propriété avec seulement un hook get est calculée à l’accès :

class Circle {
    public float $area {
        get => M_PI * $this->radius ** 2;
    }
    
    public function __construct(public float $radius) {}
}

Pas de stockage backing, pas de méthode getter explicite, support IDE complet. Les interfaces peuvent aussi déclarer des propriétés avec des hooks, ce qui signifie que les contrats peuvent maintenant spécifier un comportement à l’accès aux propriétés, quelque chose qui était tout simplement impossible avant.

La visibilité asymétrique

Une option plus légère pour quand on veut juste une lecture publique et une écriture privée :

class Version {
    public private(set) string $value = '1.0.0';
}

$v = new Version();
echo $v->value;      // fonctionne
$v->value = '2.0';  // Error

Élimine le pattern private $x + public getX() pour les propriétés publiques en lecture seule sans avoir besoin de la sémantique readonly complète.

array_find() et amis

$first = array_find($users, fn($u) => $u->isActive());
$any   = array_any($users, fn($u) => $u->isPremium());
$all   = array_all($users, fn($u) => $u->isVerified());

Ces fonctions existent dans la bibliothèque standard de chaque autre langage depuis des décennies. En PHP, il fallait utiliser array_filter() + accès par index ou écrire une boucle manuelle. Elles existent maintenant : array_find(), array_find_key(), array_any(), array_all().

Instanciation sans parenthèses supplémentaires

// avant
(new MyClass())->method();

// après
new MyClass()->method();

Une restriction syntaxique qui était toujours agaçante et jamais justifiée est supprimée.

Les objets paresseux

Des objets dont l’initialisation est différée jusqu’au premier accès à une propriété :

$user = $reflector->newLazyProxy(fn() => $repository->find($id));
// Pas d'appel en base encore
$user->name; // Maintenant le proxy s'initialise

Le public direct est les auteurs de frameworks ORM et de conteneurs DI, pas les développeurs d’applications. Mais l’effet se fait sentir dans chaque application qui utilise Doctrine ou Symfony : le lazy loading implémenté au niveau du langage plutôt qu’à travers la génération de code.

PHP 8.4 est un langage qui ressemble à peine au PHP 5 avec lequel la plupart d’entre nous avons commencé. Les property hooks en particulier : ce ne sont pas des contournements, ce sont une fonctionnalité de conception.

#[\Deprecated] pour son propre code

PHP émet des notices de dépréciation pour les fonctions intégrées depuis des années. 8.4 permet de câbler le même mécanisme dans son propre code :

class ApiClient {
    #[\Deprecated(
        message: 'Use fetchJson() instead',
        since: '2.0',
    )]
    public function get(string $url): string { ... }
}

Appeler une méthode dépréciée émet maintenant E_USER_DEPRECATED, exactement comme appeler mysql_connect(). Les IDEs le détectent, les analyseurs statiques le signalent, le log d’erreurs le capture. Avant ça, la seule option était un commentaire PHPDoc @deprecated : bien pour les IDEs, complètement invisible pour le moteur.

BcMath\Number rend la précision arbitraire utilisable

Les fonctions bcmath existent en PHP depuis toujours, mais leur API procédurale rend tout chaînage pénible. 8.4 ajoute BcMath\Number, un wrapper objet avec surcharge d’opérateurs :

$a = new BcMath\Number('10.5');
$b = new BcMath\Number('3.2');

$result = $a + $b;             // BcMath\Number('13.7')
$result = $a * $b - new BcMath\Number('1');
echo $result;                  // 32.6

Les opérateurs +, -, *, /, **, % fonctionnent tous. L’objet est immutable. L’échelle se propage automatiquement à travers les opérations. Les calculs financiers, qui nécessitaient des chaînes de bcadd(bcmul(...), ...), se lisent maintenant comme de l’arithmétique.

De nouvelles fonctions procédurales complètent le tableau : bcceil(), bcfloor(), bcround(), bcdivmod().

L’enum RoundingMode remplace les constantes PHP_ROUND_*

round() a toujours pris un $mode entier depuis un ensemble de constantes PHP_ROUND_*. 8.4 les remplace par un enum RoundingMode avec des noms plus propres et quatre modes supplémentaires qui n’étaient pas disponibles avant :

round(2.5, mode: RoundingMode::HalfAwayFromZero);  // 3
round(2.5, mode: RoundingMode::HalfTowardsZero);   // 2
round(2.5, mode: RoundingMode::HalfEven);          // 2 (arrondi du banquier)
round(2.5, mode: RoundingMode::HalfOdd);           // 3

// Les quatre nouveaux modes (disponibles uniquement via l'enum)
round(2.3, mode: RoundingMode::TowardsZero);       // 2
round(2.7, mode: RoundingMode::AwayFromZero);      // 3
round(2.3, mode: RoundingMode::PositiveInfinity);  // 3
round(2.3, mode: RoundingMode::NegativeInfinity);  // 2

Les anciennes constantes PHP_ROUND_* fonctionnent encore. L’enum est la voie à suivre.

Les fonctions de string multibyte qui auraient dû exister

mb_trim(), mb_ltrim(), mb_rtrim() : des fonctions de trim qui respectent les frontières de caractères multibyte, pas juste les espaces ASCII. Aussi nouvelles : mb_ucfirst() et mb_lcfirst() pour la mise en majuscule correcte des strings multibyte.

$s = "\u{200B}hello\u{200B}"; // Espaces de largeur nulle
echo mb_trim($s);              // "hello"
echo mb_ucfirst('über');       // "Über"

Ces fonctions comblent des lacunes présentes depuis que mbstring a été introduit.

request_parse_body() pour les requêtes non-POST

PHP parse automatiquement application/x-www-form-urlencoded et multipart/form-data dans $_POST et $_FILES, mais seulement pour les requêtes POST. Les requêtes PATCH et PUT avec les mêmes types de contenu nécessitaient un parsing manuel avec file_get_contents('php://input') et du code personnalisé.

// Dans un handler PATCH
[$_POST, $_FILES] = request_parse_body();

La fonction retourne un tuple. Même logique de parsing que PHP utilise pour POST, maintenant disponible pour n’importe quelle méthode HTTP.

Une nouvelle API DOM qui suit la spec

L’API DOMDocument existante était construite sur une spec DOM level 3 plus ancienne avec des spécificités PHP superposées. 8.4 ajoute un namespace Dom\ parallèle qui implémente le WHATWG Living Standard :

$doc = Dom\HTMLDocument::createFromString('<p class="lead">Hello</p>');
$p = $doc->querySelector('p');
echo $p->classList;  // "lead"
echo $p->id;         // ""

$doc2 = Dom\HTMLDocument::createFromFile('page.html');

Dom\HTMLDocument parse correctement HTML5, tag soup inclus. Dom\XMLDocument gère le XML strict. Les nouvelles classes sont strictes sur les types, retournent les bons types de nœuds, et exposent des propriétés modernes comme classList, id, className. L’ancien DOMDocument reste, inchangé, pour la compatibilité ascendante.

PDO reçoit des sous-classes spécifiques au driver

PDO::connect() et l’instanciation directe retournent maintenant des sous-classes spécifiques au driver quand elles sont disponibles :

$pdo = PDO::connect('mysql:host=localhost;dbname=test', 'user', 'pass');
// $pdo est maintenant une instance Pdo\Mysql

$pdo = new Pdo\Pgsql('pgsql:host=localhost;dbname=test', 'user', 'pass');

Chaque sous-classe driver (Pdo\Mysql, Pdo\Pgsql, Pdo\Sqlite, Pdo\Firebird, Pdo\Odbc, Pdo\DbLib) peut exposer des méthodes spécifiques au driver sans polluer l’interface PDO de base. Doctrine, Laravel et autres ORMs similaires peuvent maintenant type-hinter contre la classe de driver spécifique quand ils ont besoin d’un comportement spécifique au driver.

OpenSSL reçoit le support des clés modernes

openssl_pkey_new() et les fonctions associées supportent maintenant Curve25519 et Curve448, les courbes elliptiques modernes qui ont remplacé les anciennes courbes NIST dans la plupart des recommandations de sécurité :

$key = openssl_pkey_new(['curve_name' => 'ed25519', 'private_key_type' => OPENSSL_KEYTYPE_EC]);
$details = openssl_pkey_get_details($key);

x25519 et x448 pour l’échange de clés, ed25519 et ed448 pour les signatures. Les quatre fonctionnent maintenant avec openssl_sign() et openssl_verify().

PCRE : lookbehind de longueur variable

La mise à jour de la bibliothèque PCRE2 embarquée (10.44) apporte les assertions lookbehind de longueur variable, quelque chose que les moteurs regex de Perl et Python avaient et que PHP ne pouvait pas faire :

// Correspondre "bar" seulement quand précédé de "foo" ou "foooo"
preg_match('/(?<=foo+)bar/', 'foooobar', $matches);

Les assertions lookbehind nécessitaient auparavant un pattern de largeur fixe. Elles peuvent maintenant correspondre à des patterns de longueur variable. Le modificateur r (PCRE2_EXTRA_CASELESS_RESTRICT) est aussi nouveau : il empêche le mélange de caractères ASCII et non-ASCII dans les correspondances insensibles à la casse, fermant une classe d’attaques de confusion Unicode.

DateTime reçoit les microsecondes et une factory de timestamp

$dt = DateTimeImmutable::createFromTimestamp(1700000000.5);
echo $dt->getMicrosecond(); // 500000

$with_micros = $dt->setMicrosecond(123456);

createFromTimestamp() accepte un float pour une précision sous-seconde. getMicrosecond() et setMicrosecond() complètent l’API pour le composant microseconde qui était à l’intérieur de DateTime mais inaccessible directement.

fpow() pour la conformité IEEE 754

pow(0, -2) en PHP retournait historiquement une valeur définie par l’implémentation. 8.4 déprécie pow() avec une base zéro et un exposant négatif et introduit fpow(), qui suit strictement IEEE 754 : fpow(0, -2) retourne INF, comme le standard le définit :

echo fpow(2.0, 3.0);   // 8.0
echo fpow(0.0, -1.0);  // INF
echo fpow(-1.0, INF);  // 1.0

À retenir dans tout code faisant des calculs mathématiques où la conformité IEEE compte.

Le coût de bcrypt augmente

Le coût par défaut pour password_hash() avec PASSWORD_BCRYPT est passé de 10 à 12. Ça impacte tout code appelant password_hash($pass, PASSWORD_BCRYPT) sans coût explicite. L’objectif est de maintenir le défaut grossièrement à “quelques centaines de millisecondes sur du matériel moderne” à mesure que le matériel devient plus rapide.

Si on stocke des hash bcrypt et qu’on monte sur 8.4, les hash existants restent valides : password_verify() lit le coût depuis le hash lui-même. Les nouveaux hash utilisent le coût 12. password_needs_rehash() retourne true pour les anciens hash si on passe ['cost' => 12], donc on peut les mettre à jour à la prochaine connexion.

Les dépréciations qui comptent

Les paramètres implicitement nullable sont dépréciés. Si un paramètre a un défaut de null, le type doit le dire explicitement :

// Déprécié dans 8.4
function foo(string $s = null) {}

// Correct
function foo(?string $s = null) {}
function foo(string|null $s = null) {}

trigger_error() avec E_USER_ERROR est déprécié : le remplacer par une exception ou exit(). Le niveau E_USER_ERROR a toujours été un hybride maladroit entre une erreur récupérable et une erreur fatale, et personne n’était sûr lequel.

lcg_value() est aussi déprécié. Utiliser Random\Randomizer::getFloat() à la place. Le générateur LCG avait de mauvaises propriétés d’aléatoire et aucun contrôle de graine.

Laravel comme cible de première classe

Depuis sa première release, API Platform était construit sur Symfony. La couche HTTP, les métadonnées, le serializer et le bridge Doctrine supposaient tous le container de Symfony, l’event dispatcher et le cycle de vie des requêtes. Les utilisateurs Laravel pouvaient faire tourner API Platform via un adaptateur léger, mais les filtres, la sécurité et l’intégration Doctrine ne fonctionnaient pas avec Eloquent.

La 4.0 livre un bridge Laravel dédié. Il mappe la couche d’état d’API Platform sur le cycle de vie des requêtes de Laravel, s’intègre directement avec les modèles Eloquent, et se branche sur le système d’autorisation de Laravel :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Illuminate\Database\Eloquent\Model;

#[ApiResource(
    operations: [new GetCollection(), new Get()]
)]
class Book extends Model
{
    protected $fillable = ['title', 'author'];
}

L’autorisation utilise les policies et gates de Laravel plutôt que les security voters de Symfony. Les opérations exposent un paramètre policy dédié qui correspond à un nom de méthode de policy :

#[Get(policy: 'view')]
class Book extends Model {}

API Platform mappe la valeur de policy vers Gate::allows() de Laravel avec l’instance du modèle. Les policies peuvent aussi être auto-détectées : si un modèle a une classe de policy enregistrée, API Platform infère la bonne méthode (view, viewAny, create, update, delete) selon le type d’opération. Les filtres pour les collections Eloquent couvrent le même périmètre que leurs homologues Doctrine : PartialSearchFilter, EqualsFilter, RangeFilter, OrderFilter, DateFilter, et des variantes de recherche (StartSearchFilter, EndSearchFilter). La pagination, le tri et la validation fonctionnent via les mécanismes natifs de Laravel.

Ce n’est pas un shim de compatibilité. Le bridge Laravel est maintenu aux côtés du bridge Symfony et est couvert par la même suite de tests. Les projets utilisant l’un ou l’autre framework ont la même API de définition des ressources.

PUT supprimé des opérations par défaut

Depuis API Platform 1.0, #[ApiResource] sans tableau operations explicite générait des opérations CRUD incluant PUT. Le handler PUT mettait à jour les ressources existantes et, depuis la 3.1, pouvait aussi les créer via allowCreate: true.

La 4.0 supprime PUT de l’ensemble par défaut. #[ApiResource] génère maintenant GET, POST, PATCH et DELETE. Pour utiliser PUT, il faut le déclarer explicitement :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Put;

#[ApiResource(
    operations: [
        // ... autres opérations
        new Put(),
    ]
)]
class Book {}

La motivation est la clarté sémantique. PATCH remplace PUT pour la plupart des cas d’usage de mise à jour partielle. La sémantique de PUT — remplacer la représentation entière de la ressource — est rarement ce qu’une API implémente réellement, mais le défaut le faisait apparaître dans toutes les APIs à moins de l’enlever activement. Rendre PUT opt-in aligne les défauts sur la façon dont la sémantique HTTP est réellement utilisée en pratique.

PHP 8.2 minimum

La 4.0 abandonne PHP 8.0 et 8.1. PHP 8.2 est le nouveau minimum. La syntaxe de classe readonly, AllowDynamicProperties et les types DNF¹ introduits en 8.2 sont disponibles dans toute la codebase. Aucune fonctionnalité spécifique de 8.2 n’est structurante pour la 4.0 — le bump de version concerne principalement l’abandon du fardeau de maintenance plus ancien.

Symfony 6.4+ et Doctrine ORM 2.17+ minimum

Côté Symfony, la 4.0 requiert Symfony 6.4 ou 7.x et Doctrine ORM 2.17 ou 3.x. Les deux étaient déjà supportés en 3.4. La migration de la 3.4 vers la 4.0 sur la piste Symfony est : résoudre les dépréciations 3.4, vérifier qu’on est sur Symfony 6.4+ et ORM 2.17+, puis mettre à jour. Aucun travail de migration supplémentaire n’est nécessaire si c’est déjà en place.

Ce que la 4.0 n’est pas

La 4.0 n’est pas une nouvelle architecture. Les state providers, processors et le modèle de métadonnées de ressources de la 3.0 sont inchangés. Le bridge Laravel ajoute un nouveau contexte d’exécution mais ne change pas la façon dont les ressources ou les opérations sont déclarées. La séparation est intentionnelle : si la 3.0 était le “quoi”, la 4.0 est le “où”.

BackedEnum comme ressources API

Depuis PHP 8.1, les classes BackedEnum ont un ensemble fixe de cas avec des valeurs de support string ou integer. API Platform 3.4 permet de mettre #[ApiResource] directement sur un BackedEnum :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [new GetCollection()]
)]
enum BookStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

Un endpoint GET /book_statuses retourne la liste des cas. Chaque cas est sérialisé avec son nom et sa valeur. L’endpoint est en lecture seule — les enums sont immuables par nature.

C’est surtout utile pour les consommateurs frontend qui veulent une liste lisible par machine des valeurs valides sans les coder en dur. L’alternative était un contrôleur personnalisé ou une ressource DTO dédiée listant manuellement les valeurs de l’enum.

BackedEnumFilter

Le compagnon des ressources enum est BackedEnumFilter, un nouveau filtre pour les collections Doctrine qui contraint une requête par une propriété BackedEnum :

use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
#[ApiFilter(BackedEnumFilter::class, properties: ['status'])]
class Book
{
    public BookStatus $status;
}

GET /books?status=published filtre la collection aux livres où status est égal à BookStatus::Published. Les valeurs d’enum invalides retournent une réponse 400. Avant ce filtre, on devait soit écrire un filtre personnalisé, soit utiliser SearchFilter et valider la valeur manuellement.

Expressions de sécurité sur les paramètres

La 3.3 avait ajouté la sécurité aux liens et aux propriétés. La 3.4 étend cela aux paramètres de requête. Un paramètre peut déclarer une expression de sécurité qui contrôle s’il est accepté :

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    parameters: [
        new QueryParameter(
            key: 'includeDeleted',
            security: "is_granted('ROLE_ADMIN')"
        ),
    ]
)]
class Book {}

Quand l’expression de sécurité est false, le paramètre est rejeté avec un 403, pas silencieusement ignoré. C’est plus explicite que vérifier le rôle de l’utilisateur dans le provider après avoir reçu le paramètre.

Support DBAL 4 ajouté

La 3.4 ajoute le support de Doctrine DBAL 4, qui apporte des changements au système de types qui affectent la façon dont les types personnalisés et le SQL spécifique à la plateforme fonctionnent. Les filtres Doctrine Orm et les extensions de requête dans API Platform ont été mis à jour pour fonctionner avec la nouvelle API de types DBAL 4.

DBAL 3 (^3.4.0) et DBAL 4 sont supportés simultanément en 3.4. C’est la release à adopter pour migrer vers DBAL 4 tout en restant sur une branche stable API Platform 3.x.

Validateur de paramètres de requête déprécié

La 3.3 avait ajouté le validateur strict de paramètres de requête en opt-in. La 3.4 déprécie l’ancien comportement (paramètres inconnus silencieusement ignorés) en préparation pour rendre la validation stricte la valeur par défaut en 4.0. Les projets qui s’appuient sur des paramètres de requête pass-through ont une release de plus pour les déclarer explicitement.

Dernier arrêt avant la 4.0

La 3.4 est la dernière release 3.x avec de nouvelles fonctionnalités. Tout ce qui était déprécié d’ici la 3.4 disparaît en 4.0. Le chemin de migration de la 3.4 vers la 4.0 est intentionnellement court : résoudre les dépréciations, puis mettre à jour.

Configuration déclarative des headers

Avant la 3.3, définir des headers de réponse personnalisés nécessitait soit un processor personnalisé qui modifiait l’objet réponse, soit un event listener Symfony sur kernel.response. Les deux approches fonctionnaient mais vivaient en dehors de la définition de la ressource.

La 3.3 ajoute un paramètre parameters aux métadonnées d’opération :

use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\HeaderParameter;

#[Get(
    parameters: [
        'X-Custom-Header' => new HeaderParameter(description: 'A custom header'),
    ]
)]

Pour les headers qui varient par réponse (comme Cache-Control avec un max-age calculé), le processor peut encore les définir directement sur l’objet réponse. Le paramètre parameters sert principalement à documenter les headers attendus dans la spec OpenAPI et pour les valeurs de headers statiques.

Sécurité des liens sur les sous-ressources

Quand une ressource expose des liens vers des ressources liées, ces liens apparaissent dans la sortie sérialisée indépendamment du fait que l’utilisateur courant puisse accéder à la ressource liée. Cela crée un problème de divulgation : un utilisateur qui peut lire un livre mais pas le profil de son auteur voit quand même l’URI de l’auteur dans la réponse.

La 3.3 ajoute des expressions de sécurité au descripteur Link :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Link;

#[ApiResource]
#[Get]
class Book
{
    #[Link(
        toClass: Author::class,
        security: "is_granted('ROLE_ADMIN')"
    )]
    public Author $author;
}

Le lien est omis de la réponse quand l’expression de sécurité évalue à false. La ressource liée elle-même n’est pas affectée — seulement le fait que la réponse courante inclue la référence à elle.

ApiProperty::security

Le même mécanisme d’expression de sécurité est disponible au niveau propriété via ApiProperty::security. Cela permet de cacher des champs individuels selon l’utilisateur courant sans écrire un normalizer personnalisé :

use ApiPlatform\Metadata\ApiProperty;

class Book
{
    #[ApiProperty(security: "is_granted('ROLE_ADMIN')")]
    public string $internalNote;
}

La propriété est exclue de la sérialisation quand l’expression est false. C’est plus propre qu’un normalizer pour le cas courant de champs conditionnels par rôle.

Webhooks OpenAPI

OpenAPI 3.1 supporte les webhooks — des appels HTTP sortants que votre API fait à des listeners enregistrés — dans le document spec lui-même. Avant la 3.3, il n’y avait pas de moyen de les documenter dans la spec générée par API Platform.

La 3.3 ajoute une classe Webhook à passer au paramètre openapi d’une opération. On déclare une classe PHP dédiée avec #[ApiResource] et on utilise Webhook sur chaque opération pour décrire la forme de l’appel sortant :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Attributes\Webhook;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\PathItem;

#[ApiResource(
    operations: [
        new Post(
            openapi: new Webhook(
                name: 'bookCreated',
                pathItem: new PathItem(
                    post: new Operation(summary: 'Un livre a été créé'),
                ),
            )
        ),
    ]
)]
class BookWebhook {}

Les définitions de webhooks apparaissent dans la spec générée sous la clé webhooks aux côtés des paths réguliers. Swagger UI les affiche dans une section séparée.

Deep linking dans Swagger UI

Swagger UI supporte le deep linking — des URLs mémorisables qui ouvrent directement sur une opération spécifique dans l’interface. Avant la 3.3, l’intégration API Platform n’activait pas cela. La 3.3 active l’option deepLinking de Swagger UI, configurable via swagger_ui_extra_configuration :

api_platform:
    openapi:
        swagger_ui_extra_configuration:
            deepLinking: true

Avec cette option activée, le fragment d’URL se met à jour pendant la navigation dans l’UI, et coller ou partager l’URL ouvre la même opération. Utile quand on écrit de la doc qui pointe directement vers un endpoint spécifique.

Validation stricte des paramètres de requête

La 3.3 renforce le validateur de paramètres de requête : les paramètres non déclarés sur l’opération renvoient maintenant une réponse 400 au lieu d’être silencieusement ignorés. Ce comportement est opt-in :

api_platform:
    validator:
        query_parameter_validation: true

L’intention est de détecter les fautes de frappe et les mauvaises utilisations de l’API tôt. Si vous vous appuyez sur des paramètres de requête pass-through pour une logique personnalisée (logging, feature flags), vous devez les déclarer explicitement sur l’opération avant d’activer cela.

La suppression la plus visible : les annotations Doctrine. @Route, @ORM\Column, @Assert — disparus. Les attributs PHP natifs sont l’approche recommandée depuis Symfony 5.2. 7.0 rend juste ça officiel.

Les attributs partout

La migration des annotations vers les attributs est principalement mécanique : la syntaxe passe de @ à #[], et les références de classes passent des classes d’annotation Doctrine aux classes d’attribut PHP :

// avant
/** @Route('/users', methods={"GET"}) */

// après
#[Route('/users', methods: ['GET'])]

Le vrai gain n’est pas juste la syntaxe : les attributs sont validés par le moteur PHP, pas un parseur de docblock. Les IDEs peuvent les résoudre sans plugins personnalisés. Les outils d’analyse statique les comprennent nativement. Fini les “ça échoue silencieusement à l’exécution à cause d’une faute de frappe dans un commentaire.”

Workflow avec attributs PHP

Les listeners et guards d’événements Workflow peuvent maintenant être enregistrés via des attributs :

#[AsGuard(workflow: 'order', transition: 'ship')]
public function canShip(Event $event): void
{
    if (!$event->getSubject()->isPaymentConfirmed()) {
        $event->setBlocked(true);
    }
}

Le profiler de workflow, un panneau dédié montrant le marquage courant et les transitions disponibles, est un outil de debug vraiment utile quand on travaille avec des machines à états complexes.

DatePoint dans le composant Clock

DatePoint, le DateTime immutable avec gestion stricte des erreurs introduit dans 6.4, est maintenant la façon recommandée de travailler avec les dates. Combiné avec les propriétés readonly de PHP 8.2, les objets-valeur de dates dans le code de domaine deviennent presque trivialement propres :

readonly class Order {
    public function __construct(
        public DatePoint $createdAt,
        public ?DatePoint $shippedAt = null,
    ) {}
}

Ce que 7.0 supprime

La liste complète des suppressions : le support des annotations Doctrine, le bridge du composant Templating, le bridge ProxyManager, le bridge Monolog pour les versions inférieures à 3.0, et le transport Sendinblue (remplacé par Brevo). Le support PHP 8.0 et 8.1 se termine aussi. 8.2 est le plancher maintenant.

Monter de 6.4 avec toutes les notices de dépréciation corrigées, et 7.0 est fluide. Sauter cette étape et on s’expose à une mauvaise surprise.

Scheduler et AssetMapper diplômés

Deux composants qui sont sortis en expérimental dans 6.3 sont maintenant stables : Scheduler et AssetMapper. Stable signifie des APIs verrouillées, plus de mises en garde @experimental, et ils apparaissent correctement dans le guide de mise à jour. On peut vraiment compter sur eux maintenant.

Scheduler reçoit #[AsCronTask] et #[AsPeriodicTask] pour l’enregistrement de tâches par attribut, la modification de planning à l’exécution avec recalcul du heap, FailureEvent, et une option --date sur schedule:debug. AssetMapper ajoute le support des fichiers CSS dans l’importmap, une commande outdated, une commande audit, et le préchargement automatique via WebLink.

#[AsCronTask('0 2 * * *')]
class NightlyReportMessage {}

#[AsPeriodicTask(frequency: '1 hour')]
class HourlyCleanupMessage {}

Le câblage de services reçoit deux nouveaux attributs

#[AutowireLocator] et #[AutowireIterator] ont atterri dans 6.4 et sont stables dans 7.0. Ils remplacent la configuration verbose XML/YAML des service locators taggués par quelque chose qu’on peut juste mettre directement en PHP :

class HandlerRegistry
{
    public function __construct(
        #[AutowireLocator('app.handler', indexAttribute: 'key')]
        private ContainerInterface $handlers,
    ) {}
}

#[Target] est aussi plus intelligent : quand un service a un alias d’autowiring nommé comme invoice.lock.factory, on peut maintenant écrire #[Target('invoice')] au lieu du nom complet de l’alias. Moins de bruit quand le type dit déjà ce qu’on veut.

Messenger reçoit une gestion plus précise des échecs

RejectRedeliveredMessageException dit au worker de ne pas retenter un message, ce qui est pratique quand un message arrive deux fois à cause d’un timeout d’ack du transport et qu’on a besoin d’une sémantique exactly-once. messenger:failed:remove --all vide tout le transport d’échec en un coup, pas de boucle nécessaire. Les retries échoués peuvent aussi aller directement au transport d’échec, en contournant entièrement la queue de retry.

Plusieurs hôtes Redis Sentinel sont maintenant supportés dans le DSN :

redis-sentinel://host1:26379,host2:26379,host3:26379/mymaster

Console reçoit les noms de signaux et le profilage de commandes

SignalMap mappe les entiers de signaux à leurs noms POSIX. Quand un worker attrape SIGTERM, le log dit maintenant SIGTERM au lieu de 15. Petite chose, vraie amélioration. ConsoleTerminateEvent est dispatché même quand le processus se termine via signal, ce qui n’était pas le cas avant 7.0.

Le profilage de commandes arrive aussi : passer --profile à bin/console et les données collectées vont directement dans le profiler Symfony, navigable depuis l’UI web.

Form : des petites choses qui s’accumulent

ChoiceType reçoit une option duplicate_preferred_choices. La définir à false et on arrête de montrer la même option deux fois quand les choix préférés chevauchent la liste complète. FormEvent::setData() est déprécié pour les événements où les données sont déjà verrouillées à ce point du cycle de vie. La barre oblique auto-fermante sur les éléments <input> est aussi supprimée : <input> est un élément void en HTML5 et la barre oblique était techniquement invalide.

Le support des enums dans les formulaires est bien fait : ChoiceType rend les backed enums directement, et les enums translatable reçoivent leurs labels via le translator sans câblage personnalisé.

HttpFoundation : small but useful

Response::send() reçoit un paramètre $flush. Passer false pour bufferiser la sortie sans la flusher au client, utile quand on enchaîne des middlewares qui doivent inspecter la réponse avant qu’elle quitte le processus.

UriSigner passe de HttpKernel à HttpFoundation, où il appartient sémantiquement. Même nom de classe, namespace différent.

Les cookies reçoivent le support CHIPS (Cookies Having Independent Partitioned State), le mécanisme navigateur pour les cookies cross-site dans une partition first-party. Ça ne compte que si on construit des widgets embarquables, mais bon à savoir que c’est là.

Translation : provider Phrase et sortie arborescente

Phrase rejoint Crowdin et Lokalise comme provider de traduction supporté. Le configurer dans config/packages/translation.yaml et les commandes translation:push / translation:pull gèrent la synchronisation.

translation:pull reçoit une option --as-tree qui écrit les fichiers de traduction en YAML imbriqué plutôt qu’en clés à notation pointée plate. Si c’est vraiment mieux dépend entièrement de l’équipe.

LocaleSwitcher::runWithLocale() passe maintenant la locale courante comme argument au callback, évitant un appel getLocale() à l’intérieur :

$switcher->runWithLocale('fr', function (string $locale) use ($mailer) {
    $mailer->send($this->buildEmail($locale));
});

Quelques choses dans Serializer et DomCrawler

L’attribut Context du Serializer peut maintenant cibler des classes spécifiques, donc un seul DTO peut se comporter différemment pendant la (dé)sérialisation selon quelle classe détient le contexte. TranslatableNormalizer arrive pour normaliser les objets qui implémentent TranslatableInterface : le translator est appelé pendant la normalisation, pas avant.

Crawler::attr() reçoit un paramètre $default. Au lieu de null-checker la valeur de retour, on passe une valeur de repli :

$src = $crawler->attr('src', '/placeholder.png');

assertAnySelectorText() et assertAnySelectorTextContains() rejoignent l’ensemble d’assertions DomCrawler. Ils passent si au moins un élément correspondant satisfait la condition, plutôt que d’en exiger que tous correspondent.

HttpClient : réponses HAR pour les tests

MockResponse accepte maintenant les fichiers HAR (HTTP Archive). Enregistrer de vraies interactions HTTP dans le navigateur ou avec un proxy, déposer le fichier .har dans les fixtures de tests, et les rejouer :

$client = new MockHttpClient(HarFileResponseFactory::createFromFile(__DIR__.'/fixtures/api.har'));

Bien mieux qu’écrire des stubs de réponse à la main quand on traite avec une API complexe.

AssetMapper

La gestion frontend moderne dans Symfony, ça voulait dire Webpack Encore. Encore fonctionne : il gère la transpilation, le bundling, le versioning, le hot reload. Il nécessite aussi Node.js, une étape de build séparée, et une quantité non négligeable de configuration pour ce qui est souvent un frontend assez modeste.

AssetMapper prend une position différente. Les navigateurs modernes supportent les modules ES nativement. Au lieu de bundler, livrer les fichiers tels quels, laisser le navigateur résoudre les imports via une importmap, et gérer les dépendances vendor via des fichiers téléchargés plutôt que des packages npm.

composer require symfony/asset-mapper
php bin/console importmap:require lodash

Pas de Node.js. Pas de npm. Pas d’étape de build. Les fichiers JavaScript et CSS sont versionnés et servis directement, avec un digest dans l’URL pour le cache busting. Pour les applications où le frontend n’est pas la principale préoccupation d’ingénierie, ça supprime toute une chaîne d’outils de l’équation.

6.4 ajoute les fichiers CSS à l’importmap, le préchargement CSS automatique via WebLink, et des commandes pour auditer et mettre à jour les dépendances vendor. L’expérience package.json, sans npm.

Scheduler

Le composant Scheduler (planification de tâches périodiques et de style cron sans runner externe) sort d’expérimental et devient stable. L’API utilise des attributs :

#[AsCronTask('0 * * * *')]
class HourlyReport implements ScheduledTaskInterface
{
    public function run(): void { ... }
}

Soutenu par les transports Messenger, les tâches tournent dans tout environnement où un worker est en cours d’exécution. Pour beaucoup de cas d’usage, ça remplace le pattern classique entrée cron + commande console.

Webhook et RemoteEvent

Aussi diplômés d’expérimental : le composant Webhook gère les webhooks entrants depuis des services externes. Au lieu d’écrire des contrôleurs bruts qui parsent les payloads et dispatchent des événements à la main, on configure des parseurs pour des services connus (Stripe, GitHub, Mailgun) et on obtient des événements typés.

DatePoint

Une nouvelle classe DatePoint dans le composant Clock : un wrapper DateTime immutable qui lève des exceptions sur les modificateurs invalides au lieu de retourner silencieusement false. Petite chose, mais significative pour le code qui manipule des dates et veut réellement savoir quand quelque chose va mal.

La fenêtre de support

6.4 LTS reçoit des corrections de bugs jusqu’en novembre 2026 et des correctifs de sécurité jusqu’en novembre 2027. Le chemin de 6.4 vers 7.4 (la prochaine LTS) passe par les notices de dépréciation de 6.4, comme d’habitude.

Routes sans strings magiques

Les alias de routes basés sur le FQCN sont maintenant générés automatiquement. Si une méthode de contrôleur a une seule route, Symfony crée un alias en utilisant son nom de classe complet :

// Auparavant : seul 'blog_index' fonctionnait
// Maintenant : les deux fonctionnent de manière identique
$this->urlGenerator->generate('blog_index');
$this->urlGenerator->generate(BlogController::class.'::index');

Pour les contrôleurs invocables, l’alias est juste le nom de classe. L’avantage pratique : navigation IDE et sécurité au refactoring — on référence une constante de classe, pas une string qui peut silencieusement diverger.

Deux nouveaux attributs DI

#[AutowireLocator] et #[AutowireIterator] rejoignent la famille d’attributs DI. Au lieu de configurer des service locators et des itérables taggués en YAML, on les déclare juste sur les paramètres du constructeur :

public function __construct(
    #[AutowireLocator([FooHandler::class, BarHandler::class])]
    private ContainerInterface $handlers,
) {}

Alias, services optionnels (préfixés avec ?), et injection de paramètres via SubscribedService sont tous supportés. Le locator charge paresseusement, donc seuls les handlers qu’on appelle vraiment sont instanciés.

Messenger reçoit des handlers intégrés

Trois nouvelles classes de message couvrent des tâches courantes qui nécessitaient auparavant des handlers personnalisés.

RunProcessMessage dispatche une commande Process via le bus. RunCommandMessage fait de même pour les commandes console. Les deux retournent un objet de contexte avec le code de sortie et la sortie. PingWebhookMessage pingue une URL, ce qui est utile pour surveiller les tâches planifiées sans mettre en place un service de health-check dédié :

$this->bus->dispatch(new RunCommandMessage('cache:clear'));
$this->bus->dispatch(new PingWebhookMessage('GET', 'https://healthchecks.io/ping/abc123'));

Le problème d’héritage des sous-processus a aussi été résolu avec PhpSubprocess. Quand on lance PHP avec une limite mémoire personnalisée (-d memory_limit=-1), les processus enfants lancés avec Process ne l’héritent pas. PhpSubprocess le fait :

$sub = new PhpSubprocess(['bin/console', 'app:heavy-import']);

Sécurité : trois corrections pour des situations réelles

Le profiler montre maintenant comment les badges de sécurité ont été résolus pendant l’authentification : lesquels ont passé, lesquels ont échoué, et pourquoi. Avant, il fallait ajouter de la sortie de debug manuellement quand un authentificateur personnalisé ne se comportait pas bien.

Le throttling de login via RateLimiter hache maintenant automatiquement les PII dans les logs. Les adresses IP et les noms d’utilisateur sont hachés avec le secret du kernel avant d’être écrits. Pas de config nécessaire, pas de regex sur les lignes de log.

Les patterns de firewall acceptent maintenant des tableaux :

firewalls:
    no_security:
        pattern:
            - "^/register$"
            - "^/api/webhooks/"

Fini les acrobaties regex pour les exclusions multi-chemins.

Déconnexion sans contrôleur bidon

La route de déconnexion nécessitait auparavant un contrôleur qui ne faisait rien que lever une exception, avec un commentaire expliquant que oui, c’est intentionnel. 6.4 élimine ça :

# config/routes/security.yaml
_security_logout:
    resource: security.route_loader.logout
    type: service

Le route loader s’en occupe. Le contrôleur bidon est parti. Flex met à jour la recette.

Le sérialiseur en meilleure forme

Trois améliorations du sérialiseur qui résolvent chacune un vrai problème.

Attribut #[Groups] au niveau de la classe : appliquer un groupe à la classe entière, puis surcharger par propriété. Utile quand une ressource a un groupe de sérialisation par défaut et quelques champs qui nécessitent un contrôle plus fin.

Les objets translatable ont maintenant un normaliseur dédié. Les strings translatable (enveloppant TranslatableInterface de Doctrine) sont traduites vers la locale passée via NORMALIZATION_LOCALE_KEY pendant la normalisation. Avant ça, il fallait écrire un normaliseur personnalisé.

En mode debug, les erreurs de décodage JSON utilisent maintenant seld/jsonlint pour de meilleurs messages. Au lieu de “Syntax error”, on obtient la ligne et ce qui s’est vraiment passé :

Parse error on line 1: {'foo': 'bar'}
           ^ Invalid string, used single quotes instead of double quotes

Profilers pour les choses qui n’étaient pas des requêtes HTTP

Le profiler de commande étend le profiler existant aux commandes console. Ajouter --profile à n’importe quelle commande et obtenir une entrée complète dans le profiler : entrée/sortie, temps d’exécution, mémoire, requêtes en base, messages de log. Les commandes qui nécessitaient --verbose plus du timing manuel ont maintenant la même expérience de debug que les requêtes HTTP.

Le profiler de workflow fait de même pour les machines à états. Un nouveau panneau montre une représentation graphique des workflows et les transitions déclenchées pendant la requête. Zéro configuration.

L’accumulation de DX

Plusieurs additions plus petites qui se combinent.

renderBlock() et renderBlockView() sur AbstractController permettent de rendre un bloc Twig nommé et de le retourner comme Response ou string. Pratique pour les réponses Turbo Stream où on veut mettre à jour un fragment sans une action de contrôleur complète.

Le processeur d’env defined retourne un booléen plutôt que la valeur : true si la variable existe et n’est pas vide, false sinon. Utile pour les feature flags pilotés par des variables d’environnement :

parameters:
    is_feature_enabled: '%env(defined:FEATURE_FLAG_KEY)%'

HttpClient accepte maintenant max_retries par requête, surchargeant la stratégie globale de retry. La méthode filter() du composant Finder accepte un second argument pour élaguer des répertoires entiers tôt, ce qui compte quand on cherche dans de grands arbres.

La méthode click() de BrowserKit accepte maintenant des paramètres serveur comme en-têtes supplémentaires, utile dans les tests fonctionnels qui doivent simuler des appels API authentifiés en suivant des liens.

L’impersonation devient utilisable dans les templates

Deux nouveaux helpers Twig : impersonation_path() et impersonation_url(). Ils génèrent les URLs correctes incluant le paramètre de query switch-user, qui est configurable et n’a aucune raison d’être codé en dur dans les templates. Les associer avec l’existant impersonation_exit_path() pour le flux complet d’impersonation admin.

Contrôle des locales, partout où ça manquait

Trois lacunes comblées. TemplatedEmail a maintenant une méthode locale() pour rendre les emails dans la langue du destinataire. runWithLocale() du locale switcher passe maintenant la locale comme argument au callback, donc on n’a pas à la capturer depuis la portée extérieure. Et app.enabledLocales est disponible dans Twig, donc on peut construire des sélecteurs de langue sans coder en dur les listes de locales.

Déployer sur des filesystems en lecture seule

APP_BUILD_DIR est maintenant une variable d’environnement reconnue par le kernel. La définir pour rediriger les artefacts compilés (cache du router, proxies Doctrine, traductions préchargées) vers un répertoire qui existe, même quand le répertoire cache par défaut n’existe pas. MicroKernelTrait l’utilise automatiquement. WarmableInterface a reçu un paramètre $buildDir pour supporter cette séparation : les warmers de cache personnalisés qui écrivent des artefacts en lecture seule doivent se mettre à jour en conséquence.

Les constantes de classe typées

Les constantes de classe n’ont jamais été typées depuis leur introduction. PHP 8.3 corrige ça :

interface HasVersion {
    const string VERSION;
}

class App implements HasVersion {
    const string VERSION = '1.0.0';
}

Sans constantes typées, une constante d’interface pouvait être redéfinie avec un type complètement différent dans une classe implémentante sans que rien ne se plaigne. Les constantes typées comblent ce trou, et sur les bases de code pilotées par les interfaces, l’impact est immédiat.

L’accès dynamique aux constantes de classe

Une lacune qui nécessitait un contournement depuis que les constantes existent :

$name = 'STATUS';
echo MyClass::{$name}; // ça marche maintenant

Avant, accéder à une constante avec un nom dynamique signifiait appeler constant('MyClass::STATUS'). La nouvelle syntaxe est cohérente avec la façon dont PHP gère déjà les variables variables et les appels de méthodes dynamiques.

readonly peut maintenant être modifié dans clone

Une limitation spécifique mais vraiment agaçante de 8.1 avec readonly : on ne pouvait pas cloner un objet et changer une propriété readonly. 8.3 ajoute la possibilité de réinitialiser les propriétés readonly pendant le clonage, ce qui rend les value objects immuables utilisables dans beaucoup plus de patterns.

json_validate()

if (json_validate($string)) {
    $data = json_decode($string);
}

Avant 8.3, la seule façon de valider une chaîne JSON était de la décoder et de vérifier les erreurs. json_validate() vérifie sans allouer la structure décodée, ce qui compte quand on a juste besoin de savoir si la chaîne est du JSON valide, pas ce qu’elle contient.

Améliorations du Randomizer

getBytesFromString() génère une chaîne aléatoire composée uniquement de caractères d’un ensemble donné :

$rng = new Random\Randomizer();
$token = $rng->getBytesFromString('abcdefghijklmnopqrstuvwxyz0123456789', 32);

L’approche précédente : str_split, array_map, sélection aléatoire, implode. Ça marchait, mais c’était plus long que ça n’avait le droit d’être.

8.3 est pour les équipes qui adoptent les versions PHP rapidement et veulent les améliorations incrémentales. Les constantes typées seules valent le coup sur toute base de code avec des constantes d’interface.

#[\Override] rend l’héritage explicite

Avant 8.3, rien n’empêchait d’écrire une méthode qu’on croyait surcharger celle d’un parent, alors qu’on avait un typo dans le nom ou que le parent l’avait silencieusement supprimée. Des bugs silencieux, zéro retour du moteur.

class Cache {
    #[\Override]
    public function get(string $key): mixed {
        // Le moteur vérifie que cette méthode existe dans un parent ou une interface
    }
}

Si la méthode n’existe dans aucune classe parente ou interface implémentée, PHP lève une erreur. Même concept que @Override en Java ou override en C#, enfin en PHP.

final sur les méthodes de trait

Les traits ont toujours eu des aspérités dans le modèle OOP de PHP. Un problème spécifique : une classe utilisant un trait pouvait surcharger n’importe laquelle de ses méthodes, sapant les garanties que le trait essayait de fournir. 8.3 laisse le trait lui-même marquer une méthode comme final :

trait Singleton {
    final public static function getInstance(): static {
        // ...
    }
}

Maintenant, une classe utilisant le trait ne peut pas surcharger getInstance(). La garantie tient.

Les classes anonymes peuvent être readonly

PHP 8.1 avait apporté les classes readonly. Les classes anonymes avaient été laissées de côté pour une raison obscure. 8.3 corrige ça :

$point = new readonly class(3, 4) {
    public function __construct(
        public float $x,
        public float $y,
    ) {}
};

Pratique quand on a besoin d’un value object immuable jetable sans la cérémonie de lui donner un nom.

Les initialiseurs de variables statiques acceptent des expressions

Une restriction petite mais ancienne : les initialiseurs de variables statiques n’acceptaient que des expressions constantes, pas d’appels de fonctions. 8.3 lève cette contrainte :

function connection(): PDO {
    static $pdo = new PDO(getenv('DATABASE_URL'));
    return $pdo;
}

L’initialiseur s’exécute une seule fois au premier appel, la variable statique persiste. Faisable avec un test null avant, c’est juste plus propre.

mb_str_pad() existe enfin

str_pad() a toujours été conscient des octets, pas des caractères. Pour les chaînes multibyte (arabe, japonais, caractères accentués) il produisait une sortie incorrecte. 8.3 ajoute enfin la variante multibyte :

$padded = mb_str_pad('日本', 10, '*', STR_PAD_BOTH);

La fonction respecte les limites de caractères, pas les comptages d’octets.

str_increment() et str_decrement()

L’opérateur ++ de PHP sur les chaînes a une histoire de bizarreries : il incrémente les séquences de lettres ('a' → 'b', 'z' → 'aa'), mais -- n’a jamais fonctionné symétriquement. Le comportement était suffisamment surprenant que 8.3 déprécie ++/-- sur les chaînes non alphanumériques et introduit des fonctions explicites :

echo str_increment('a');  // b
echo str_increment('Az'); // Ba
echo str_decrement('b');  // a
echo str_decrement('Ba'); // Az

Les fonctions rendent l’intention évidente et le comportement prévisible.

Random\Randomizer gagne le support des flottants

8.3 comble le côté flottant de l’API Randomizer :

$rng = new Random\Randomizer();

// Un flottant dans [0.0, 1.0)
$f = $rng->nextFloat();

// Un flottant dans une plage spécifique avec contrôle de l'inclusion des bornes
$f = $rng->getFloat(1.5, 3.5, Random\IntervalBoundary::ClosedOpen);

IntervalBoundary est un nouvel enum avec quatre valeurs : ClosedOpen, ClosedClosed, OpenClosed, OpenOpen. C’est important pour la justesse statistique : l’approche naïve avec rand() / getrandmax() ne produit pas une distribution uniforme sur les flottants.

La hiérarchie d’exceptions de Date

Les erreurs de date/heure en PHP levaient des exceptions génériques sans moyen de distinguer “chaîne malformée” de “timezone invalide” sans parser le message. 8.3 ajoute une hiérarchie propre :

try {
    new DateTimeImmutable('not a date');
} catch (DateMalformedStringException $e) {
    // spécifiquement un échec de parsing
} catch (DateException $e) {
    // autres erreurs liées aux dates
}

L’arbre complet : DateError (niveau moteur), DateException (base), avec des sous-classes spécifiques pour timezone invalide, chaîne d’intervalle malformée, chaîne de période malformée, et chaîne de date malformée.

gc_status() en dit plus

gc_status() retourne maintenant huit champs supplémentaires : running, protected, full, buffer_size, et des décompositions temporelles (application_time, collector_time, destructor_time, free_time). Si vous profilez la pression mémoire ou les pauses GC, ces données étaient auparavant inaccessibles sans passer par une extension.

strrchr() gagne un argument de direction

strrchr() (trouver la dernière occurrence d’un caractère, retourner de là jusqu’à la fin) accepte maintenant un booléen $before_needle, alignant son API sur celle de strstr() :

$path = '/var/www/html/index.php';
echo strrchr($path, '/', before_needle: true);  // /var/www/html
echo strrchr($path, '/');                        // /index.php

Une fonction présente dans PHP depuis 1994, enfin cohérente avec sa voisine.

Dépréciations à noter

get_class() et get_parent_class() sans arguments émettent maintenant des avertissements de dépréciation. Les formes sans argument reposaient sur un contexte $this implicite, facile à mal lire. Passez l’objet explicitement.

assert_options() et les constantes ASSERT_* sont dépréciées au profit de la directive INI zend.assertions, qui est le bon outil pour contrôler le comportement des assertions selon les environnements.

Les opérateurs ++/-- sur les chaînes vides et les chaînes non numériques non alphanumériques émettent maintenant des avertissements de dépréciation. Le comportement était un territoire indéfini. 8.3 amorce la migration vers un comportement défini en 9.0.

Protection contre les débordements de pile

Deux nouvelles directives INI : zend.max_allowed_stack_size fixe une limite dure sur la profondeur de pile de PHP, et zend.reserved_stack_size réserve un buffer pour le nettoyage après qu’une limite soit atteinte. Avant 8.3, un code récursif profond pouvait tout simplement crasher au niveau OS. Maintenant PHP l’intercepte et lève une Error avec un message utile.

Les erreurs comme ressources

Avant la 3.2, la gestion des erreurs était en dehors du modèle de ressources. Les exceptions étaient interceptées par un event listener Symfony et converties en réponse, avec un contrôle limité sur la forme de la sortie.

La 3.2 fait des erreurs des classes ApiResource de première classe conformes à la RFC 9457 (Problem Details for HTTP APIs). La classe d’erreur intégrée est ApiPlatform\ApiResource\Error, et on peut créer la sienne :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ApiResource]
#[ErrorResource]
class BookNotFoundError extends \RuntimeException implements ProblemExceptionInterface
{
    public function __construct(private readonly string $bookId)
    {
        parent::__construct("Book $bookId not found");
    }

    public function getType(): string
    {
        return '/errors/book-not-found';
    }
}

Quand cette exception est levée n’importe où dans la couche d’état, API Platform l’intercepte, la sérialise comme une réponse Problem Detail, et génère un schéma OpenAPI approprié pour elle. Le type d’erreur, le titre, le détail et le statut font tous partie du contrat de la ressource — pas des chaînes codées en dur dans un listener.

Les sous-ressources sans les contournements

Les sous-ressources existaient en 2.x mais ont été supprimées en 3.0 parce qu’elles étaient étroitement couplées à l’ancien modèle de data provider et ne pouvaient pas être proprement mappées à la nouvelle architecture orientée opération. La 3.2 les réintroduit d’une façon qui s’intègre.

Une sous-ressource est une ressource accessible via l’URI d’une ressource parente. En 3.2, elle est déclarée directement sur la ressource enfant en utilisant uriTemplate :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: [
                'bookId' => new Link(fromClass: Book::class),
            ],
        ),
    ]
)]
class Review
{
    // ...
}

Le descripteur Link rend la relation explicite. Le provider reçoit bookId dans $uriVariables et peut l’utiliser pour délimiter la requête. Pas d’inférence magique, pas de jointures implicites — la structure d’URI et l’accès aux données sont tous les deux déclarés.

canonical_uri_template pour plusieurs chemins d’accès

Quand une ressource est accessible via plusieurs URI (un endpoint direct et un endpoint de sous-ressource), OpenAPI doit savoir quelle URI est canonique pour les liens $ref. La 3.2 utilise le uriTemplate de niveau supérieur sur ApiResource comme URI canonique par défaut. Pour plus de contrôle, l’option canonical_uri_template peut être passée via extraProperties sur n’importe quelle opération pour la définir explicitement.

#[ApiResource(
    uriTemplate: '/reviews/{id}',
    operations: [
        new Get(),
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: ['bookId' => new Link(fromClass: Book::class)],
        ),
    ]
)]
class Review {}

La spec OpenAPI générée utilise l’URI canonique pour les références de schéma, gardant le document cohérent quand une ressource apparaît sous plusieurs chemins.

Types union et intersection

La 3.2 ajoute le support des types union et intersection PHP dans la couche de métadonnées. Une propriété déclarée comme Book|Magazine génère un schéma oneOf approprié dans OpenAPI. C’était auparavant non supporté — on devait tomber sur un mixed non typé ou annoter la propriété manuellement.

Les event listeners rendus optionnels

Le dernier shim de compatibilité venu de la 2.x était la possibilité d’utiliser les event listeners Symfony sur les événements kernel.request et kernel.view pour intercepter le flux de données d’API Platform. La 3.2 ne les supprime pas, mais introduit un moyen de s’en passer : passer event_listeners_backward_compatibility_layer: false dans la configuration d’API Platform désactive entièrement les hooks basés sur les événements. Le remplacement est un provider ou processor décoré par un autre provider ou processor. Le hook basé sur les événements était avec état, dépendant de l’ordre, et court-circuitait entièrement le contexte d’opération. Les providers décorés reçoivent l’objet opération et peuvent appeler le provider interne quand ils sont prêts.

Le modèle d’état est maintenant complet

La 3.0 a introduit l’architecture. La 3.1 a ajouté la séparation ressource/entité. La 3.2 ferme les lacunes restantes : les erreurs ont un contrat de ressource, les sous-ressources ont un modèle de déclaration propre, et la couche d’état couvre désormais tous les points d’extension que les event listeners géraient autrefois. Les shims 2.x existent encore, mais s’en passer n’est plus qu’une ligne de configuration.

La séparation ressource/entité

En 2.x, API Platform fonctionnait mieux quand votre ressource API et votre modèle de persistance étaient la même classe. Utiliser un DTO comme surface API était possible via le système Input/Output DTO, mais ce système a été supprimé en 3.0 — il compliquait le modèle d’état sans apporter suffisamment de bénéfices.

La 3.1 le remplace par quelque chose de plus propre. Le paramètre stateOptions d’une opération accepte un objet DoctrineOrmOptions qui pointe vers une entité différente :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Orm\State\Options;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
class BookDto
{
    public string $title;
    public string $author;
}

Le provider reçoit les objets BookEntity de Doctrine et la couche de sérialisation les mappe sur BookDto. Les filtres Doctrine, la pagination et le tri fonctionnent tous sur BookEntity. La surface API expose BookDto. Les deux peuvent évoluer indépendamment.

Ça compte plus qu’il n’y paraît. Votre modèle de persistance accumule des champs internes, des relations et des colonnes qui n’ont aucune raison d’apparaître dans votre API. Avant la 3.1, on les exposait quand même ou on construisait un normaliseur élaboré pour les cacher. Maintenant on déclare ce que l’API expose comme classe distincte et on laisse le framework gérer la correspondance.

Un PUT conforme à la spec

Depuis la version 1.0, le handler PUT d’API Platform mettait à jour des ressources existantes. Créer une ressource via PUT — ce que la spec HTTP autorise explicitement — n’était pas supporté. La 3.1 ajoute la création basée sur l’uriTemplate :

#[Put(
    uriTemplate: '/books/{id}',
    allowCreate: true,
)]

Avec allowCreate: true, un PUT vers une URI qui n’existe pas crée la ressource au lieu de retourner une 404. L’identifiant vient de l’URI, pas du corps de la requête. C’est ce que la RFC 9110 décrit pour PUT : “Si la ressource cible n’a pas de représentation courante et que le PUT en crée une avec succès, le serveur d’origine DOIT informer le user agent en envoyant une réponse 201 (Created).”

C’est un petit paramètre, mais il ouvre API Platform à des cas d’usage — création idempotente, identifiants assignés par le client — qui nécessitaient auparavant un contrôleur personnalisé.

Les erreurs de dénormalisation collectées, pas jetées

Avant la 3.1, les erreurs de désérialisation s’arrêtaient au premier problème. Envoyer un corps de requête avec cinq champs invalides renvoyait une erreur sur le premier. On le corrigeait, on renvoyait, on trouvait le deuxième. À répéter cinq fois.

La 3.1 ajoute une option collect_denormalization_errors sur l’opération qui change ce comportement :

#[Post(collectDenormalizationErrors: true)]

Avec cette option activée, API Platform intercepte toutes les erreurs de type et les violations de contraintes pendant la désérialisation et les retourne sous forme de liste structurée dans la réponse, formatée de la même façon que les erreurs de validation. Un seul aller-retour, une vue complète.

ApiResource::openapi remplace openapiContext

L’ancien paramètre openapiContext acceptait un tableau brut fusionné dans le schéma OpenAPI généré — pratique mais non typé. La 3.1 introduit un paramètre openapi de premier ordre qui accepte un objet OpenApiOperation :

use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\RequestBody;

#[Post(
    openapi: new Operation(
        requestBody: new RequestBody(
            description: 'Créer un livre',
            required: true,
        ),
        summary: 'Créer une nouvelle entrée livre',
    )
)]

L’ancien tableau openapiContext fonctionne encore mais est déprécié. La nouvelle approche est typée, compatible avec l’autocomplétion IDE, et se valide à la construction plutôt qu’à la génération du schéma. Les backed enums PHP 8.1 obtiennent également une génération de schéma OpenAPI correcte en 3.1 — un champ typé comme backed enum produit un schéma avec des valeurs enum et le type correct, sans annotation supplémentaire.

Le pattern est clair

La 3.0 a établi l’architecture. La 3.1 montre ce que cette architecture permet : une séparation propre ressource/entité sans système DTO parallèle, une sémantique HTTP correcte selon la RFC, un meilleur rapport d’erreurs. Aucune de ces fonctionnalités n’aurait été aussi propre à implémenter sur le modèle data provider de la 2.x. Les features de la 3.1 sont la première preuve que la réécriture était la bonne décision.

Les propriétés dynamiques dépréciées

PHP a toujours permis d’ajouter des propriétés à des objets sans les déclarer dans la classe :

class User {}
$user = new User();
$user->name = 'Alice'; // aucune déclaration, aucune erreur... jusqu'ici

En 8.2, ça déclenche un avertissement de dépréciation. En PHP 9.0, ce sera une erreur fatale. Le délai de grâce existe, mais le compteur tourne.

La logique est solide : les propriétés dynamiques sont une source classique de typos qui passent silencieusement (écrivez $user->nmae et PHP crée simplement une nouvelle propriété au lieu de se plaindre). Des déclarations explicites rendent le contrat de la classe lisible et donnent aux outils matière à travailler.

La migration est essentiellement mécanique : déclarez les propriétés, ou posez #[AllowDynamicProperties] sur les classes legacy que vous ne pouvez pas encore toucher.

Les classes readonly

8.1 avait ajouté readonly sur les propriétés individuelles. 8.2 l’ajoute sur la déclaration de classe elle-même :

readonly class Point {
    public function __construct(
        public float $x,
        public float $y,
        public float $z,
    ) {}
}

Toutes les propriétés promues et déclarées explicitement deviennent readonly automatiquement. Les value objects (coordonnées, montants monétaires, identifiants) sont la cible évidente. La syntaxe est propre et l’intention se lit clairement.

Une contrainte : les classes readonly ne peuvent pas avoir de propriétés non typées, ce qui était déjà une mauvaise idée avec readonly de toute façon.

Les types DNF

Les types en Forme Normale Disjonctive permettent de combiner types union et types intersection :

function process(Countable&Iterator|null $collection): void { ... }

(Countable&Iterator)|null : un objet qui implémente les deux interfaces, ou null. Cela couvre des expressions de type que les unions de 8.0 et les intersections de 8.1 approchaient chacune sans pouvoir les représenter ensemble.

L’extension Random

Une extension Random dédiée remplace les fonctions éparpillées rand(), mt_rand(), random_int() par une API orientée objet :

$rng = new Random\Randomizer();
$rng->getInt(1, 100);
$rng->shuffleArray($items);

Les moteurs sont interchangeables : Mersenne Twister, PCG64, Xoshiro256StarStar, ou CryptoSafeEngine pour les contextes sensibles à la sécurité. Même code, moteur déterministe avec seed dans les tests, moteur cryptographique en production.

8.2 est une version de consolidation. La dépréciation des propriétés dynamiques est la seule décision à prendre maintenant.

null, false, et true comme types autonomes

PHP avait les types nullable depuis 7.1 et les types union depuis 8.0, mais null comme déclaration de type autonome n’était pas valide. 8.2 corrige ça :

function alwaysNull(): null {
    return null;
}

function disabled(): false {
    return false;
}

function enabled(): true {
    return true;
}

false et true comme types autonomes sont utiles quand on veut être précis sur ce qu’une fonction peut réellement retourner. C’est étroit mais juste : une fonction qui retourne false en cas d’échec et une chaîne en cas de succès devrait déclarer string|false, et maintenant les deux côtés de cette union sont de vrais types.

Les constantes dans les traits

Les traits pouvaient contenir des propriétés et des méthodes. Les constantes étaient le trou dans la raquette. 8.2 le comble :

trait Timestamps {
    public const DATE_FORMAT = 'Y-m-d H:i:s';

    public function formatCreatedAt(): string {
        return $this->createdAt->format(self::DATE_FORMAT);
    }
}

class Article {
    use Timestamps;
}

echo Article::DATE_FORMAT; // 'Y-m-d H:i:s'

La constante appartient à la classe qui utilise le trait, pas au trait lui-même, donc on ne peut pas accéder à Timestamps::DATE_FORMAT directement. Comportement de scope attendu, cohérent avec le fonctionnement des méthodes de trait.

#[SensitiveParameter]

Les stack traces ont toujours été un risque : les arguments de fonction sont loggés verbatim, ce qui veut dire que les mots de passe et les tokens se retrouvent dans les logs d’erreur et les dashboards de monitoring. 8.2 ajoute un attribut pour stopper ça :

function authenticate(
    string $user,
    #[\SensitiveParameter] string $password,
): bool {
    // si ça lève une exception, la stack trace affiche :
    // authenticate('alice', Object(SensitiveParameterValue))
    return hash('sha256', $password) === getStoredHash($user);
}

La valeur du paramètre dans la trace est remplacée par un objet SensitiveParameterValue. Un attribut, zéro excuse pour ne pas l’ajouter sur chaque fonction qui touche à des credentials.

Les syntaxes d’interpolation de chaînes dépréciées

Deux façons d’interpoler des expressions dans des chaînes sont dépréciées en 8.2 :

$name = 'world';

// Celles-ci sont dépréciées :
echo "Hello ${name}";       // utiliser "$name" ou "{$name}"
echo "Hello ${getName()}";  // utiliser "{$this->getName()}"

Les formes ${...} créaient une ambiguïté entre les variables variables et les expressions. La syntaxe plus propre {$...} a toujours été là et fait la même chose. C’est essentiellement un travail de recherche-remplacement sur les bases de code qui ont adopté les formes dépréciées par habitude.

utf8_encode() et utf8_decode() dépréciées

Ces deux fonctions sont dépréciées en 8.2 et disparaissent en 9.0. Leur comportement a toujours été plus étroit que ce que les noms suggéraient : utf8_encode() convertit ISO-8859-1 en UTF-8, pas “n’importe quel encodage en UTF-8”.

// Déprécié en 8.2 :
$utf8 = utf8_encode($latin1String);

// Utiliser à la place :
$utf8 = mb_convert_encoding($latin1String, 'UTF-8', 'ISO-8859-1');

mb_convert_encoding() ou iconv() gèrent le cas général. Si vous traitez vraiment des entrées en Latin-1, le remplacement est direct.

Les fonctions de chaîne indépendantes de la locale

Plusieurs fonctions de chaîne variaient silencieusement leur comportement selon la locale système, produisant des résultats différents en production par rapport à un container de dev. En 8.2, elles sont indépendantes de la locale et ne gèrent que l’ASCII :

// strtolower, strtoupper, stristr, stripos, strripos,
// lcfirst, ucfirst, ucwords, str_ireplace font maintenant une conversion
// de casse ASCII uniquement.
// Pour un comportement sensible à la locale, utiliser les équivalents mb_* :
$lowered = mb_strtolower($text, 'UTF-8');

C’est un correctif de cohérence. Si votre code reposait sur le comportement sensible à la locale de ces fonctions, il était déjà cassé sur des systèmes avec des configurations de locale différentes. 8.2 rend le comportement déterministe partout, ce qui est ce qu’on voulait vraiment.

str_split() sur une chaîne vide

Un changement de comportement discret à noter :

// PHP 8.1 : str_split('') === ['']
// PHP 8.2 : str_split('') === []

Le nouveau comportement a plus de sens : découper rien ne produit rien. Si vous vérifiez count(str_split($input)), une entrée vide ne produit plus un count de 1.

L’ancien modèle avait une fuite conceptuelle. DataProviderInterface et DataPersisterInterface étaient appelés pour chaque requête HTTP, mais le provider recevait le contexte de l’opération comme un indice — pas comme un contrat. Un provider de collection et un provider d’item étaient des interfaces distinctes, mais les deux vivaient dans le même seau mental : “choses qui retournent des données.” La couche HTTP savait ce qui était demandé ; le provider devait reconstruire cette connaissance à partir d’indices passés dans le tableau $context.

La 3.0 inverse le modèle. Les opérations sont déclarées en premier. L’accès aux données est câblé aux opérations.

Les state providers remplacent les data providers

L’ancien DataProviderInterface a disparu. Le remplaçant est ProviderInterface :

use ApiPlatform\State\ProviderInterface;
use ApiPlatform\Metadata\Operation;

class BookProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            return $this->repository->findAll();
        }

        return $this->repository->find($uriVariables['id']);
    }
}

La différence n’est pas syntaxique. En 2.x, on enregistrait un provider et API Platform l’appelait pour toute ressource correspondante. En 3.0, on lie un provider à une opération spécifique. Le provider n’a plus à deviner ce qui l’a déclenché — l’objet opération qu’il reçoit est le contrat.

Les state processors remplacent les data persisters

DataPersisterInterface avait le même problème côté écriture : une seule classe gérant la création, la mise à jour et la suppression, les distinguant en inspectant la méthode HTTP ou l’état de l’objet. ProcessorInterface reçoit l’opération comme argument typé :

use ApiPlatform\State\ProcessorInterface;
use ApiPlatform\Metadata\Operation;

class BookProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        $this->entityManager->persist($data);
        $this->entityManager->flush();

        return $data;
    }
}

Plus utile encore : on peut lier un processor différent par opération. L’opération de suppression en reçoit un qui supprime. L’opération de création en reçoit un qui valide et stocke. Pas de switch, pas d’inspection de méthode, pas de classe partagée qui essaie d’être trois choses à la fois.

Les opérations déclarées explicitement en attributs PHP 8.1

L’autre moitié de la 3.0 est la couche de métadonnées. Les annotations Doctrine sont remplacées par des attributs natifs PHP 8.1, et chaque opération est déclarée explicitement sur la classe ressource :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new GetCollection(provider: BookProvider::class),
        new Get(provider: BookProvider::class),
        new Post(processor: BookProcessor::class),
    ]
)]
class Book
{
    // ...
}

C’est plus verbeux que @ApiResource avec ses valeurs par défaut magiques. C’est aussi explicite. On sait exactement quelles opérations HTTP existent pour cette ressource, ce qui récupère les données, ce qui les écrit, et où vit la logique. Les valeurs par défaut de la 2.x étaient pratiques jusqu’au jour où il fallait en surcharger une sans réussir à déterminer quel service décorer sans lire le code source.

PHP 8.1 n’était pas un hasard

L’exigence stricte pour PHP 8.1 est structurante. Les callables de première classe rendent l’enregistrement des filtres plus propre. L’immuabilité des métadonnées d’opération est assurée par un pattern de clonage (méthodes withX()) qui s’appuie sur les arguments nommés et les propriétés de constructeur promues — des fondations PHP 8.0 sur lesquelles l’architecture s’appuie massivement.

Plus concrètement : l’expression complète de l’architecture 3.0 — opérations typées, providers scopés à l’opération, métadonnées explicites — avait besoin de la 8.1 pour ne pas ressembler à des contournements. Abandonner PHP 7.x et 8.0 n’était pas une décision de nettoyage.

La migration est un vrai travail

Le passage de 2.x à 3.0 n’est pas un simple bump de version. Chaque DataProvider devient un ProviderInterface. Chaque DataPersister devient un ProcessorInterface. Les annotations deviennent des attributs. Les normaliseurs et filtres personnalisés peuvent nécessiter une restructuration. Le guide de mise à jour documente tout cela, mais “documenté” ne veut pas dire “rapide.”

Ce qu’on obtient de l’autre côté est une architecture qui passe à l’échelle sans la complexité ambiante de la 2.x : plus besoin de deviner quelle interface implémenter, plus de chaînes $this->supports(), plus de valeurs par défaut invisibles qui surchargent silencieusement la config explicite.

La 3.0 est l’API Platform qu’on concevrait de zéro en sachant ce qu’on sait après des années de 2.x. Le prix est la migration. Le numéro de version est honnête là-dessus.

Ça vient avec le framework. Ça a de la logique de retry, du support AMQP natif, de la documentation first-party. Notre setup ressemblait à de l’artisanat par comparaison.

Question légitime. On l’a prise au sérieux. Voilà ce qu’on a trouvé.

Câbler la topologie à la main

Swarrot est une bibliothèque consumer qui enveloppe l’extension PECL AMQP. Elle lit des octets depuis une queue, les fait passer à travers une chaîne de processors (leur terme pour middleware), et laisse votre code décider quoi faire avec le payload. C’est vraiment tout.

La chaîne de middleware est la partie intéressante. Les processors sont des décorateurs imbriqués, chacun enveloppant le suivant. Les couches extérieures gèrent les préoccupations d’infrastructure avant même que le message n’atteigne la logique métier :

middleware_stack:
    - configurator: 'swarrot.processor.signal_handler'
    - configurator: 'swarrot.processor.max_execution_time'
    - configurator: 'swarrot.processor.exception_catcher'
    - configurator: 'swarrot.processor.doctrine_object_manager'
    - configurator: 'swarrot.processor.ack'
    - configurator: 'app.processor.retry'

signal_handler est en tête parce qu’il doit intercepter SIGTERM avant que tout autre processor ne le voie. ack est près du bas parce qu’on n’acquitte le message qu’après que le traitement réussit. L’ordre n’est pas arbitraire, et il est entièrement visible dans la configuration.

La topologie est tout aussi explicite. On déclare tout soi-même : exchanges, routing keys, queues de retry, queues de lettres mortes :

messages_types:
    content.ingest:
        exchange: e.app.content
        routing_key: q.app.content.ingest
    content.ingest_retry:
        exchange: e.app.content
        routing_key: q.app.content.ingest.retry
    content.ingest_dead:
        exchange: e.app.content
        routing_key: q.app.content.ingest.dead

Trois entrées par type de message logique : queue principale, queue de retry, queue de lettres mortes. Tout ce qui existe sur le broker est nommé ici. La config est verbeuse mais honnête : pas d’inférence, pas de convention plutôt que configuration. Si une queue existe dans RabbitMQ, on peut la tracer jusqu’à une seule ligne de YAML.

Quand le nom de classe devient la route

Symfony Messenger opère un niveau plus haut. On définit une classe de message, un handler, et un transport. La bibliothèque gère la sérialisation, le routing, le retry et les queues d’échec automatiquement.

class IngestContent
{
    public function __construct(
        public readonly string $contentId,
        public readonly string $source,
    ) {}
}

framework:
    messenger:
        transports:
            async:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                retry_strategy:
                    max_retries: 3
                    delay: 1000
        routing:
            'App\Message\IngestContent': async

Messenger sérialise l’objet, le met sur le transport, et le désérialise de l’autre côté dans la classe correcte. Pas de topologie manuelle, pas de noms d’exchange explicites. Le nom de classe est la primitive de routing.

Cette dernière phrase est exactement là où les choses se sont compliquées pour nous.

Quand le typage devient du couplage

Messenger suppose que le producteur et le consumer partagent une définition de classe PHP. C’est bien pour une seule application, ou pour des services qui partagent un package de contrats dédié. Dans un monorepo d’applications Symfony indépendantes, ça crée un couplage qui n’existe tout simplement pas aujourd’hui.

Prenez un message d’ingestion de contenu que douze services consomment. Avec Swarrot, chaque service lit le payload JSON brut et prend les champs qui l’intéressent. Ajouter un nouveau champ signifie mettre à jour le producteur. Les consumers qui n’ont pas besoin du champ continuent de fonctionner sans modification.

Avec Messenger, IngestContent doit être définie quelque part que les douze services peuvent référencer. Ça signifie soit :

• Un package PHP partagé, versionné, déployé et maintenu à travers les services. Chaque changement de schéma devient un exercice de coordination inter-services.
• Des classes dupliquées dans chaque service, qui divergent silencieusement sous la pression.

Ni l’une ni l’autre n’est gratuite. L’approche package partagé inverse le modèle de propriété : le schéma de message devient une dépendance plutôt qu’un contrat défini à la frontière. L’approche duplication est juste le problème original différé.

La différence fondamentale est ce que représente un message. Messenger est conçu pour des commandes typées : un objet qui porte du sens et se distribue à un handler spécifique. Swarrot traite les messages comme des données opaques : des octets qui coulent à travers une topologie, traités par le consumer qui écoute. Si vos messages sont des données, l’abstraction supplémentaire qu’ajoute Messenger ne vous aide pas. Elle crée de la friction.

Le bloquant

Le problème de sérialisation était le décisif. Dans un monorepo où les services sont autonomes, partager des classes PHP entre eux n’est pas architecturalement neutre : c’est une décision de couplage qui rend les changements futurs plus difficiles. On aurait échangé une bibliothèque nominalement “legacy” pour une plus moderne tout en introduisant exactement le genre de couplage fort qu’on avait passé des années à éviter.

Il y avait des préoccupations secondaires aussi. L’extension PECL AMQP donne un accès direct aux fonctionnalités du broker (priorités de messages, TTL par queue, routing par headers exchange) que Messenger abstrait. Et migrer quinze consumers sans jour J signifie faire tourner les deux bibliothèques en parallèle, ce qui est une vraie contrainte opérationnelle.

Mais le problème de sérialisation seul aurait suffi.

Données ou commandes : voilà la question

Le choix ne concerne pas la qualité des bibliothèques. Messenger est bien maintenu, bien documenté, et s’intègre proprement dans l’écosystème Symfony.

La question à se poser en premier est : que sont vos messages ?

Si ce sont des commandes typées avec un schéma connu et un seul consumer faisant autorité, Messenger est un choix naturel. On écrit une classe, un handler, on configure un transport, et l’infrastructure gère le reste.

Si ce sont des payloads de données consommés par plusieurs services indépendants, chacun possédant sa propre désérialisation, l’abstraction qu’ajoute Messenger joue contre vous. La topologie explicite de Swarrot et son modèle de payload brut donnent plus de contrôle là où on en a vraiment besoin.

Une vraie limitation à garder à l’esprit : Swarrot est lié à l’extension PECL AMQP, qui n’implémente qu’AMQP 0-9-1. Ce qui signifie que RabbitMQ (ou un broker compatible) est une dépendance dure. Si l’infrastructure migre un jour vers un broker AMQP 1.0 (Azure Service Bus, ActiveMQ Artemis), Swarrot ne peut pas suivre. La couche transport de Messenger abstrait ça proprement : changer de broker signifie changer un DSN, pas réécrire les consumers.

Si la portabilité de broker est une exigence, ou susceptible de le devenir, ça change significativement le calcul.

Swarrot n’est pas du legacy à migrer. Pour l’instant, c’est le bon choix : le routing AMQP comme primitive, les messages comme données, RabbitMQ comme choix d’infrastructure long terme.

Ça pourrait changer. Un package de contrats partagé, une nouvelle exigence de broker, un service greenfield qui ne porte pas le poids de la topologie existante : n’importe lequel de ces éléments pourrait faire pencher la balance vers Messenger. La bibliothèque n’est pas inadaptée à cette plateforme. Elle est peut-être juste la bonne réponse pour une version future de celle-ci.

Ce n’est pas juste un bump de version. C’est un engagement à construire contre le langage actuel plutôt que le plancher historique.

Le système de sécurité, enfin reconstruit

Le composant de sécurité Symfony a deux systèmes. L’ancien (AnonymousToken, GuardAuthenticatorInterface, un enchevêtrement d’interfaces qui vous faisaient implémenter des méthodes dont vous n’aviez pas besoin) avait été déprécié. 6.0 le supprime entièrement.

Le nouveau système de sécurité (security.enable_authenticator_manager: true en 5.x) est maintenant le seul système. C’est plus propre : une seule interface à implémenter, séparation claire entre authentification et autorisation, vérification des credentials basée sur des passeports. La migration depuis les anciens guard authenticators n’est pas indolore, mais la destination est beaucoup moins confuse.

La classe Path du Filesystem

Travailler avec des chemins de fichiers en PHP est fondamentalement un problème de manipulation de strings. __DIR__, concaténation, realpath(), séparateurs spécifiques à la plateforme : la bibliothèque standard donne des primitives mais pas vraiment un modèle.

La nouvelle classe Path gère ça :

use Symfony\Component\Filesystem\Path;

Path::join('/var/www', 'html', '../uploads'); // /var/www/uploads
Path::makeRelative('/var/www/html', '/var/www'); // html
Path::isAbsolute('./relative/path'); // false

Multiplateforme, sans effets de bord, sans accès au filesystem nécessaire. Aussi dans 6.0 : support des patterns .gitignore imbriqués dans Finder.

Les enums dans le système de formulaires

En s’appuyant sur les fondations posées par 5.4, 6.0 pousse le support des enums plus loin. Les valeurs BackedEnum font des allers-retours à travers les formulaires et le sérialiseur sans transformateurs personnalisés. Le composant de formulaire comprend les cases d’enum comme options de choix nativement.

Ce que 6.0 supprime

La liste des suppressions est extensive : l’ancien système de sécurité, le composant Templating, le support des annotations PHP (remplacées par les attributs natifs), le support du cache Doctrine, ContainerAwareTrait. Six années de marqueurs @deprecated accumulés, finalement nettoyés.

Les applications qui avaient pris au sérieux les warnings de dépréciation de 5.4 avaient un chemin de migration propre. Celles qui ne l’avaient pas fait avaient du travail à faire.

La complétion automatique était toujours le manque

Le composant Console a reçu l’autocomplétion shell, et c’est proprement intégré : définir une méthode complete() sur sa commande, et Tab dans Bash suggère des valeurs valides pour les options et arguments.

class DeployCommand extends Command
{
    public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
    {
        if ($input->mustSuggestOptionValuesFor('env')) {
            $suggestions->suggestValues(['prod', 'staging', 'dev']);
        }
    }
}

Toutes les commandes Symfony intégrées ont reçu la complétion aussi : debug:router, cache:pool:clear, lint:yaml, et une quinzaine d’autres. Exécuter bin/console completion bash >> ~/.bashrc et c’est terminé.

Messenger, maintenant avec attributs et traitement par lots

L’attribut #[AsMessageHandler] remplace l’ancienne MessageHandlerInterface. Moins de boilerplate, et on peut maintenant configurer l’affinité de transport et la priorité directement sur l’attribut :

#[AsMessageHandler(fromTransport: 'async', priority: 10)]
class SendWelcomeEmailHandler
{
    public function __invoke(UserRegistered $message): void { ... }
}

L’autre ajout significatif : BatchHandlerInterface. Quand on insère un millier de lignes, traiter les messages un par un est du gaspillage. Les batch handlers collectent les messages et les traitent en groupes. La taille de lot par défaut est 10, contrôlée par BatchHandlerTrait::shouldFlush(). L’Acknowledger gère le succès et l’échec individuels dans le lot.

reset_on_message: true dans la config Messenger réinitialise les services du conteneur entre les messages. Auparavant, un buffer Monolog pouvait se remplir à travers la gestion des messages et personne ne s’en rendait compte avant la production. Ça évite cette catégorie de bugs de stateful sans nécessiter de nettoyage manuel.

Le conteneur DI devient plus expressif

Trois changements qui comptent en pratique.

Les types union et intersection s’autowire maintenant. PHP 8.1 a ajouté les types intersection, et Symfony 6.0 les câble :

public function __construct(
    private NormalizerInterface&DenormalizerInterface $serializer
) {}

Ça fonctionne tant que les deux interfaces pointent vers le même service via les alias d’autowiring.

TaggedIterator et TaggedLocator ont reçu les options defaultPriorityMethod et defaultIndexMethod. On n’a plus besoin de YAML pour exprimer l’ordonnancement ou l’indexation pour les services taggués :

public function __construct(
    #[TaggedIterator(tag: 'app.handler', defaultPriorityMethod: 'getPriority')]
    private iterable $handlers,
) {}

SubscribedService (l’attribut qui remplace la magie implicite de ServiceSubscriberTrait) rend l’accès paresseux aux services explicite et typable :

#[SubscribedService]
private function mailer(): MailerInterface
{
    return $this->container->get(__METHOD__);
}

La validation reçoit trois nouveaux outils

CssColor valide les valeurs de couleurs CSS dans les formats voulus : hex, RGB, HSL, couleurs nommées, ou n’importe quel mélange. Utile pour les champs de configuration de thème où on veut accepter #ff0000 mais pas red, ou vice versa.

#[Assert\CssColor(formats: Assert\CssColor::HEX_LONG)]
private string $brandColor;

Cidr valide la notation CIDR pour IPv4 et IPv6, avec des options pour fixer la version et contraindre la plage de masque réseau. Les outils d’infrastructure et les formulaires de config réseau ont enfin une contrainte de première classe.

Le troisième ajout n’est pas une nouvelle contrainte. Ce sont les attributs imbriqués PHP 8.1 qui rendent les contraintes composées existantes utilisables sans XML. AtLeastOneOf, Collection, All, Sequentially : tout ça nécessitait auparavant des contournements d’annotation. Maintenant ça fonctionne juste comme attributs :

#[Assert\Collection(
    fields: [
        'email' => new Assert\Email(),
        'role'  => [new Assert\NotBlank(), new Assert\Choice(['admin', 'user'])],
    ]
)]
private array $payload;

Le sérialiseur, nettoyé

Deux choses. D’abord, le contexte de sérialisation est maintenant configurable globalement au lieu d’être répété à chaque appel serialize() :

# config/packages/serializer.yaml
serializer:
    default_context:
        enable_max_depth: true

Ensuite, l’option COLLECT_DENORMALIZATION_ERRORS change comment le sérialiseur gère les erreurs de type à la désérialisation. Au lieu de lever une exception au premier problème, il les collecte tous et les expose via PartialDenormalizationException. Si on écrit une API qui désérialise des corps de requête, c’est la différence entre retourner “le premier champ qui échoue” et “tous les champs qui échouent” dans une seule réponse.

Les utilitaires de string que personne ne savait vouloir

trimPrefix() et trimSuffix() sur les classes UnicodeString / ByteString. Pas glamour, mais supprimer un préfixe connu avec ltrim() est un piège subtil : ça supprime des caractères, pas des strings. Ceux-ci sont corrects :

use function Symfony\Component\String\u;

u('file-image-001.png')->trimPrefix('file-');   // 'image-001.png'
u('report.html.twig')->trimSuffix('.twig');     // 'report.html'

Aussi dans cette version : NilUlid pour les ULIDs à valeur zéro, perMonth() et perYear() sur RateLimiter pour quand les limites horaires n’ont pas de sens, et appendToFile() dans le composant Filesystem a reçu un paramètre LOCK_EX optionnel pour les écrivains concurrents.

Déboguer l’environnement

debug:dotenv est une nouvelle commande console qui montre quels fichiers .env ont été chargés et d’où vient chaque valeur. Quand on a .env, .env.local, .env.test, et .env.test.local qui se battent et que quelque chose ne va pas, cette commande dit exactement quel fichier a gagné. Elle n’apparaît que quand le composant Dotenv est utilisé, ce qui est le cas pour toute application Symfony standard.

5.4 est la version LTS, et son rôle est de porter autant que possible le jeu de fonctionnalités de 6.0 tout en conservant la compatibilité 5.x. C’est aussi la première version de Symfony qui comprend réellement les fonctionnalités de PHP 8.1.

Support des enums

PHP 8.1 a introduit les enums natifs. Symfony 5.4 les embrasse immédiatement :

enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

Le type de formulaire EnumType rend les enums sous forme de listes déroulantes, sans transformateurs personnalisés. Le validateur comprend les backed enums. Le sérialiseur mappe les valeurs d’enum sur leur type de backing et inversement. Trois composants mis à jour d’un coup, ce qui a rendu la migration des bases de code des pseudo-constantes enum vers les vrais enums PHP 8.1 étonnamment fluide.

Cache des voters de sécurité

La CacheableVoterInterface permet aux voters qui s’abstiennent toujours sur un attribut donné de le signaler au système de sécurité, qui peut alors les ignorer lors des vérifications suivantes. Pour les applications avec de nombreux voters, le gain sur les vérifications de permissions s’accumule vite. Petit changement, perceptible en pratique.

Messenger continue de mûrir

Le traitement par batch de Messenger (gérer plusieurs messages en une seule transaction au lieu d’un par un) est maintenant stable. Rate limiting par transport. Les dead letter queues bénéficient de meilleurs outils. Après des années en mode « expérimental », Messenger en 5.4 est enfin la fondation async sur laquelle on peut s’appuyer pour des charges sérieuses.

La Console a eu sa touche Tab

Symfony 5.4 embarque l’autocomplétion shell pour toutes les commandes. Appuyez sur Tab et le shell suggère les noms de commandes, les valeurs d’arguments et les valeurs d’options. Pour les commandes intégrées, ça fonctionne sans configuration. Pour les commandes personnalisées, ajoutez une méthode complete() :

use Symfony\Component\Console\Completion\CompletionInput;
use Symfony\Component\Console\Completion\CompletionSuggestions;

public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
{
    if ($input->mustSuggestOptionValuesFor('format')) {
        $suggestions->suggestValues(['json', 'xml', 'csv']);
    }
}

Pas d’interface requise, juste la méthode et Symfony s’en charge. La communauté a aussi passé en revue toutes les commandes intégrées (debug:router, cache:pool:clear, secrets:remove, lint:twig, et une dizaine d’autres) pour ajouter les compléments avant la sortie.

Les routes peuvent être des alias maintenant

Le composant de routing supporte désormais les alias : une route peut pointer vers une autre. Le cas d’usage évident, c’est renommer une route sans casser tout ce qui génère encore des URLs avec l’ancien nom.

# config/routes.yaml
admin_dashboard:
    path: /admin

# ancien nom conservé pendant la transition
dashboard:
    alias: admin_dashboard
    deprecated:
        package: 'acme/my-bundle'
        version: '2.3'

Générer une URL avec dashboard fonctionne toujours, mais déclenche un avertissement de dépréciation. Des chemins de renommage propres pour les bundles qui doivent maintenir des noms de routes publics tout en avançant.

Les exceptions sont mappées aux codes HTTP dans la config

Avant 5.4, mapper une classe d’exception à un code HTTP signifiait implémenter HttpExceptionInterface ou écrire un listener. Maintenant c’est juste une entrée YAML :

# config/packages/framework.yaml
framework:
    exceptions:
        App\Exception\PaymentRequiredException:
            status_code: 402
            log_level: warning
        App\Exception\MaintenanceException:
            status_code: 503
            log_level: info

L’exception n’a rien à implémenter. Le framework lit la map, définit le code de statut, loggue au niveau configuré. Pratique pour les exceptions métier qui n’ont aucune raison de connaître HTTP.

Deux nouvelles contraintes de validation

5.4 ajoute Cidr et CssColor au composant Validator.

Cidr valide la notation réseau (adresse IP plus masque de sous-réseau) avec un contrôle sur la version IP acceptée et les bornes de la valeur du masque :

#[Assert\Cidr(version: 4, netmaskMin: 16, netmaskMax: 28)]
private string $allowedSubnet;

CssColor valide qu’une chaîne est une couleur CSS valide. Utile pour les éditeurs de thème, la config CMS, ou toute interface qui laisse les utilisateurs choisir des couleurs :

#[Assert\CssColor(
    formats: Assert\CssColor::HEX_LONG,
    message: "La couleur d'accentuation doit être une valeur hex à 6 chiffres.",
)]
private string $accentColor;

Attributs PHP imbriqués pour les contraintes de validation

Symfony 5.2 avait ajouté les contraintes de validation en attributs PHP, mais PHP 8.0 avait une limitation sur les attributs imbriqués. Les contraintes complexes comme All, Collection, ou AtLeastOneOf étaient impossibles à exprimer avec la syntaxe d’attribut seule. PHP 8.1 a levé cette restriction, et 5.4 en tire le meilleur parti :

use Symfony\Component\Validator\Constraints as Assert;

class CartItem
{
    #[Assert\All([
        new Assert\NotNull(),
        new Assert\Range(min: 1),
    ])]
    private array $quantities;

    #[Assert\AtLeastOneOf(
        constraints: [new Assert\Email(), new Assert\Url()],
        message: 'Doit être un email ou une URL valide.',
    )]
    private string $contact;
}

Pas de docblocks d’annotations, pas de mapping XML. Des attributs PHP 8.1 purs, de bout en bout.

Injection de dépendances : trois choses à savoir

Les itérateurs taggués peuvent maintenant être injectés dans des service locators, qui n’acceptaient auparavant que des listes de services explicites. L’autowiring des types union fonctionne quand les deux côtés de l’union résolvent vers le même service, ce qui est courant avec les interfaces du serializer :

public function __construct(
    private NormalizerInterface & DenormalizerInterface $serializer
) {}

#[SubscribedService] remplace l’introspection automatique que ServiceSubscriberTrait faisait implicitement. C’est maintenant un attribut explicite sur les méthodes, ce qui rend la dépendance visible sans aucune magie :

use Symfony\Contracts\Service\Attribute\SubscribedService;

class SomeService implements ServiceSubscriberInterface
{
    #[SubscribedService]
    private function router(): RouterInterface
    {
        return $this->container->get(__METHOD__);
    }
}

Messenger : attributs, état des workers et reset de services

Les handlers Messenger peuvent abandonner MessageHandlerInterface en faveur de #[AsMessageHandler], qui permet aussi de lier un handler à un transport spécifique et de définir sa priorité, sans toucher au YAML :

#[AsMessageHandler(fromTransport: 'async', priority: 10)]
class ProcessOrderHandler
{
    public function __invoke(ProcessOrder $message): void { /* ... */ }
}

L’état des workers est maintenant inspectable via WorkerMetadata dans les event listeners, utile quand vous avez des workers sur plusieurs transports et avez besoin de savoir lequel a déclenché un événement donné.

Les workers longue durée accumulent de l’état entre les messages : buffers de l’entity manager, caches en mémoire, connexions ouvertes. La nouvelle option reset_on_message prend en charge la réinitialisation de tous les services réinitialisables entre les messages :

framework:
    messenger:
        reset_on_message: true

Serializer : collecter les erreurs plutôt que lever

Désérialiser du JSON externe dans un DTO typé levait une exception dès la première discordance de type. L’option COLLECT_DENORMALIZATION_ERRORS change ça : toutes les erreurs de type sont collectées dans une PartialDenormalizationException, pour que vous puissiez retourner un 400 propre avec la liste complète des problèmes par champ :

try {
    $dto = $serializer->deserialize($request->getContent(), OrderDto::class, 'json', [
        DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true,
    ]);
} catch (PartialDenormalizationException $e) {
    return $this->json(
        array_map(fn($err) => ['path' => $err->getPath(), 'expected' => $err->getExpectedTypes()], $e->getErrors()),
        400
    );
}