Comment faire de la recherche hybride avec ES|QL dans Elasticsearch ?

La recherche hybride dans ES|QL s'effectue via la syntaxe FORK. Elle permet d'exécuter parallèlement une recherche textuelle classique et une recherche sémantique, puis de combiner les scores grâce à l'opérateur FUSE (utilisant par exemple l'algorithme RRF).

Qu'est-ce que DiskBBQ et quel est son impact sur les performances ?

DiskBBQ est une optimisation introduite dans Elasticsearch 9.2 qui regroupe les vecteurs par similarité sur le disque pour permettre une lecture séquentielle plutôt qu'aléatoire.

Pourquoi recommander l'utilisation du type natif semantic_text ?

Le type 'semantic_text' est recommandé car il simplifie drastiquement l'usage de l'IA dans Elasticsearch. Il permet de s'affranchir de la gestion complexe du chunking, du calcul des dimensions et du stockage manuel des vecteurs. Le moteur gère l'ensemble du processus de manière transparente, rendant son utilisation aussi simple qu'un champ texte standard.

JoliCode blog - les derniers articles

Notre retour sur le SymfonyLive Paris 2026

2026-04-08T15:42:00+02:00

Les années passent, mais certaines traditions restent immuables. Il y a quelques jours, la communauté s'est de nouveau réunie à la Cité Universitaire pour l'édition 2026 du Symfony Live Paris.

Si le monde de la tech avance à toute vitesse, le cru 2026 conserve la recette qui a fait son succès. Nous étions, comme à notre habitude, présents au rendez-vous. Voici notre retour sur une édition qui prouve que Symfony reste à la pointe des évolutions.

Keynote de Fabien Potencier

Fabien Potencier nous a présenté un composant Symfony que beaucoup de gens attendaient impatiemment depuis sa première annonce datant de la SymfonyCon 2023 : Symfony TUI (pour Terminal User Interface) !

Avec l'arrivée récente et massive de l’IA dans les habitudes de travail de beaucoup de développeurs, Fabien a trouvé une raison parfaite de relancer son travail sur le composant TUI pour permettre une utilisation plus ergonomique et avancée des LLMs directement depuis un terminal.

On a d’ailleurs eu le droit à une démonstration de son propre coding agent pour voir en direct ce à quoi on pourrait s’attendre avec l'adoption de ce composant pour discuter avec des LLMs. Et le rendu rivalise avec ce qui peut aujourd’hui être proposé directement dans nos IDEs.

Mais au-delà de l’intégration évidente avec l’IA, le composant TUI, c’est aussi une évolution du composant Symfony Console que l’on utilise tous (pour rappel, il s’agit de l’un des premiers composants de l’écosystème Symfony, sorti il y a 15 ans maintenant). L’objectif ici, c’est de laisser Console s’occuper des parties commandes/arguments/output, pour concentrer toute la partie affichage, interaction et interactivité dans TUI.

Lors de ce talk assez orienté technique, Fabien a expliqué comment TUI fonctionne sous le capot. Sans entrer dans les détails ici, on pourra retenir :

Il existe trois manières de gérer le style: à la manière stylesheet avec des sélecteurs semblables au CSS ; avec des classes utilitaires, comme on le ferait en Tailwind ; ou directement in-line, pour prendre la main de manière ponctuelle comme c'est possible en HTML. Les breakpoints sont aussi gérés avec des media-queries, pour un rendu nativement responsive ;
Beaucoup de Widgets sont disponibles nativement pour gérer la majorité des cas d’usages (ex: TextWidget pour affichage de texte et ASCII, InputWidget pour les entrées textuelles, SelectListWidget pour des listes scrollables, etc.) mais il est évidemment possible de créer nos propres widgets pour des cas particuliers ;
TUI utilise PHP Fibers et Revolt pour assurer un affichage et des animations complètement asynchrones et une gestion parallèle de l’affichage et de l’interactivité avec le développeur.

La liste s’allonge évidemment, et toutes les informations sont disponibles sur le Blog Post dédié à l’arrivée de Symfony TUI.

Pour conclure cette première conférence, Fabien s'est montré particulièrement enthousiaste. Ce nouveau composant Symfony ouvre des portes immenses, aussi bien pour l'affichage dans la console que pour l'intégration de l'intelligence artificielle.

Pour prouver la puissance de son outil, il a même fait une démonstration impressionnante : un jeu de Tetris tournant en direct dans son terminal ! Le rendu est fluide et visuellement bluffant, montrant que l'on peut désormais créer de véritables interfaces graphiques (TUI) modernes, directement en PHP.

Pour terminer, Fabien a lancé une idée très originale pour le futur des contributions sur ce composant : plutôt que d'envoyer une solution toute prête, les développeurs pourraient simplement partager un prompt (une instruction pour l'IA).

Fabien utiliserait alors son propre assistant et ses propres ressources pour transformer ces instructions en code réel et donner vie aux futures améliorations du projet !

La communauté au rythme de l’IA

On se souvient du SymfonyLive 2024, où l’IA générative d'images s'invitait déjà dans de nombreuses présentations. À l'époque, c’était encore une nouveauté impressionnante, bien que limitée. Cette année, le changement est radical : les agents IA étaient omniprésents dans bon nombre de sujets. Cela reflète parfaitement l'évolution de notre quotidien de développeur, qui s'accélère de plus en plus dans cette direction.

Aujourd'hui, l'IA n'est plus juste un gadget visuel, elle est au cœur du développement de Symfony :

Les nouvelles versions de Twig (le moteur de templates de Symfony) sont désormais gérées de manière quasi automatique par un agent ;
Une grande partie du code source est également générée par des assistants intelligents.

Cependant, un point reste essentiel : l'IA aide à produire, mais elle ne remplace pas l'humain. La responsabilité finale appartient toujours à la personne qui valide le code. C'est le développeur qui vérifie et garantit la qualité de ce qui est produit avant de l'envoyer en production.

L’IA au service des devs : Anatomie d'un assistant de Code Review - Thomas Boileau

La volonté de Thomas est de normaliser l’utilisation de l’IA au sein de sa société. Son constat est qu’il est difficile d’intervenir dans le cycle de développement logiciel, au niveau individuel, car l’usage de l’IA est encore très inégal selon les développeurs. C’est pour ça qu’il a préféré intervenir sur la CI.

Lors de sa présentation, il nous expose donc un cas pratique. Son but : construire un assistant IA qui intervient au moment des code reviews.

Techniquement, dès qu'une PR est labellisé Ready For Review (RFR) alors un webhook est lancé, et l’assistant IA est déclenché.

Ici, ce que l'on apprend n’est pas réellement comment utiliser l’IA, mais plutôt un rappel bienvenu sur l’adoption d’une fonctionnalité par des utilisateurs. Il nous a bien expliqué qu’après sa première itération, quasiment personne n'interagissait avec son agent de revue de code.

En effet, comme toutes les nouveautés, l’essentiel, c'est de construire avec les utilisateurs finaux et d’éviter au maximum la friction. C’est donc après avoir mesuré l’usage de son bot et consulté les développeurs (utilisateurs) qu’il a proposé une nouvelle version, cette fois-ci plus utile pour tout le monde.

Évidement, Thomas nous rappelle qu’il aurait pu utiliser une solution sur étagère, mais il souligne les contraintes réglementaires qui s'appliquent à son domaine.

Sa conclusion est que le plus important dans ce projet reste la DX pour avoir une bonne adoption, et surtout que ce bot IA ne remplace pas l'humain, il est créé dans le but d’être seulement un plus dans la boucle.

Développer un Coding Agent en PHP : dans les coulisses du "Harness" - Fabien Potencier

Tout a commencé par un défi sur Twitter. Un utilisateur affirmait qu'il était impossible de créer un coding agent (un assistant capable de coder de façon autonome) performant en utilisant le langage PHP. Piqué au vif, Fabien Potencier, le créateur de Symfony, a décidé de prouver le contraire en développant son propre assistant.

Plutôt que d'utiliser des outils tout prêts comme GitHub Copilot ou Claude Code, fabriquer son propre agent permet de comprendre les coulisses de l’intelligence artificielle. On découvre alors comment se déroule réellement une "discussion" entre un développeur et un modèle de langage (LLM).

Pour rendre l'outil agréable à utiliser, il a utilisé le composant TUI de Symfony. Cela permet d'avoir une interface textuelle interactive directement dans sa console.

Pour que l'agent soit intelligent, il doit communiquer avec un modèle (comme Claude Opus, Claude Sonnet, GPT 5). Mais les modèles évoluent sans cesse. Fabien a donc créé un petit outil, symfony/models-dev, qui répertorie de manière automatique tous les modèles disponibles afin de toujours utiliser la version la plus récente.

Discuter avec un chat, c'est facile. Mais pour qu'un agent soit utile, il doit pouvoir agir sur votre ordinateur. C'est là qu'interviennent les Tools (outils). De manière surprenante, Fabien n'a eu besoin que de 4 outils de base :

Read : pour lire le contenu d'un fichier.
Write : pour créer un nouveau fichier.
Update : pour modifier un fichier existant sans gaspiller de token.
Bash : pour exécuter n'importe quelle commande (lancer des tests, installer un package, etc.).

Un agent classique oublie tout dès que la session se ferme. Pour corriger cela, chaque échange est enregistré dans une base de données.

L’astuce géniale ? Cette mémoire est stockée sous forme d'arbre. Cela permet à l'agent de revenir en arrière à un point précis pour tester une autre solution si la première n'a pas fonctionné.

Plus on discute avec l'IA, plus le "contexte" (le nombre de mots envoyés) devient important. Si on dépasse la limite du modèle, il sature. Fabien a donc mis en place un système de compression intelligent :

Il garde toujours le tout premier message (les instructions de base).
Il garde les derniers messages récents.
Il résume tout ce qui se trouve entre les deux.

Les conseils de Fabien

Durant sa démonstration, il a partagé quelques astuces précieuses :

Les Skills : Dès qu'il réalise qu'il répète une tâche, ou une instruction, il crée un "skill" (une compétence) pour son agent. C'est comme écrire des tests : on a l'impression de perdre du temps au début, mais on en gagne énormément sur le long terme ;
Le regard neuf : Parfois, l'IA s'embrouille. Fabien conseille de lui demander d'analyser la situation avec "un regard neuf" (fresh eyes). Cela donne souvent des résultats spectaculaires pour débloquer un bug complexe.

Bien qu'il n'ait pas eu le temps de tout montrer, notamment son système d'orchestration dans le cloud, la preuve est faite : le PHP est un langage de choix pour l'intelligence artificielle !

Embeddings en PHP : Symfony AI en pratique - Grégoire Pineau

Le talk de Grégoire nous met tout de suite dans la pratique avec une vraie mise en situation autour des embeddings et de la similarité de contenu.

Il part sur un cas d’usage qui parle à tout le monde : faire correspondre des URLs entre un ancien et un nouveau site. Là où on pourrait partir sur des règles compliquées ou du matching approximatif, les embeddings offrent une solution plus robuste : on compare directement le sens sémantique des pages.

Ce qui marche particulièrement bien, c’est le fil rouge visuel de la conférence. Un schéma du processus est affiché, puis réutilisé à chaque étape. Ce qui rend la progression assez claire : on comprend où on en est, ce qu’on fait, et pourquoi on le fait.

La conférence prend le temps de poser les bases :

ce qu’est un embedding (une représentation vectorielle d’un contenu) ;
à quoi ça sert (mesurer de la similarité sémantique) ;
et surtout dans quels cas ça devient utile.

Ensuite, on rentre dans le concret :

comment choisir un modèle selon son besoin ;
comment vectoriser ses données depuis Symfony ;
où stocker ces vecteurs (PostgreSQL, Redis, etc.) ;
et comment les requêter efficacement.

L'intérêt de cette présentation, c'est que Grégoire nous a montré que tout se fait sans quitter l’écosystème Symfony, grâce à Symfony AI. Cette initiative fournit ainsi toutes les abstractions nécessaires pour manipuler modèles, stores, agents et bien plus encore. N'hésitez pas à consulter le site dédié à Symfony AI pour découvrir tout ça. Vous pouvez retrouver ses slides en ligne.

Retours d’expériences et présentations techniques

Tous ces nouveaux outils basés sur l'IA ne doivent pas éclipser l'importance de la technicité en dehors de l'intelligence artificielle ! Au contraire, nous apprécions également les outils éprouvés et bien établis, et les retours d'expériences de manière générale.

Chiffrez vos données avec Doctrine, en restant recherchable - Jérôme Tamarelle

Lors de cette conférence, Jérôme Tamarelle a rappelé un point essentiel : la sécurité des données ne concerne pas uniquement les informations directement identifiantes (comme un email ou un nom), mais aussi les données indirectes. Croisées entre elles, ces dernières peuvent suffire à identifier une personne.

Il est important de distinguer deux approches souvent confondues :

Le chiffrement : les données sont transformées de manière réversible. On peut les déchiffrer à l’aide d’une clé ;
Le hashage : il s’agit d’une empreinte unique et fixe d’une donnée. Cette opération est irréversible. Plusieurs types de chiffrement existent, dont le chiffrement aléatoire et le chiffrement déterministe.

Avec le chiffrement aléatoire, chaque valeur est chiffrée différemment, même si elle est identique à une autre. Par exemple, une même adresse email enregistrée deux fois en base produira deux valeurs chiffrées différentes.

Avec le chiffrement déterministe, une même donnée produira toujours le même résultat chiffré.

Avec Doctrine, on encapsule le chiffrement directement dans Doctrine via des types personnalisés. Un champ devient "chiffré" simplement par sa définition.

Mais du coup, on ne peut plus faire de recherche sur ces champs sans passer par Doctrine.

Sécuriser ses données, c’est accepter de complexifier son application. Et surtout, le faire dès la conception.

Doctrine inheritance - Rémi JANOT

Rémi commence par présenter la différence entre héritage (mapper une hiérarchie de classe) et polymorphisme (une clef étrangère qui pointe vers une autre classe) car le vocabulaire utilisé par les différents ORM et framework peuvent parfois prêter à confusion.

S'ensuit un rappel bienvenu de l’héritage implémenté directement au niveau de Doctrine ; avec des exemples concrets, il passe en revue toutes les combinaisons possibles : soit avec des MappedSuperClass, soit des DiscriminatorMap.

Fort de son expérience, il nous explique aussi qu’il est possible d’assez facilement passer d’une architecture Single Table Inheritance (STI) vers Class Table Inheritance (CTI). Donc les choix techniques ne sont pas forcément figés, les projets évoluent, et des solutions sont toujours possibles. Il nous rappelle aussi que lorsqu’on utilise les CTI, il est important de bien vérifier les index pour gagner en performance.

JSON + SQL : hérésie ou élégance ? Retour d'expérience - Rémy Bonfils, Olivier FOURNY

On reste ici dans le thème de la modélisation de nos bases de données avec un retour d’expérience sur l’utilisation de JSON dans nos tables SQL, via l’exemple d’une application mobile offline permettant de configurer des maisons imprimées en 3D (oui oui).

Étant donné la nature très flexible des paramètres d’impression (80000 configurations possibles, importées depuis un CSV), la question de comment les stocker se pose dès le départ. Rémy et Olivier nous expliquent vouloir tout d’abord se diriger vers une modélisation de type Entity-Attribute-Valeur, où les paramètres ne sont pas représentés par des colonnes dans nos tables, mais par des lignes (ça doit parler aux personnes devant travailler sur des projets Magento ou Drupal) : beaucoup de flexibilité évidemment, mais aussi l’impossibilité d’avoir un minimum de structure dans nos données (tout est varchar). Et surtout des requêtes beaucoup plus complexes et donc des performances catastrophiques.

L’équipe se penche donc sur une autre solution : le stockage des paramètres dans des colonnes de la base de données en format JSON.

Et la surprise, les performances sont à peine inférieures à une modélisation classique de base de données (avec des tables liées par des clés étrangères), mais en gardant la flexibilité voulue ! Et grâce aux fonctions SQL permettant de manipuler du JSON, les requêtes restent simples et lisibles.

Pour notre part, à JoliCode, nous avons l’habitude de profiter du type JSON dans nos bases de données relationnelles (PostgreSQL ou MySQL), et nous vous le recommandons lorsque le besoin s’en fait ressentir.

ClickHouse pour les développeurs Symfony - Romain Neutron

Dans cette session, Romain Neutron a abordé la problématique de la gestion des données analytiques et des logs à grande échelle, des domaines où les bases relationnelles classiques comme MySQL ou PostgreSQL atteignent souvent leurs limites. Il a présenté ClickHouse, une base de données orientée colonnes ultra-performante, comme la solution idéale pour traiter des volumes massifs de données en temps réel. L'idée centrale n'est pas de remplacer votre base de données habituelle, mais de l'épauler pour des besoins spécifiques d'agrégation et de dashboards instantanés.

Côté technique, la conférence a mis en lumière la simplicité d'intégration de ClickHouse dans l'écosystème Symfony. Il a également partagé des benchmarks impressionnants comparant les temps de réponse sur des agrégations de plusieurs millions de lignes, montrant que ClickHouse peut transformer des requêtes de plusieurs secondes en résultats quasi instantanés.

Enfin, Romain a insisté sur les bonnes pratiques et les pièges à éviter, notamment sur la structure des données et le choix des moteurs de table (comme MergeTree). C'est un talk indispensable pour les développeurs cherchant à scaler leur stack analytique tout en restant dans un environnement PHP familier. De notre côté, on utilise ClickHouse dans plusieurs projets, surtout dans redirection.io pour les parties logs, analytics et crawler. On ne peut donc que vous recommander de vous y intéresser.

Ses slides sont disponibles en ligne pour retrouver toutes les informations importantes.

Symfony UX et la suite Hotwired

Cette année, on continue de parler de Symfony UX, et en particulier, deux retours d’expériences spécifiquement axés sur hotwired.dev.

Du web au mobile avec Symfony & Hotwire Native - Imad ZAIRIG

Imad nous a préparé une conférence sur le nouveau bundle Symfony UX Native qui utilise Hotwire Native. Basé sur un exemple, on peut voir comment l’application est architecturée.

On a eu l'exemple d'un bouton, rendu avec un composant bouton mobile, mais dont l'événement click est écouté par stimulus du côté de l’application Symfony

Cela fonctionne avec des webview pour que ce soit toujours Symfony qui gère le back-end et le front, mais avec des comportements mobiles gérés nativement (ex : la navigation et les transitions). On note qu’il y a quand même encore quelques fois ou il faut lancer le projet mobile avec Xcode par exemple pour iOS.

Pour utiliser les capacités natives des applications mobiles (type appareil photo) il faut passer par des "Bridges Component", ça demande malgré tout du code côté mobile.

Selon la complexité de l’application et la taille de l’équipe, Symfony UX Native est une piste à explorer.

Édition simultanée : facile avec Symfony UX - David Buchmann

Au travers d’un exemple concret David nous a fait voir comment intégrer toute la suite d’outils de hotwired.dev. Il commence avec Turbo (et un peu de Turbo Frames aussi) et nous fait voir à quel point c’est bien intégré à Symfony UX. Puis sa conférence continue avec la mise en place de Mercure (grâce à son intégration dans FrankenPHP), et finalement le tout s’intègre parfaitement via des contrôleurs Stimulus qui écoutent les messages Mercure.

Il résume les avantages de Hotwire comme ceci : la logique reste dans le backend, la sécurité est intégrée. La complexité du frontend s’en trouve réduite.

Conclusion

Si cette édition du SymfonyLive Paris 2026 nous a offert un aperçu saisissant de l'intégration massive de l'Intelligence Artificielle au cœur de l'écosystème Symfony, elle prouve une chose essentielle : l'importance des conférences n'a jamais été aussi grande. Notre métier de développeur est en pleine mutation, et nous avons fort à faire pour rester à jour.

Le fil conducteur de cette année reste cependant une évidence : quelle que soit la puissance des outils, l'humain reste au centre de la boucle. L'IA est un assistant extraordinaire pour la production de code et les tâches répétitives, mais c'est bien la communauté, la validation humaine et le partage de connaissances qui garantissent la qualité et la progression de notre écosystème. Merci aux organisateurs, aux conférenciers, et à la communauté d'avoir fait de cette édition 2026 un moment marquant, et rendez-vous l'année prochaine pour continuer à naviguer ensemble dans le futur du développement web !

Jane now supports OpenAPI 3.1 and JSON Schema 2020-12

2026-03-30T11:50:00+02:00

Version 7.11.0 of Jane PHP, the API client and Normalizer generator, is now available. This major update to the generation engine focuses on aligning with the latest industry standards through the support of JSON Schema 2020-12 and OpenAPI 3.1.

🚀 Major Updates

JSON Schema 2020-12 Support

One of the most important changes introduced in this version is the integration of support for JSON Schema 2020-12 (PR #918). This update allows Jane to process much more modern and complex data schemas, thus offering a richer semantics for describing your structures.

It is important to note that this evolution was designed to be totally transparent: Jane retains backward compatibility with the 2019-09 draft. You can therefore benefit from the latest advances without worrying about your existing schemas.

This dual compatibility allows the tool to offer increased precision in two areas:

PHP model generation: The generated classes more accurately reflect the constraints and relationships defined in your schemas, thus reducing the need for manual adjustments.
Data validation: The support of these specifications guarantees that the built-in validation logic is perfectly aligned with modern API requirements.

OpenAPI 3.1 Support

The other pillar of this version is the support for the OpenAPI 3.1 specification (PR #904). This update is structural because it finally aligns the OpenAPI standard with JSON Schema, thus simplifying the management of data models.

Thanks to this support, Jane natively leverages the new capabilities of the standard:

Convergence with JSON Schema: OpenAPI 3.1 becomes a "superset" of JSON Schema, allowing Jane to interpret complex definitions without loss of information.
Native and nullable typing: Jane uses the new syntax to generate PHP properties with exact typing (e.g ?string), ensuring consistency between your API contract and your code.

📖 New Official Documentation

Alongside these technical developments, the project's documentation has been refreshed to provide a better user experience. It centralizes the installation, configuration, and usage guides for all components.

It is available here: https://jane.jolicode.com/latest/

🛠️ Continuous Improvements and Maintenance

Beyond these major developments, this version is also the occasion for a big spring cleaning for the project. We have consolidated the codebase with a series of stability fixes, particularly regarding the handling of numeric types in query strings, and an overall update of the maintenance tools. These adjustments, although more discreet, guarantee better reliability of the generator and simplify the installation of dependencies for your projects.

📦 Get Started!

All these improvements are available now via the v7.11.0 tag. Whether you want to take advantage of the latest OpenAPI specifications or simply benefit from a more robust generation engine, we strongly encourage you to update your projects:

composer update jane-php/* -W

Feel free to test these new features, explore the new documentation, and give us your feedback on GitHub. Jane continues to grow thanks to your usage and contributions, so enjoy!

📚 Official documentation: jane.jolicode.com
💻 GitHub Repository: janephp/janephp
🚀 Release v7.11.0: Check the changelog

Jane supporte maintenant JSON Schema 2020-12 et OpenAPI 3.1

2026-03-30T11:34:00+02:00

La version v7.11.0 de Jane PHP, le générateur de client d'API et de Normalizer, est désormais disponible. Cette mise à jour majeure du moteur de génération se concentre sur l'alignement avec les derniers standards de l'industrie via le support de JSON Schema 2020-12 et d'OpenAPI 3.1.

🚀 Évolutions majeures

Support de JSON Schema 2020-12

L'un des changements les plus importants introduits dans cette version est l'intégration du support pour JSON Schema 2020-12 (PR #918). Cette mise à jour permet à Jane de traiter des schémas de données beaucoup plus modernes et complexes, offrant ainsi une sémantique plus riche pour la description de vos structures.

Il est important de noter que cette évolution a été pensée pour être totalement transparente : Jane conserve une rétrocompatibilité avec la draft 2019-09. Vous pouvez donc bénéficier des dernières avancées sans craindre pour vos schémas existants.

Cette double compatibilité permet à l'outil d'offrir une précision accrue dans deux domaines :

La génération des modèles PHP : Les classes générées reflètent plus fidèlement les contraintes et relations définies dans vos schémas, réduisant ainsi le besoin d'ajustements manuels.
La validation des données : Le support de ces spécifications garantit que la logique de validation intégrée est en parfaite adéquation avec les exigences modernes des API.

Support d'OpenAPI 3.1

L'autre pilier de cette version est le support de la spécification OpenAPI 3.1 (PR #904). Cette mise à jour est structurante car elle aligne enfin le standard OpenAPI sur JSON Schema, simplifiant ainsi la gestion des modèles de données.

Grâce à ce support, Jane exploite nativement les nouvelles capacités du standard :

Convergence avec JSON Schema : OpenAPI 3.1 devient un "superset" de JSON Schema, permettant à Jane d'interpréter des définitions complexes sans perte d'information.
Typage natif et nullable : Jane utilise la nouvelle syntaxe pour générer des propriétés PHP au typage exact (ex ?string), assurant une cohérence entre votre contrat d'API et votre code.

📖 Nouvelle documentation officielle

Parallèlement à ces évolutions techniques, la documentation du projet a reçu un coup de neuf pour offrir une meilleure expérience aux utilisateurs. Elle centralise les guides d'installation, de configuration et d'utilisation pour l'ensemble des composants.

Elle est disponible ici: jane.jolicode.com

🛠️ Améliorations continues et maintenance

Au-delà de ces évolutions majeures, cette version est aussi l'occasion d'un grand nettoyage de printemps pour le projet. Nous avons consolidé la base de code avec une série de correctifs de stabilité, notamment sur la gestion des types numériques dans les query strings, et une mise à jour globale des outils de maintenance. Ces ajustements, bien que plus discrets, garantissent une meilleure fiabilité du générateur et simplifient l'installation des dépendances pour vos projets.

📦 Lancez-vous !

Toutes ces améliorations sont disponibles dès maintenant via le tag v7.11.0. Que vous souhaitiez profiter des dernières spécifications OpenAPI ou simplement bénéficier d'un moteur de génération plus robuste, nous vous encourageons vivement à mettre à jour vos projets :

composer update jane-php/* -W

N'hésitez pas à tester ces nouveautés, à explorer la nouvelle documentation et à nous faire part de vos retours sur GitHub. Jane continue de grandir grâce à vos usages et vos contributions, alors profitez-en bien !

📚 Documentation officielle : jane.jolicode.com
💻 Dépôt GitHub : janephp/janephp
🚀 Release v7.11.0 : Consulter le changelog

Déploiement On-Premise - Partie 2 - Castor à la rescousse

2026-03-26T10:41:00+01:00

Dans le précédent article, nous avons vu toutes les étapes nécessaires pour préparer les images Docker qui seront utilisées en production. Mais nous allons maintenant aller plus loin pour automatiser et simplifier encore un peu plus cette étape grâce à Castor et les runners GitLab, le but étant de faciliter la procédure de déploiement de nouvelles versions de l'application afin que le client puisse être autonome.

Création et publication des images

Comme souvent quand nos projets nécessitent de lancer des commandes, nous mettons en place des tâches Castor pour simplifier la DX. Nous avons donc créé une task production:build qui applique tout ce que nous avons vu dans l'article précédent :

<?php

use Castor\Attribute\AsOption;
use Castor\Attribute\AsTask;
use Castor\Exception\ProblemException;
use Symfony\Component\Console\Input\InputOption;

use function Castor\capture;
use function Castor\check;
use function Castor\context;
use function Castor\fs;
use function Castor\io;
use function Castor\run;
use function Castor\variable;

const REGISTRY = '<url du registre>:4567/plancq/arsol/';
const DEFAULT_BRANCH = 'main';
const BAKE_FILE = __DIR__ . '/../infrastructure/production/bake.hcl';
const IMAGES_TO_TAG = [
    'postgres:16' => 'postgres',
    'getmeili/meilisearch:v1.16' => 'meilisearch',
];

#[AsTask(description: 'Build production docker images', namespace: 'production:docker')]
function build(
    #[AsArgument(description: 'Version of the images')]
    ?string $tagVersion = null,
    #[AsOption(description: 'Force the build whatever the current branch state')]
    bool $force = false,
    #[AsOption(description: 'Push the images to the registry', mode: InputOption::VALUE_NEGATABLE)]
    ?bool $push = null,
    #[AsOption(description: 'Update docker-compose.yml with current tag', mode: InputOption::VALUE_NEGATABLE)]
    ?bool $updateDockerCompose = null,
): void {
    $currentBranch = capture(['git', 'branch', '--show-current']);
    check('Checking current branch:', 'You must be on the main branch to build the production images. Change the current branch or use --force to bypass this check.', static fn () => DEFAULT_BRANCH === $currentBranch || $force);

    $currentChanges = capture(['git', 'status', '--porcelain']);
    check('Checking git working tree:', 'You have uncommitted changes. Git stash everything before building image or use --force to bypass this check.', static fn () => !$currentChanges || $force);

    if (!$force) {
        run(['git', 'pull', 'origin', DEFAULT_BRANCH]);
    }

    $validateVersion = static function (string $tagVersion): string {
        if (!$tagVersion) {
            throw new \RuntimeException('Version is required');
        }

        if (!preg_match('/^20\d{2}\.\d{2}\.\d{2}+(-\d+)?$/', $tagVersion)) {
            throw new \RuntimeException('Version must be in the format YYYY.MM.DD (eventually with a revision like YYYY.MM.DD-1), got: ' . $tagVersion);
        }

        return $tagVersion;
    };

    if ($tagVersion) {
        $tagVersion = $validateVersion($tagVersion);
    } else {
        $tagVersion = io()->ask('Please provide the version of the production images to build:', date('Y.m.d'), $validateVersion);
    }

    $tags = [$tagVersion, 'lastest'];

    io()->section('Building the local development images...');
    \docker\build();

    if (fs()->exists(context()->workingDirectory . '/.dockerignore')) {
        fs()->rename(context()->workingDirectory . '/.dockerignore', context()->workingDirectory . '/.dockerignore.tmp', true);
    }

    try {
        $command = [
            'docker', 'buildx', 'bake',
            '--file', BAKE_FILE,
            '--load',
        ];

        foreach (getImagesToBuild() as $targetName => $config) {
            foreach ($tags as $tag) {
                $command[] = '--set';
                $command[] = $targetName . '.tags+=' . REGISTRY . $targetName . ':' . $tag;
            }

            $command[] = '--set';
            $command[] = $targetName . '.args.PROJECT_NAME=' . variable('project_name');
        }

        run($command);
    } finally {
        if (file_exists(context()->workingDirectory . '/.dockerignore.tmp')) {
            fs()->rename(context()->workingDirectory . '/.dockerignore.tmp', context()->workingDirectory . '/.dockerignore', true);
        }
    }

    foreach (IMAGES_TO_TAG as $sourceImage => $image) {
        foreach ($tags as $tag) {
            run(['docker', 'image', 'pull', $sourceImage]);
            run(['docker', 'image', 'tag', $sourceImage, REGISTRY . $image . ':' . $tag]);
        }
    }

    io()->success('Production images are now built.');

    if ($updateDockerCompose || (null === $updateDockerCompose && io()->confirm('Do you want to update the docker-compose with the current version?', false))) {
        updateDockerCompose($tagVersion);
    } else {
        io()->info('You can update the production docker-compose.yml file by running the following command:');
        io()->info('castor production:docker:update-docker-compose ' . $tagVersion);
    }

    if ($push || (null === $push && io()->confirm('Do you want to push the images to the registry (you may want to play with the images before pushing)?', false))) {
        push($tagVersion);
    } else {
        io()->info('You can push the images to the registry by running the following command:');
        io()->info('castor production:docker:push');
    }

    io()->success('Great job! Everything is now done.');
}

#[AsTask(description: 'Push production docker images', namespace: 'production:docker')]
function push(?string $tag = null): void
{
    io()->info('Pushing image to the registry...');

    foreach ([...array_keys(getImagesToBuild()), ...IMAGES_TO_TAG] as $image) {
        io()->write(\sprintf('Pushing %s image...', $image));
        if ($tag) {
            run(['docker', 'image', 'push', '--disable-content-trust', REGISTRY . $image . ':' . $tag]);
        } else {
            run(['docker', 'image', 'push', '--disable-content-trust', '--all-tags', REGISTRY . $image]);
        }
    }

    io()->success(\sprintf('Production images have been pushed to the registry %s', REGISTRY));
}

function getImagesToBuild(): array
{
    $bakeConfigOutput = capture([
        'docker', 'buildx', 'bake',
        '--file', BAKE_FILE,
        '--print',
    ]);

    $bakeConfig = json_decode($bakeConfigOutput, true);

    if (null === $bakeConfig) {
        throw new ProblemException('Failed to parse bake.hcl output as JSON.');
    }

    if (!\is_array($bakeConfig) || !isset($bakeConfig['target']) || !\is_array($bakeConfig['target'])) {
        throw new ProblemException('Invalid bake.hcl structure or missing targets.');
    }

    return $bakeConfig['target'];
}

Info

Nous recommandons généralement de placer les tâches et fonctions du projets dans des fichiers .php dans le dossier .castor/ à la racine du dépôt.

Pour résumer, cette task tout-en-un va :

s'assurer que vous êtes sur la branche main, à jour et sans modification locale ;
demander la version des tags à créer en prenant par défaut la date du jour ;
construire la stack Docker de dev si nécessaire (pour avoir les images de base utilisées) ;
exécuter la commande Bake pour construire/taguer les images PHP ;
exécuter les commandes Docker pour construire/taguer les images publiques (Postgres et Meilisearch) ;
demander si vous voulez mettre à jour la version des images dans le docker-compose.yml final (si jamais vous voulez tester l'application en local avant de publier la version) ;
demander si vous voulez publier les images sur le registry.

Chaque paramètre de cette task (la version à taguer, la confirmation de push ou de mise à jour du docker-compose.yml) est optionnel. S'ils ne sont pas spécifiés, la task les demandera de manière intéractive.

Il est maintenant très facile de publier une nouvelle version du projet pour n'importe quel intervenant du projet (tant qu'il a accès au registre Docker évidemment). Mais on peut aller encore un peu plus loin pour faciliter, cette fois, l'exploitation de l'infrastructure de production.

Pilotage de l'infrastructure

Pour démarrer le projet (que ce soit en production, en pré-production ou sur du on-premise), nous avons besoin de 3 choses :

créer le fichier docker-compose.yml avec tous les services définis ;
créer un fichier .env pour configurer l'application Symfony ;
lancer la commande docker compose up -d.

Nous allons tout d'abord créer un nouvel ensemble de task Castor qui vont permettre de tout de piloter l'infrastructure docker :

<?php

namespace production;

use Castor\Attribute\AsTask;
use Castor\Context;
use Castor\Event\BeforeExecuteTaskEvent;
use Castor\Exception\ProblemException;
use Symfony\Component\Process\Exception\ProcessFailedException;

use function Castor\context;
use function Castor\fs;
use function Castor\io;
use function Castor\load_dot_env;
use function Castor\run;
use function Castor\wait_for_docker_container;

#[AsTask(description: 'Start production infrastructure')]
function start(): void
{
    try {
        production_docker_compose(['up', '-d']);
    } catch (ProcessFailedException $e) {
        if (preg_match(
            '/Bind for (.*):(?<port>\d+) failed: port is already allocated/mi',
            $e->getProcess()->getErrorOutput(),
            $matches
        )) {
            throw new ProblemException(\sprintf('It seems that port %s is already used on your machine. Please free this port and try again.', $matches['port']), previous: $e);
        }

        throw $e;
    }

    io()->success('Production infrastructure has been started. It should be available in a few seconds.');

    $url = 'https://' . $_ENV['SERVER_NAME'];

    wait_for_docker_container('arsol-' . $_ENV['ARSOL_INSTANCE'] . '-frontend-1', timeout: 60, intervalMs: 1000);

    io()->success(\sprintf('Production infrastructure is now ready at %s. Enjoy!', $url));
}

#[AsTask(description: 'Stop production infrastructure')]
function stop(): void
{
    io()->title('Stopping production infrastructure');

    production_docker_compose(['stop']);

    io()->success('Production infrastructure has been stopped.');
}

function production_docker_compose(array $arguments): void
{
    load_dot_env(context()->workingDirectory . '/.env');

    run(['docker', 'compose', '-f', 'docker-compose.yml', '-p', 'arsol-' . $_ENV['ARSOL_INSTANCE'], ...$arguments]);
}

Info

Cette fois, nous plaçons les tasks et fonctions destinées à être utilisées en production dans un dossier tools/production/castor.php. Nous expliquerons l'intérêt de séparer ces tasks dans un dossier à part dans le chapitre suivant.

Avec ces deux tasks, on peut maintenant lancer castor production:start et castor production:stop. Mais pour une meilleure DX, on va également créer automatiquement le fichier .env de base ainsi que le fichier docker-compose.yml s'ils n'existent pas encore. Cela se fait facilement avec le système de Listener intégré dans Castor :

use Castor\Attribute\AsListener;
use Castor\Event\BeforeExecuteTaskEvent;

use function Castor\context;
use function Castor\fs;
use function Castor\io;

const DOT_ENV_GENERABLES = [
    'APP_SECRET',
    'POSTGRES_PASSWORD',
    'MEILI_MASTER_KEY',
];

#[AsListener(BeforeExecuteTaskEvent::class)]
function configure(BeforeExecuteTaskEvent $event): void
{
    $context = context();

    $taskName = (string) $event->task->getName();
    if (!str_starts_with($taskName, 'production:')
        || str_starts_with($taskName, 'production:docker:')
        || 'production:repack' === $taskName) {
        return;
    }

    if (!fs()->exists($context->workingDirectory . '/docker-compose.yml')) {
        io()->info('No docker-compose.yml file found in the current directory. Creating one from the default template.');
        fs()->copy(__DIR__ . '/docker-compose.yml', $context->workingDirectory . '/docker-compose.yml');
    }

    if (!fs()->exists($context->workingDirectory . '/.env')) {
        io()->info('No .env file found in the current directory. Creating one from the default template.');
        fs()->copy(__DIR__ . '/.env.production', $context->workingDirectory . '/.env');
    }

    foreach (DOT_ENV_GENERABLES as $envVar) {
        $dotEnvContent = file_get_contents($context->workingDirectory . '/.env');

        if (preg_match('/^' . preg_quote($envVar, '/') . '=.+$/m', $dotEnvContent)) {
            continue;
        }

        $value = bin2hex(random_bytes(16));
        $dotEnvContent = preg_replace('/^' . preg_quote($envVar, '/') . '=.*/m', $envVar . '=' . $value, $dotEnvContent);

        file_put_contents($context->workingDirectory . '/.env', $dotEnvContent);
    }
}

Nous avons également ajouté quelques tasks supplémentaires pour afficher les logs du projet Docker compose, pour afficher l'état des conteneurs ou encore pour détruire complètement toute trace du projet (pratique quand on veut juste tester la stack).

Création d'un exécutable

Castor propose une fonctionnalité de repack qui permet de packager un projet Castor avec ses tasks dans un Phar autonome, ce qui permet de le partager et l'utiliser sans avoir besoin d'avoir le code du projet, ni même d'avoir Castor installé. C'est parfait pour notre environnement de production / On-Premise car hormis PHP, nous avons rien à installer à l'avance pour pouvoir démarrer l'application.

Dans le dossier tools/production/, nous allons donc placer plusieurs fichiers qui seront inclus dans le phar :

un fichier .env.production avec les vars d'env à définir obligatoirement ;
le fichier docker-compose.yml vu dans le précédent article ;
le fichier castor.php du chapitre précédent qui contient les tasks pour piloter la stack.

Nous allons donc maintenant pouvoir repacker le projet Castor situé dans ce dossier tools/production/. La commande à lancer en dev pour repacker notre projet sera évidemment encapsulée dans une task Castor (donc placée dans le dossier habituel .castor/) :

const PRODUCTION_DIRECTORY = __DIR__ . '/../tools/production/';

#[AsTask(description: 'Repack production application in a new phar')]
function repack(): void
{
    io()->title('Repacking production application.');

    // Castorception \o/
    run('castor repack --app-name=arsol --no-logo', context: context()->withWorkingDirectory(PRODUCTION_DIRECTORY));

    fs()->mkdir(PRODUCTION_DIRECTORY . '/build');
    fs()->remove(finder()->in(PRODUCTION_DIRECTORY . '/build')->ignoreDotFiles(false));
    fs()->rename(PRODUCTION_DIRECTORY . '/arsol.linux.phar', PRODUCTION_DIRECTORY . '/build/arsol.phar', true);
}

Il ne reste qu'à installer le fichier tools/production/build/arsol.phar sur le serveur, par exemple dans /usr/bin/local/arsol. On peut dès maintenant lancer la commande arsol production:start (notez le nom de l'exécutable 😎) pour initialiser et démarrer complètement l'infrastructure.

Info

Si nous le voulions, nous pourrions également compiler ce phar dans un binaire statique contenant PHP, ce qui aurait éliminé le besoin d'avoir PHP installé sur le serveur pour pouvoir utiliser le projet repacké. N'hésitez pas à jeter un œil à la documentation Castor qui explique comment compiler son projet.

Automatiser le build depuis Gitlab

Dernière étape pour simplifier la vie du client, nous allons automatiser plusieurs choses directement depuis Gitlab :

Le build des images Docker de prod et le push sur le registre Docker ;
Le repack du projet tools/production dans un phar autonome ;
Ajout de ce phar dans les artefacts associés du job pour le rendre facilement accessible.

Voici un extrait du fichier .gitlab-ci.yml qui permet de faire cela :

stages:
  # ...
  - release

variables:
  CASTOR_CONTEXT: ci
  CASTOR_WORKING_DIR: /tmp/castor/${CI_PIPELINE_ID}

# ...

release:
  stage: release
  script:
    - export TAG=$(date +%Y.%m.%d)
    - export RELEASE_DIRECTORY=/tmp/castor-release/${TAG}
    - rm -rf ${RELEASE_DIRECTORY}
    - git clone . ${RELEASE_DIRECTORY}
    - cd $RELEASE_DIRECTORY
    - echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin
    - castor production:docker:build --push --update-docker-compose "$TAG" --force
    - castor production:repack
    # On déplace le phar à la racine, pour qu'il soit exposé en tant qu'artefact du job
    - cp tools/production/build/arsol.phar "$CI_PROJECT_DIR/"
    # On est sur un self-hosted runner donc on fait le ménage avant de terminer
    - castor docker:destroy --force
    - rm -rf $RELEASE_DIRECTORY

  # Cet artefact sera associé au job, et donc facilement récupérable depuis GitLab
  artifacts:
    paths:
      - arsol.phar
    expire_in: 1 week

  # Ce job est à lancer manuellement et n'est disponible que sur la branche main
  when: manual
  allow_failure: true
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
    - when: never

Avant de finir cet article, je voudrais revenir sur un point vu précédemment. Vous vous souvenez de la variable PROJECT_NAME qui était employée pour préfixer le nom de l'image de la stack de dev ? C'était nécessaire justement quand la stack de prod est construite dans la CI GitLab.

En effet, comme nous utilisons un runner self-hosté, les jobs ne sont pas isolés et tournent sur la même machine en parallèle. Pour ne pas avoir de conflits dans les noms et avoir une stack Docker indépendante entre chaque build de la CI, nous avons donc besoin que les projets Docker compose utilisent un nom unique pour chaque build. Notre template docker-starter est parfaitement compatible avec ce use-case et expose une variable dans le contexte qui permet d'adapter le nom du projet Docker compose à notre guise :

// castor.php à la racine du projet

function create_default_variables(): array
{
    return [
        // Nom du projet docker compose par défaut en local
        'project_name' => 'arsol',
        // ...
    ];
}

// .castor/context.php


#[AsContext(name: 'ci')]
function create_ci_context(): Context
{
    $pipelineId = $_SERVER['CI_PIPELINE_ID'] ?? throw new \RuntimeException('CI_PIPELINE_ID is not set. This context should only be used in a CI environment.');

    $c = create_test_context();

    return $c
        ->withData([
            'project_name' => 'arsol-ci-' . $pipelineId,
            'docker_compose_files' => [
                'docker-compose.yml',
                'docker-compose.ci.yml',
            ],
        ], recursive: false)
    ;
}

Comme nous forçons le context CASTOR_CONTEXT=ci dans GitLab, toutes les stacks construites dans cet environnement sont automatiquement nommées avec un suffixe qui reprend l'id de la pipeline actuelle.

Au passage, on rajoute un docker-compose.ci.yml au projet qui va rajouter quelques configurations spécifiques à la CI (comme des variables d'environnement ou un routeur adaptés)

Conclusion

Pour conclure, grâce au template docker-starter et à Castor, nous avons pu mettre en place un déploiement d'ArSol qui convient à la fois pour la production et le On-Premise mais qui reste simple à l'usage :

Les images Docker pré-construites garantissent des déploiements fiables et déterministes ;
Les images sont optimisées pour ne contenir que ce qui est nécessaire, sans les outils de build ;
Tout passe par Castor, la complexité Docker/CI est masquée ;
Le repack Castor génère un seul exécutable (arsol.phar) pour tout gérer (démarrer, arrêter, mettre à jour) sur site, même sans être un expert système.

L'automatisation complète via Castor et GitLab CI permet au client d'être autonome pour préparer et déployer une mise à jour pour tous les environnements. Une preuve que Docker et Castor sont la bonne formule pour transformer des contraintes de terrain en solutions d'infrastructure efficaces et élégantes.

Déploiement On-Premise - Partie 1 - Le socle Docker

2026-03-25T10:41:00+01:00

Dans cet article, nous vous expliquons notre approche de déploiement hybride pour une application Symfony conteneurisée avec Docker. Ce système permet un déploiement à la fois sur des serveurs connectés à Internet et en mode local (on-premise) pour les zones de travail sans connectivité réseau.

Le contexte

Nous avons récemment entrepris la refonte complète de l'application ArSol pour l'équipe archéologique de l'université de Tours. Le logiciel original, une application desktop, était obsolète. Nous l'avons entièrement modernisé en développant une application web sur mesure... avec une interface utilisateur considérablement rajeunie de plusieurs décennies propulsée avec Symfony 7.4, PHP 8.4 et FrankenPHP.

Une des particularités du projet, c'est que l'application peut être utilisée sur des lieux de fouilles archéologiques ne disposant pas de réseau. Pour plusieurs raisons, l'idée d'une PWA a été écartée assez rapidement. Nous avons plutôt opté pour un mode de déploiement On-Premise : chaque site de fouille pourra ainsi faire tourner l'infrastructure complète (serveur web, bases de données et application Symfony) sur une machine locale. Les contraintes métiers nous ont permis de développer, sans trop de complexité, un système de verrouillage partiel de l'application (pour éviter tout conflit) et une synchronisation des données entre le SaaS (c'est-à-dire la production, le serveur central) et les instances On-Premise.

Je vais vous montrer aujourd'hui comment nous avons mis en place ce déploiement On-Premise (que j'abrégerai OP dans la suite de cet article). D'abord, nous verrons comment se présente la stack Docker, puis comment nous avons automatisé la création des images et le déploiement.

La base Docker

Pour ce projet, nous avons choisi de déployer l'application via des images Docker, aussi bien pour la production que pour les instances OP. Ainsi, ce sont les mêmes images Docker qui seront utilisées dans le mode SaaS et dans le mode OP. L’activation des différentes options et feature flags repose exclusivement sur des variables d’environnement.

La stack de dev

Sur tous nos projets, nous utilisons docker-starter et ArSol n'y a pas fait exception. Ce squelette fournit une stack Docker complète, avec tout ce qu'il faut dedans pour que chaque intervenant du projet puisse le faire tourner en local facilement.

Docker-starter s'est amélioré au fil des années pour offrir une excellente DX à tous nos développeurs, qu'ils soient développeurs PHP ou intégrateurs, qu'ils soient à l'aise avec le fonctionnement de Docker ou pas du tout.

Pour cela, toute la stack est pilotée par des tasks Castor 🦫 :

castor start : construit les images si nécessaire, les démarre, installe les dépendances Composer/Yarn/npm, build les assets front, etc. Bref, cette seule commande suffit pour rendre le projet complètement fonctionnel en local, que ce soit au premier lancement ou aux lancements suivants ;
castor migrate : joue les migrations Doctrine ;
castor stop : stoppe toute la stack ;
et plein d'autres tasks pour les power users ou pour ceux qui veulent lancer une tâche particulière, par exemple ré-installer les dépendances, exécuter les tests, etc.

Cette infrastructure dockerisée est parfaite pour le développement :

Les tâches castor fournies couvrent une bonne partie des besoins du quotidien ;
Le code du projet n'est pas copié/collé dans les conteneurs, mais "monté" dans des volumes pour chaque conteneur. Ainsi, les modifications dans le code sont directement disponibles dans les conteneurs, pas de build/restart à faire à chaque modification.

Comment passer en production ?

Si Docker-starter est parfait pour l'environnement de développement, il ne doit toutefois pas être utilisé tel quel en production.

En production, la priorité est la fiabilité, la sécurité, la rapidité de déploiement et la reproductibilité de l'environnement. Contrairement à l'environnement de développement où le montage de volume permet l'itération rapide du code, en production, on cherche à minimiser les étapes au moment du déploiement.

Avoir des images pré-construites garantit que l'image qui a été testée et validée contient exactement le code, les dépendances (Composer, Yarn/npm) et les assets frontend nécessaires et compilées. Cela élimine le besoin d'exécuter des commandes de build ou d'installation au moment du lancement des conteneurs (sur les serveurs de production ou sur les instances On-Premise). Cela réduit ainsi le risque d'erreurs dues à des dépendances externes ou des configurations de l'environnement hôte. C'est la garantie d'un déploiement "figé" et déterministe. D'ailleurs, comme les assets sont buildées en amont, nous n'avons pas besoin de NodeJS dans le conteneur final, ce qui permet également d'avoir des images plus légères in-fine.

L'objectif est d'avoir des images Docker prêtes pour la production, mais aussi utilisables pour la pré-production et le déploiement on-premise.

L'important, c'est la santé

Dans l'idéal, nous souhaitons également que chaque service définisse son propre healthcheck. Un healthcheck est une commande que Docker pourra exécuter pour déterminer si le conteneur est toujours en bon état. Si ce n'est pas le cas, Docker tentera de redémarrer le conteneur. Voilà un exemple de healthcheck permettant de vérifier si un serveur MySQL est toujours opérationnel dans un conteneur :

mysqladmin ping -h localhost

Il se configure de cette manière dans un docker-compose.yml classique:

services:
  mysql:
    image: "mysql"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"]
      timeout: 20s
      retries: 10

En général, je préfère que les images "applicatives" déclarent elles-mêmes leur healthcheck plutôt que de laisser l'utilisateur le définir lui-même dans son docker-compose.yml. Cela offre, selon moi, deux avantages :

l'image garde la responsabilité de tout configurer comme il faut : l'utilisateur n'a pas besoin de savoir ce qui tourne dans l'image, comment vérifier que tout fonctionne (faut-il utiliser wget, curl ou un autre outil pour avoir l'état du service), etc ;
le docker-compose.yml reste le plus simple possible pour l'utilisateur.

Cela se fait grâce à l'instruction HEALTHCHECK directement dans le dockerfile de l'image en question. Voici un exemple d'un healthcheck qu'on pourrait définir dans le Dockerfile pour un conteneur faisant tourner un serveur web :

HEALTHCHECK --interval=5m --timeout=3s CMD curl -f http://localhost/ || exit 1

Info

Certaines images publiques ne fournissent volontairement pas de healthcheck. Il faudra donc le configurer nous-même, soit dans une image à vous, soit dans le docker-compose.yml.

Publication et utilisation des images finales

Une fois les images construites, il faut les publier sur un registre Docker pour les mettre à disposition des différents environnements cibles (que ce soit votre serveur de production, dans un Kubernetes, etc). Docker fournit un registre par défaut qui s'appelle Docker Hub. C'est sur ce service que Docker va chercher les images qu'il ne connaît pas encore localement (par exemple depuis un FROM xxx dans un Dockerfile ou depuis un docker-compose.yml). La plupart des systèmes de gestion de code comme GitHub ou GitLab fournissent également un registre de conteneur pour stocker de manière privée vos images Docker. Ces images, dans le cadre d'ArSol, sont stockées dans le registre GitLab du client.

Une fois que tout est prêt, nous obtenons le docker-compose.yml suivant (simplifié dans le cadre de cet article) :

volumes:
  postgres-data: {}
  caddy_data: {}
  caddy_config: {}

services:
  frontend:
    image: "<url du registre>/arsol/frontend:2025.10.23"
    restart: unless-stopped
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
      meilisearch:
        condition: service_healthy
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - caddy_data:/data
      - caddy_config:/config

  postgres:
    image: "<url du registre>/arsol/postgres:2025.10.23"
    restart: unless-stopped
    env_file: .env
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 5s
      retries: 5

  worker-messenger:
    image: "<url du registre>/arsol/worker-messenger:2025.10.23"
    restart: unless-stopped
    env_file: .env
    depends_on:
      frontend:
          condition: service_healthy
      postgres:
        condition: service_healthy

Info

Les volumes pour caddy sont importants pour permettre la génération automatique des certificats SSL.

Vous noterez que nous avons spécifié, pour chaque image, un tag basé sur une date (en l'occurrence 2025.10.23). En effet, quand Docker a déjà récupéré un tag pour une image donnée, il ne cherchera pas à la mettre à jour à moins de nettoyer les images locales (ou à moins de forcer le pull avec l'option docker run --pull=always). Si on utilisait un tag fixe (comme latest par exemple), les images ne seraient jamais mises à jour sur la machine, quand bien même le tag en question aurait changé sur le registre pour cibler une nouvelle version.

Une fois le docker-compose.yml configuré, et le fichier .env créé, nous pouvons lancer docker compose -f docker-compose.yml up -d, et voilà 🎉 : l'infrastructure de production est opérationnelle en HTTP et HTTPS.

La seule différence pour mettre en place une instance OP sera le contenu du .env pour activer/désactiver certaines fonctionnalités spécifiques à ce mode (comme les écrans pour déclencher la synchronisation avec le SaaS, ou la désactivation des données des autres sites archéologiques). Et pour déployer une nouvelle version, il nous faut construire et taguer une nouvelle version de nos images, mettre à jour le docker-compose.yml pour utiliser la bonne version des images et relancer la commande docker compose.

Maintenant que l'objectif est clair, voyons en détails comment y parvenir.

Construction des images

Ici, nous voulons construire toutes les images Docker nécessaires pour faire tourner le projet. À cette étape, nous devons considérer deux cas, suivant si nous utilisons des images publiques telles quelles ou s'il s'agit de nos propres images spécifiques à ArSol.

Images publiques

Dans un premier temps, parlons des images publiques que nous utilisons telles quelles (comme pour Postgres ou Meilisearch). Nous pourrions réutiliser ces images présentes sur le Docker Hub. Mais à la place, nous allons plutôt taguer ces images avec notre système de tag et les pousser sur notre propre registre Docker. Cela apporte plusieurs avantages :

toutes les images du projet utilisent le même tag (plus simple pour s'y retrouver) ;
le projet n'est dépendant que d'un seul registre Docker, celui du client.

Pour celles-ci, nous allons simplement créer un nouveau tag sur les images en question et les publier sur notre registre Docker privé :

# Tag de l'image
docker image tag <le nom de l'image>:<la version de l'image> <url du registre>/arsol/<le nom de l'image chez nous>:<la version de l'applicatif>

# Publication de l'image sur le registre
docker image push --disable-content-trust <url du registre>/arsol/<le nom de l'image chez nous>:<la version de l'applicatif>

Info

Ici, nous n'allons pas utiliser le système de signature des images, donc nous désactivons la validation des images côté registre en utilisant l'option --disable-content-trust.

Par exemple, pour meilisearch, cela nous donnerait quelque comme cela pour publier le tag "daté" ainsi que le tag latest :

docker image tag getmeili/meilisearch:v1.16 <url du registre>:4567/plancq/arsol/meilisearch:2025.10.23
docker image tag getmeili/meilisearch:v1.16 <url du registre>:4567/plancq/arsol/meilisearch:latest
docker image push --disable-content-trust <url du registre>:4567/plancq/arsol/meilisearch:2025.10.23
docker image push --disable-content-trust <url du registre>:4567/plancq/arsol/meilisearch:latest

Nous pouvons maintenant utiliser cette image directement dans notre docker-compose.yml.

Images applicatives

En revanche, pour les images avec PHP (frontend et worker) contenant le code de l'application, les dépendances & cie, c'est un peu plus compliqué comme nous allons le voir.

La stack de dev comme base

Nous allons nous servir des images de la stack de dev comme base pour nos images de production. En effet, dans Docker-starter, nos images customs suivent déjà plusieurs bonnes pratiques, notamment pour optimiser leur poids :

les instructions RUN sont regroupées le plus possible pour réduire le nombre de couches de l'image (layer squashing) ;
un nettoyage immédiat du cache et des fichiers temporaires est fait pour chaque commande afin de diminuer la taille de chaque layer, et donc le poids final de l'image ;
le build "multi-stage" est utilisé pour ne pas inclure les outils de dev dans l'image finale (composer, nodejs, yarn, etc) mais uniquement dans une image builder utilisée quand il y a besoin de ces outils.

Pour la production, nous allons appliquer la même logique. Nous créerons donc un Dockerfile unique avec plusieurs stages qui nous donnera les différentes images finales à construire, mais en partant des différentes images de dev pour éviter d'avoir à dupliquer et maintenir une autre installation de PHP dans la bonne version, avec les bonnes extensions, configurer FrankenPHP et caddy, etc.

Voyons à quoi ressemble ce Dockerfile dans les grandes lignes.

Le builder et la préparation de l'application

En premier, nous définissons un stage "builder", qui se base sur notre builder de dev et va faire toutes les étapes nécessaires pour installer le projet (installations composer et yarn, construction des assets, etc) :

ARG PROJECT_NAME
FROM ${PROJECT_NAME}-builder AS production-builder

ENV APP_ENV=prod
ENV COMPOSER_MIRROR_PATH_REPOS=1
ENV NODE_ENV=production

# C'est dans ce dossier que nous allons travailler
WORKDIR /var/www

# On récupère les fichiers composer.json et composer.lock et on lance Composer
COPY composer.* /var/www/

RUN composer install \
    --no-dev \
    --prefer-dist \
    --no-scripts \
    --no-interaction \
    && composer clear-cache

# Pareil pour Yarn
COPY package.json yarn.lock .yarnrc.yml /var/www/

RUN yarn install --immutable

# On récupère le reste des fichiers
COPY . /var/www/

# Et enfin, on lance toutes les tasks nécessaires pour avoir l'application opérationnelle 
RUN composer dump-autoload --optimize \
    && yarn run build \
    && bin/console cache:warmup \
    && bin/console assets:install public --relative \
    && rm -rf node_modules

Plusieurs choses sont à noter ici. Déjà, vous remarquez que nous mentionnons un argument de build PROJECT_NAME pour préfixer le nom de l'image de base. Nous verrons dans le prochain article pourquoi c'est nécessaire. Dites vous dans un premier temps que la variable a comme valeur arsol, ce qui correspond au nom du projet Docker compose de la stack de dev en local.

Info

J'ai voulu dissocier le Dockerfile de la stack de dev du Dockerfile de la stack de prod, d'où la nécessité de pouvoir référencer l'image de la stack de dev. Si nous avions mergé les deux Dockerfile, nous n'aurions pas eu besoin de cette variable PROJECT_NAME.

Ensuite, vous vous demandez peut-être la raison pour laquelle nous effectuons l'installation de Composer et Yarn avant de COPY le code et l'ensemble des fichiers de l'application. Cette approche permet de tirer parti du cache de couches : Docker commence la construction en vérifiant le cache pour la première instruction et, en cas de correspondance, il réutilise la couche et passe à l'instruction suivante. Mais si une instruction invalide le cache (par exemple, un COPY avec un fichier modifié), toutes les instructions suivantes seront exécutées sans utiliser le cache, ce qui ralentit la construction. Étant donné que les dépendances sont moins sujettes à changement que le code, il est plus probable que les étapes d'installation de Composer et Yarn soient réutilisées depuis le cache, car elles précèdent l'opération de COPY du code.

On peut maintenant préparer le stage docker qui contiendra uniquement php et les outils nécessaires pour le runtime (FrankenPHP, Caddy, etc), en se basant sur l'image du conteneur frontend :

ARG PROJECT_NAME
FROM ${PROJECT_NAME}-frontend AS production-php-base

WORKDIR /var/www

# Symfony tournera dans son env prod
ENV APP_ENV=prod

# On récupère le code de l'application, ses dépendances et assets depuis le stage builder vu précédemment
COPY --from=production-builder /var/www /var/www

Il faut bien faire attention à ce qui est inclus dans les conteneurs. C'est pour cette raison que nous allons créer un Dockerfile.gitignore au même niveau que le Dockerfile du projet. On retire tout ce qui n'est pas nécessaire, comme les dépendances ou les assets qui auraient été installées/construites dans votre stack de dev :

.castor/
.castor.stub.php
.env.local
.env.ci
*.cache
.git/
.idea/
.home/
.yarn/
doc/
infrastructure/
!infrastructure/docker/services/php-production/
tests/
tools/
node_modules/
var/
vendor/
public/assets/
public/build/
public/bundles/
public/media/
!public/media/.gitkeep

Info

Après réflexion, on aurait peut-être mieux fait de tout bloquer par défaut et ne lister que ce qu'il fallait garder (src, config, public, etc). 😝

Frontend et worker

Maintenant que nous avons un stage avec l'application opérationnelle, nous allons pouvoir construire les images finales pour notre projet. Voilà l'image qui se base sur le stage construit ci-dessus :

FROM production-php-base AS production-frontend

# Mise en place d'un entrypoint qui s'occupera d'initialiser l'application
COPY infrastructure/docker/services/php-production/entrypoint-frontend.sh /entrypoint.sh

# Configuration de Caddy
COPY infrastructure/docker/services/php-production/etc/. /etc/

RUN ["chmod", "+x", "/entrypoint.sh"]
ENTRYPOINT ["/entrypoint.sh"]

# Indique les ports utilisés par ce conteneur 
EXPOSE 80
EXPOSE 443

# Commande qui sera exécutée dans le conteneur
CMD [ "frankenphp", "run", "--config", "/etc/caddy/Caddyfile", "--adapter", "caddyfile"]

Nous avons défini un entrypoint pour ce conteneur. Lors du démarrage de ce dernier, il permet d'initialiser toute la partie data (schéma SQL, migrations Doctrine à jouer, configuration du transport pour Messenger, indexation des données dans Meilisearch). Cela est rendu possible car nous n'aurons toujours qu'une seule instance de ce conteneur en production (aucun pic de trafic à gérer). Si ce n'est pas votre cas, il faudra peut-être adapter cette technique.

Voilà à quoi ressemble cet entrypoint :

#!/bin/bash
set -e

echo "Updating all databases..."

php bin/console doctrine:database:create --if-not-exists --env=prod --no-interaction
php bin/console doctrine:migrations:sync-metadata-storage --env=prod --no-interaction
php bin/console doctrine:migrations:migrate --env=prod --no-interaction
php bin/console messenger:setup-transports --env=prod --no-interaction
php bin/console app:meilisearch:index --env=prod

echo "Ready to start the frontend service."

exec "$@"

Enfin, il ne nous manque plus que le stage qui permettra de construire l'image faisant tourner le conteneur pour le worker Messenger :

FROM production-php-base AS production-worker-messenger

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        procps \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*

CMD ["php", "-d", "memory_limit=-1", "bin/console", "messenger:consume", "-vv", "async"]

Ici, on note l'installation de procps qui fournit le binaire pgrep, utile pour vérifier si le processus qui fait tourner le worker est toujours actif. Il sera employé dans le healthcheck de ce service :

services:
  worker-messenger:
    # ...
    healthcheck:
      test: ["CMD-SHELL", "pgrep -f \"messenger:consume\" || exit 1"]
      interval: 5s
      timeout: 5s
      retries: 5

Grâce au multi-stage de Docker, nous avons ainsi pu construire toutes nos images utilisant PHP dans un même Dockerfile.

A table !

Maintenant que nos images peuvent être construites, il va nous falloir les taguer puis les envoyer sur le registre. On pourrait lancer les mêmes commandes docker image tag|push vues précédemment. Mais à la place, on va simplifier et automatiser le processus grâce à Bake.

Cet outil permet de définir l'ensemble des cibles de build dans un fichier de configuration (bake.hcl par exemple) et de les construire/pousser en une seule commande. Voici un extrait de ce à quoi ressemble notre fichier bake :

group "default" {
  targets = [
    "frontend",
    "worker-messenger",
  ]
}

target "frontend" {
  context    = "."
  dockerfile = "./infrastructure/docker/services/php-production/Dockerfile"
  target     = "production-frontend"
}

target "worker-messenger" {
  context    = "."
  dockerfile = "./infrastructure/docker/services/php-production/Dockerfile"
  target     = "production-worker-messenger"
}

Avec ce fichier, il ne nous reste qu'à lancer la commande suivant pour construire les images, les tagger et les envoyer au registre docker :

docker buildx bake --file bake.hcl --push

Info

Malheureusement, Bake n'a pas l'air de permettre de juste taguer des images existantes, donc nous ne pourrons pas l'utiliser pour remplacer les docker image tag|push des images publiques.

Nos images sont maintenant disponibles sur le registre du client :

Conclusion

Nous avons vu dans cet article une bonne partie des étapes qui nous permettent de construire les images Docker dont nous aurons besoin pour faire tourner l'application dans tous nos environnements.

Je n'en ai pas parlé jusque-là mais il reste quelques points de sécurité à garder en tête avant de mettre en production cette infrastructure (comme les capabilities Docker ou encore les logs générés par Docker Compose qui peuvent vite remplir le disque par défaut en cas de fort trafic).

Le client devant être autonome pour déployer les prochaines évolutions de l'application, nous ne nous sommes pas arrêtés là. Nous avons donc mis en place tout un ensemble de task Castor permettant d'automatiser la création et la publication des images, ainsi que de simplifier le pilotage de la stack dans les différents environnements. Mais nous verrons tout cela dans le prochain article.

AutoMapper 10.0: High-performance mapping ready for the future

2026-02-10T14:42:00+01:00

This is a major milestone for the library: AutoMapper has reached version 10.0.

While our promise remains unchanged — transforming your data from one format to another as fast as possible — this version marks a technological breakthrough. We took advantage of this major release to modernize the core engine and align with the latest Symfony standards: and much more!

Under the hood: The arrival of symfony/type-info

This is the most impactful invisible change. I have been working on Jane and AutoMapper for a long time, and I started from a simple observation: a tool capable of retrieving metadata in an advanced way was missing. At the time, Symfony's PropertyInfo component had limited support for unions and handled neither intersections nor generics.

I initially implemented the PHPStan extractor in PropertyInfo to try to fill these gaps, but I quickly realized that the system remained limited by the component's very design. It was following discussions with Mathias Arlaud that we decided to team up to create and release the TypeInfo component.

That is why TypeInfo (introduced in Symfony 7.1) is now the new standard for obtaining even more detailed type definitions. With v10, AutoMapper switches to this component. The more precise the type definition, the more reliable and optimal the mapping process can be. This is an essential step to guarantee a much more faithful extraction of your data.

The new feature: Forced Typing

Sometimes, automatic inference isn't enough, or you want to transform data into a specific format that differs from the source property's PHP type. v10 allows you to force the target type directly via the #[MapTo] attribute.

Example:

Here, we explicitly ask the mapper to transform the $number property into an array of integers in the target, even if the source is a string.

class Entity {
    #[MapTo(target: 'array', targetPropertyType: 'int')]
    public string $number;
}

Interoperability: Symfony ObjectMapper Support

Much like AutoMapper's native interface, the ObjectMapperInterface allows transforming a source object into a target object via a single method. The strength of this signature lies in the $target parameter, which accepts either a class name (to create a new instance) or an existing object (to hydrate or update it).

interface ObjectMapperInterface
{
    public function map(object $source, object|string|null $target = null): object;
}

This is where AutoMapper makes a difference: whereas Symfony's native implementation relies mainly on the Reflection API (which can be costly), AutoMapper generates optimized PHP code. By activating this support, you replace the default mechanism with a solution tailored for performance, which is much faster at runtime. To activate this feature and replace Symfony's default ObjectMapper with the AutoMapper one, a single line in the bundle configuration is enough:

automapper:
    object_mapper: true

To make this possible and efficient, we had to implement a highly anticipated feature: Nesting. This allows reading or writing deeply nested values in your objects, drastically simplifying the transition from "flat" DTOs to rich entities.

Example: Here we map a flat UserDto to a User containing an Address object. Thanks to the address.street notation, AutoMapper knows it must hydrate the sub-object.

class UserDto {
    #[MapTo(property: 'address.street')]
    public string $streetAddress;

    #[MapTo(property: 'address.city')]
    public string $cityAddress;

    public string $name;
}

class User {
    public Address $address;
    public string $name;

    public function __construct()
    {
        $this->address = new Address();
    }
}

class Address {
    public string $street;
    public string $city;
}

// In use, the Address sub-object is automatically populated
$mapper->map(new UserDto(
    streetAddress: '123 Main St',
    cityAddress: 'Springfield',
    name: 'John Doe'
), User::class);

Polymorphism: Rethinking discriminator management

Until now, handling polymorphism relied on a dependency on the Symfony Serializer. It was limited by the necessity to specify a discrimination property. v10 improves this by allowing you to define the discrimination logic directly at the class level via the #[Mapper] attribute, enabling object mapping without having to define a property to discriminate entities. This allows for seamless mapping from DTO hierarchies to Entity hierarchies.

Example: Here you define how to map the children of the abstract Pet class based on the incoming DTO type.

#[Mapper(discriminator: new Discriminator(
    mapping: [
        DogDto::class => Dog::class,
        CatDto::class => Cat::class,
    ]
))]
abstract class Pet {
    /** @var string */
    public $name;

    /** @var PetOwner */
    public $owner;
}

A new Profiler to see clearly

Mapping is often a "black box". When data comes out malformed, understanding why can be complex.

We have revamped the integration into the Symfony Profiler. Gone are the days when you didn't know if AutoMapper had actually worked. Now, the dedicated panel allows you to:

List all mappings performed during the request.
See the Source class and the Target class.
Inspect the context passed to the mapper.

It is an indispensable tool for debugging your complex transformations without having to place breakpoints everywhere.

Final Word

Version 10 is the culmination of a lot of work to modernize and sustain the library. A huge thank you to all the contributors who participated in this release, with a special mention to Joel Wurtz for his colossal investment in this major version.

To go further, everything happens here:

📖 Documentation: https://automapper.jolicode.com/
🐙 GitHub repository: https://github.com/jolicode/automapper

Make sure your environment is running PHP 8.4 or higher and run:

composer require jolicode/automapper ^10.0

AutoMapper 10.0 : Le mapping haute performance prêt pour le futur

2026-02-10T14:41:00+01:00

C’est une étape majeure pour la librairie : AutoMapper passe en version 10.0.

Si notre promesse reste inchangée — transformer vos données d'un format à un autre le plus vite possible — cette version marque une rupture technologique. Nous avons profité de cette version majeure pour moderniser le cœur du réacteur et s'aligner sur les derniers standards de Symfony et bien plus encore !

Sous le capot : L'arrivée de symfony/type-info

C'est le changement invisible le plus impactant. Je travaille sur Jane et AutoMapper depuis longtemps, et je suis parti d'un constat simple : il manquait un outil capable de récupérer les métadonnées de façon avancée. À l'époque, le composant PropertyInfo de Symfony avait un support limité des unions et ne gérait ni les intersections, ni les génériques.

J'avais initialement mis en place l'extracteur PHPStan dans PropertyInfo pour tenter de combler ces manques, mais je me suis vite rendu compte que le système restait limité par la conception même du composant. C'est suite à des discussions avec Mathias Arlaud que nous avons décidé de nous mettre ensemble pour créer et sortir le composant TypeInfo.

C'est pourquoi TypeInfo (introduit dans Symfony 7.1) est aujourd'hui le nouveau standard pour obtenir des définitions de types encore plus détaillées. Avec la v10, AutoMapper bascule sur ce composant. Plus la définition des types est précise, plus le processus de mapping peut être effectué de manière fiable et optimale. C'est une étape essentielle pour garantir une extraction beaucoup plus fidèle de vos données.

La nouveauté : Le typage forcé

Parfois, l'inférence automatique ne suffit pas ou vous souhaitez transformer une donnée vers un format précis qui diffère du type PHP de la propriété source. La v10 permet de forcer le type cible directement via l'attribut #[MapTo].

Exemple : Ici, on demande explicitement au mapper de transformer la propriété $number en un entier dans la cible, même si la source est une string.

class Entity {
    #[MapTo(targetPropertyType: 'int')]
    public string $number;
}

Interopérabilité : Support de Symfony ObjectMapper

Un peu comme l'interface native d'AutoMapper, l'ObjectMapperInterface permet de transformer un objet source en un objet cible via une méthode unique. La force de cette signature réside dans le paramètre $target, qui accepte soit le nom d'une classe (pour créer une nouvelle instance), soit un objet existant (pour l'hydrater ou le mettre à jour).

interface ObjectMapperInterface
{
    public function map(object $source, object|string|null $target = null): object;
}

Et c'est ici que AutoMapper fait la différence : là où l'implémentation native de Symfony s'appuie principalement sur l’API Reflection qui peut être coûteuse, AutoMapper génère du code PHP optimisé. En activant ce support, vous remplacez le mécanisme par défaut par une solution taillée pour la performance, beaucoup plus rapide à l'exécution.

Pour activer cette fonctionnalité et remplacer l'ObjectMapper par défaut de Symfony par celui de l’AutoMapper, il suffit d'une ligne dans la configuration du bundle :

automapper:
    object_mapper: true

Pour rendre cela possible et efficace, nous avons dû implémenter une fonctionnalité très attendue : le Nesting. Cela permet d'aller lire ou écrire des valeurs profondément imbriquées dans vos objets, simplifiant drastiquement le passage de DTOs "à plat" vers des entités riches.

Exemple : On mappe ici un UserDto plat vers un User qui contient un objet Address. Grâce à la notation address.street, AutoMapper sait qu'il doit hydrater le sous-objet.

class UserDto {
    #[MapTo(property: 'address.street')]
    public string $streetAddress;

    #[MapTo(property: 'address.city')]
    public string $cityAddress;

    public string $name;
}

class User {
    public Address $address;
    public string $name;

    public function __construct()
    {
        $this->address = new Address();
    }
}

class Address {
    public string $street;
    public string $city;
}

// À l'utilisation, le sous-objet Address est automatiquement peuplé
$mapper->map(new UserDto(
    streetAddress: '123 Main St',
    cityAddress: 'Springfield',
    name: 'John Doe'
), User::class);

Polymorphisme : Une gestion des discriminants repensée

Jusqu'ici, gérer le polymorphisme reposait sur une dépendance au Serializer de Symfony. Il était limité par la nécessité de spécifier une propriété de discrimination. La v10 améliore cela en permettant de définir la logique de discrimination directement au niveau de la classe via l'attribut #[Mapper] et permet de définir un mapping d'objets sans avoir à définir une propriété pour discriminer les entités.

Exemple : Vous définissez ici comment mapper les enfants de la classe abstraite Pet en fonction du type de DTO entrant.

#[Mapper(discriminator: new Discriminator(
    mapping: [
        DogDto::class => Dog::class,
        CatDto::class => Cat::class,
    ]
))]
abstract class Pet {
    /** @var string */
    public $name;

    /** @var PetOwner */
    public $owner;
}

Un nouveau Profiler pour y voir clair

Le mapping est souvent une "boîte noire". Quand une donnée ressort mal formée, comprendre pourquoi peut être complexe. Nous avons revu l'intégration dans le Profiler Symfony. Fini le temps où vous ne saviez pas si AutoMapper avait réellement travaillé. Désormais, le panneau dédié vous permet de :

Lister tous les mappings effectués durant la requête ;
Voir la classe Source et la classe Cible ;
Inspecter le contexte passé au mapper.

C'est un outil indispensable pour debugger vos transformations complexes sans devoir placer des points d'arrêt partout.

Le mot de la fin

Cette version 10 est l'aboutissement de beaucoup de travail pour moderniser et pérenniser la librairie. Un immense merci à tous les contributeurs qui ont participé à cette release, avec une mention spéciale à Joel Wurtz pour son investissement colossal sur cette version majeure.

Pour aller plus loin, tout se passe ici :

📖 La documentation : https://automapper.jolicode.com/
🐙 Le dépôt GitHub : https://github.com/jolicode/automapper

Assurez-vous que votre environnement tourne sous PHP 8.4 ou supérieur et lancez :

composer require jolicode/automapper ^10.0

Que devient Elasticsearch en 2026 ?

2026-01-28T14:30:00+01:00

J'étais hier à Elastic{On} Paris - la conférence de l'éditeur d'Elasticsearch 🔎. Dans cet article, je vais vous partager mon point de vue de développeur et consultant Elasticsearch sur les nouveautés, la direction, la transformation des usages du moteur et son écosystème.

L'IA est la priorité 🤖

Elastic fait tout pour asseoir sa place dans le monde des LLM, avec beaucoup de nouveautés pour améliorer la recherche par vecteurs, leur stockage et les performances générales ; et il faut le dire : la majorité des talks de la journée en parlaient ! Il est loin le temps où nous parlions des nouveautés de Lucene 🤣

L'IA générative s'invite partout, et les premiers retours d'expérience concrets arrivent également, au fur et à mesure que les solutions s'améliorent. Nous allons de plus en plus souvent intégrer des LLM, développer des serveurs MCP, mettre de l'IA dans les workflows de nos clients, et Elastic compte bien avoir sa part du gâteau dans cette révolution technique.

La recherche hybride s'améliore 👬

La recherche hybride est le fait de combiner des résultats de recherche vectorielle (KNN) avec des résultats lexicaux (BM25), afin de proposer des résultats exploitant le meilleur des deux mondes.

Un des challenges est la fusion des résultats ; et dans Elasticsearch, elle se fait avec différents "retriever" :

RRF (Reciprocal Rank Fusion) : bon choix si on n'a pas trop de règles métier ;
Weighted RRF : permet de donner de la pondération ;
Linear : utilise une somme pondérée des scores originaux...

La RRF ne nécessite aucun réglage préalable, et les différents indicateurs de pertinence n'ont pas besoin d'être liés entre eux pour obtenir des résultats de haute qualité. La syntaxe vient de changer et elle ressemble maintenant à cela :

GET /retrievers_example/_search
{
    "retriever": {
        "linear": {
            "retrievers": [
                {
                    "retriever": {
                        "standard": {
                            "query": {
                                "match": {
                                    "content": "raccord coudé en laiton"
                                }
                            }
                        }
                    },
                    "weight": 2,
                    "normalizer": "minmax"
                },
                {
                    "retriever": {
                        "knn": {
                            "field": "vector",
                            "query_vector": [ // Des vecteurs de recherche
                                0.23,
                                0.67,
                                0.89
                            ],
                            "k": 3,
                            "num_candidates": 5
                        }
                    },
                    "weight": 1.5,
                    "normalizer": "minmax"
                }
            ],
            "rank_window_size": 10
        }
    },
    "_source": false
}

Elastic 9.2 apporte aussi une grosse amélioration de la performance dont ils ont beaucoup parlé : DiskBBQ.

Aujourd'hui, les vecteurs sont indexés via HNSW (Hierarchical Navigable Small Worlds), qui est un genre de graphe à plusieurs niveaux. Ce graphe est parcouru, une similarité entre chaque nœud est calculée, et chaque niveau est visité l'un après l'autre. À chaque niveau, on a de plus en plus de nœuds à parcourir, mais à la fin nous obtenons les plus "justes".

Sur le disque, ces vecteurs ne sont pas au même endroit et donc les lire coûte cher 💸. Pour indexer dans ce graphe, il faut aussi faire des recherches, et pour merger des segments, il faut monter le graphe complet en mémoire... et ça coûte cher aussi 💸

Dans DiskBBQ, les vecteurs sont groupés par similarité. Ces vecteurs proches vont donc être localisés près les uns des autres, et la lecture sera donc séquentielle lors des recherches. Pour l'indexation, c'est aussi beaucoup mieux, car tout se passe dans le CPU.

DiskBBQ va être automatiquement appliqué à vos index si vous avez plus de 384 dimensions 👍 et la promesse est qu'il offre 95 % de réduction d'espace disque/mémoire 🚀

Un autre point d'attention est l'utilisation d'ACORN, un nouvel algorithme de recherche qui permet de filtrer efficacement les nœuds traversés dans un graphe HNSW, avec des gains annoncés jusqu'à cinq fois plus rapides sur des recherches avec beaucoup de filtres.

💡 Tout va très vite en ce moment, et chaque version du moteur apporte son lot d'optimisations ; alors, si vous utilisez des vecteurs, mettez à jour Elasticsearch !

Le nouvel Agent Builder 🔧

Ils passent la seconde avec la release de l'Agent Builder, qui va mettre à disposition des API et des interfaces graphiques pour la création d'agents intelligents complets.

Cela va permettre l'utilisation directe d'outils en mode conversationnel : par exemple, combiner des données météo en temps réel avec un catalogue de produits indexé pour proposer le produit le mieux adapté... et c'est clé en main dans le moteur !

L'outil se veut super complet et va permettre aux clients "Entreprise" de créer des solutions agentiques très simplement : tout se fait dans une interface Kibana. On y combine des outils, comme la recherche ES|QL, la récupération de documents par ID, nos outils custom... dans des workflows, et on les utilise soit via le chat inclus, soit par l'API. Les outils de l'agent sont aussi mis à disposition dans un serveur MCP Elasticsearch.

Beaucoup de ces features reposent sur Jina.ai, qui est maintenant la propriété d'Elastic.

La démo des Streams était aussi sympa : l'idée est d'envoyer tous les logs en vrac dans Elastic. Puis un LLM est utilisé pour les partitionner (par type, par exemple « log_apache » et « log_mysql »). Enfin, toujours via un LLM et via l'interface graphique, nous pouvons créer le pipeline ingest qui va parser/analyser notre log et le rendre exploitable - la fin des galères avec nos patterns GROK ?!

Des retours d'expérience ⭐

La mémoire des agents

Exploiter un agent conversationnel nécessite de conserver l'historique des conversations afin de le servir comme contexte à chaque nouvelle question.

Cet historique est problématique car il peut vite être très volumineux et donc dépasser la limite de tokens autorisée. C'est là qu'il faut ruser.

Dans LangChain, ce n'est pas terrible : ils ont un tampon, disons 30k tokens, et le reste est oublié ;
Utiliser un LLM pour résumer la conversation, ce n'est pas terrible non plus, car on y perd en précision.

Le papier CoALA (Cognitive Architectures for Language Agents) essaie de résoudre ce problème. Il expose les différents types de mémoire : sémantique (ce que l'on sait, le RAG), épisodique (ce qu'on a fait, les actions), procédurale (système prompt)... La solution implémentée chez le client est donc de garder tout l'historique mais de le simplifier via cette logique et de le stocker dans Elasticsearch.

La recherche par image

L'exemple de Leroy Merlin (Adeo) était très sympa. Ils veulent proposer la recherche par image dans leur catalogue de 10 000 000 de produits. Il suffirait de prendre en photo l'objet pour le trouver - pas besoin de connaître son nom précis ("raccord de bonde en laiton coudé" 🤣).

Vous connaissez la chanson : on indexe des embeddings de nos images et on recherche en KNN. Rien de plus simple, le POC fonctionne, ça part en prod... MAIS !

Il y a des challenges :

l'usage de la mémoire explose ;
l'espace disque n'est pas prévisible ;
les recherches sont lentes ;
la pertinence n'est pas toujours au rendez-vous.

Répondre avec le top K ne suffit pas, la pertinence visuelle ne suffit pas... Il faut aussi qualifier les résultats selon des critères métier (qualité, marge, stock).

Leur solution a été de montrer l'image du client à un LLM pour créer une recherche naturelle ; au final, ils font la recherche avec l'image et avec les informations que le LLM a extrait (marque, catégorie de produit...), ce qui affine leurs résultats.

ES|QL en recherche applicative ? ⚡

ES|QL est partout dans les nouveaux produits, et on se pose donc la question : est-ce mature et pouvons-nous abandonner le QueryDSL ? Personnellement, je pense que c'est un peu tôt, et les quelques personnes avec qui j'en ai parlé le pensent aussi. Cependant, il faut bien l'admettre : ES|QL permet des choses qui ne sont pas possibles en QueryDSL et il est bien plus lisible ! L'autocomplétion est aussi vraiment complète et puissante.

J'y ai découvert la syntaxe FORK, qui permet d'exploiter la recherche hybride :

FROM index METADATA _score
| WHERE match(content, "JoliCode")
| WHERE year > 2010
-- hybrid
| FORK (WHERE semantic_content: "JoliCode")
          | SORT _score DESC)
       (WHERE match(content, "JoliCode"))
          | SORT _score DESC)
| FUSE RRF
| SORT _score DESC
| LIMIT 100
-- rerank
| RERANK "JoliCode" ON content
| SORT _score DESC
| LIMIT 10

ES|QL est aussi capable de fournir des réponses augmentées par LLM - faire un résumé des résultats, par exemple :

-- passage du résultat dans un LLM
| LIMIT 6
| COMPLETION CONCAT("Summarize : ", content) WITH "openai" AS summary

Avec un FORK en plus, la même requête va permettre d'avoir des documents, un résumé, des agrégations...

J'aime beaucoup aussi l'usage de CASE pour se passer de scripts Painless, souvent catastrophiques pour les performances.

FROM employees
| EVAL type = CASE(
    languages <= 1, "monolingual",
    languages <= 2, "bilingual",
     "polyglot")
| KEEP emp_no, languages, type

Quelques take-away rapides 📔

Cela fait un moment qu'il existe le type natif semantic_text, et je vous le recommande pour vos premiers essais. Il permet de s'affranchir du chunking, des dimensions, du stockage de vecteurs... C'est le moteur qui se charge de tout, et c'est aussi simple à utiliser qu'un champ text ;
Elastic Inference Service, c'est uniquement dans Elastic Cloud ;
Il y aura bientôt un mode "Elastic Cloud Connect" qui permettra de bénéficier de certaines fonctionnalités Cloud tout en ayant nos data nodes on-premise ;
Les vecteurs vont passer d'un stockage en float 32 bits à 16 bits en 9.3 sans perte de recall.
Le Serverless va bientôt (cette année) arriver en self-hosted !

Merci Elastic{On} 👏

J'ai passé une journée très instructive ; j'y ai trouvé du contenu technique, j'ai échangé avec des pairs, croisé de vieilles connaissances... merci Elastic !

Il est devenu difficile de suivre l'évolution du moteur depuis la version 8, les nouvelles fonctionnalités liées à l'IA sont nombreuses, et deviennent aussi un fort point de divergence avec OpenSearch, le fork d'Amazon. En terme de recherche hybride et de confort d'utilisation (ES|QL), il y a enfin de véritables impacts techniques dans le choix de l'un ou de l'autre.

Microservices et contrats d'API : Jane comme source de vérité

2026-01-13T14:42:00+01:00

Dans le développement d'une API, nous sommes tous confrontés au même défi : maintenir la cohérence entre la documentation et le code.

Qui n'a jamais perdu des heures à débugger une erreur parce que le champ user_id était devenu userId dans le code, mais pas dans la documentation ? C'est ce qu'on appelle le "drift". À mesure que le projet évolue, le code change, mais la documentation (OpenAPI, Wiki, Postman) traîne souvent la patte, devenant une source d'erreurs plutôt qu'une aide.

Et si la solution n'était pas de mettre à jour manuellement notre code pour coller à la doc, mais de générer automatiquement notre code à partir de la doc ? C'est ici qu'intervient Jane.

Découvrir Jane

En deux mots : Jane est une suite de librairies PHP dont la mission est de générer du code de qualité à partir de vos spécifications JSON Schema ou OpenAPI.

Si l'on devait résumer son rôle dans une API moderne, Jane agit comme le "traducteur automatique" entre vos contrats d'interface (vos spécifications .yaml ou .json) et votre code PHP. Au lieu d'écrire manuellement vos classes, vos validateurs et vos clients HTTP — une tâche répétitive et sujette à l'erreur humaine — Jane les fabrique pour vous.

Concrètement, Jane analyse votre schéma et produit :

Des Modèles (DTO) : Des classes PHP simples (POPO - Plain Old PHP Objects) strictement typées qui représentent vos données ;
Des Normalizers : Toute la logique nécessaire pour transformer ces objets en JSON et inversement, en s'appuyant sur le composant symfony/serializer ;
Un Client HTTP complet : (dans le cas du composant OpenAPI) Une implémentation prête à l'emploi (compatible PSR-18) pour consommer l'API, gérant les requêtes, les réponses et même les exceptions définies dans votre spec.

L'atout majeur de Jane n'est pas seulement le gain de temps, c'est la garantie de conformité. Puisque le code est généré directement depuis la source de vérité (le schéma), il est impossible d'avoir une divergence ("drift") entre ce que votre documentation prétend faire et ce que votre code fait réellement. Si le schéma change, vous régénérez le code, et le tour est joué.

Voyons un projet d’exemple

Pour passer de la théorie à la pratique, nous allons construire un cas d'usage classique : un tunnel d'achat e-commerce.

Nous allons simuler la transformation d'un panier en une commande validée. Pour cela, nous découpons la logique en deux micro-services distincts :

Le service Panier : Il matérialise l'état d'attente avant la commande. C'est lui qui mémorise les articles choisis au fur et à mesure que le client parcourt le site, avant qu'il ne décide (ou non) de passer à l'achat ;
Le service Commande : Il gère la finalisation de la vente et la collecte des informations client.

Ce scénario nous permettra d'explorer des cas concrets :

Côté Panier, nous utiliserons des UUID pour récupérer le contenu du panier ;
Côté Commande, nous mettrons en place une validation stricte des données (regex pour le téléphone, énumération pour le pays) lors de la transformation du panier en commande, ainsi qu'un endpoint pour les codes promo.

Voyons maintenant comment formaliser tout cela dans nos contrats d'API.

Créer nos micro-services (1 / 2) : Panier

Commençons par le service le plus simple : le Panier.

Ici, nous prenons le parti du Design First : avant d'écrire la moindre ligne de PHP, nous allons figer la structure de nos échanges dans un fichier cart.yaml.

Pour ce service, le besoin est basique : nous voulons pouvoir récupérer un panier via son identifiant unique. Voici notre définition en OpenAPI 3.0.3 :

openapi: 3.0.3
info:
  title: 'Service Panier'
  version: 1.0.0
paths:
  /carts/{id}:
    get:
      summary: 'Récupérer un panier'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 'Le panier trouvé'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
components:
  schemas:
    Cart:
      type: object
      properties:
        id:
          type: string
          format: uuid
        items:
          type: array
          items:
            type: string # simplifié pour l'exemple

Ce qu'il faut retenir ici

L'utilisation du format uuid sur l'identifiant (id) n'est pas anodine. Jane exploite cette information pour enrichir le code généré avec des règles de validation strictes, garantissant que la donnée n'est pas une simple chaîne de caractères mais bien un UUID valide.

Nous avons posé les bases du Panier. Attaquons-nous maintenant au second morceau du puzzle, qui va nous demander un peu plus de rigueur : le service Commande.

Créer nos micro-services (2 / 2) : Commande

Passons maintenant aux choses sérieuses avec le service Commande. Si le Panier était une simple lecture, la Commande implique de recevoir et valider des données utilisateur critiques.

C'est l'occasion idéale pour définir des règles strictes directement dans notre fichier order.yaml. Nous allons déclarer deux routes :

Une route de création de commande, qui valide l'adresse et le téléphone, données indispensables pour assurer la livraison ;
Une route pour appliquer un code de réduction à une commande (qui impactera le prix).

Voici à quoi ressemble notre contrat :

openapi: 3.0.3
info:
  title: 'Service Commande'
  version: 1.0.0
paths:
  /orders:
    post:
      summary: 'Créer une commande à partir d un panier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '201':
          description: 'Commande créée'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

/orders/{id}/discount:
    post:
      summary: 'Ajouter un code promo'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
      responses:
        '200':
          description: 'Code promo appliqué'

components:
  schemas:
    OrderInput:
      type: object
      required: ['cartId', 'customer']
      properties:
        cartId:
          type: string
          format: uuid
        customer:
          $ref: '#/components/schemas/CustomerAddress'

    CustomerAddress:
      type: object
      required: ['firstName', 'lastName', 'phoneNumber', 'countryCode']
      properties:
        firstName:
          type: string
        lastName:
          type: string
        phoneNumber:
          type: string
          pattern: '^\+33[1-9]\d{8}$' # Validation Regex pour numéros français
          description: 'Format: +33xxxxxxxxx'
        countryCode:
          type: string
          enum: ['FR', 'BE', 'LU'] # Limitation par énumération

    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: ['pending', 'paid', 'shipped']
        price:
          type: number
          description: 'Prix final après réduction éventuelle'

Pourquoi aller aussi loin dans la spec ?

Regardez bien le schéma CustomerAddress. Nous n'avons pas seulement défini des chaînes de caractères, nous avons imposé des contraintes métiers :

pattern : Le champ phoneNumber doit correspondre à une regex précise (+33...).
enum : Le champ countryCode ne peut être qu'une valeur parmi une liste définie (France, Belgique, Luxembourg).

Au lieu de coder ces validations "à la main" dans chaque contrôleur PHP, nous les déclarons une seule fois dans le contrat. Jane se chargera de traduire ces contraintes dans le code généré, garantissant que si une donnée ne respecte pas la spec, elle ne passera pas.

Nos contrats sont prêts. Il est temps de passer au PHP.

Configuration de Jane pour le projet exemple

Nos spécifications OpenAPI sont prêtes (cart.yaml et order.yaml). Il faut maintenant expliquer à Jane comment les transformer en code PHP.

Cela se passe via un fichier de configuration, généralement nommé .jane-openapi.php à la racine du projet.

Pour gérer nos deux micro-services (Panier et Commande) sans mélanger leur code, nous utilisons l'option mapping. Elle permet de définir des règles de génération spécifiques pour chaque fichier OpenAPI au sein d'une seule et même configuration.

Voici à quoi ressemble notre fichier .jane-openapi.php:

<?php

return [
    'mapping' => [
        __DIR__ . '/cart.yaml' => [
            'namespace' => 'App\Generated\Cart',
            'directory' => __DIR__ . '/generated/Cart',
        ],
        __DIR__ . '/order.yaml' => [
            'namespace' => 'App\Generated\Order',
            'directory' => __DIR__ . '/generated/Order',
        ],
    ],
    ‘validation’ => true,
];

Les options disponibles

Déchiffrons ensemble cette configuration :

mapping : C'est la clé maîtresse qui nous permet d'associer chaque fichier de spécification (la clé du sous-tableau, ici le chemin vers cart.yaml ou order.yaml) à sa propre configuration.
namespace : C'est ici que l'organisation se joue. En donnant des namespaces différents (App\Generated\Cart vs App\Generated\Order), nous isolons complètement les domaines. Si un modèle s'appelle Error dans les deux services, il n'y aura aucun conflit de nom de classe dans notre projet.
directory : Le dossier de destination où le code PHP généré pour chaque service va être écrit.
validation : C'est une option capitale. En la passant à true, nous demandons à Jane de traduire les contraintes du schéma OpenAPI (comme minimum: 1, required, email) en métadonnées de Symfony Validator. C'est le socle qui nous permettra de garantir la robustesse des données sans avoir à réécrire manuellement les règles métiers en PHP. Nous verrons plus loin à quel point cela nous simplifie la vie.

Avec cette structure, Jane va itérer sur chaque entrée du mapping et produire automatiquement deux clients HTTP (compatibles PSR-18) distincts et autonomes.

Et les erreurs ? Standardisation et gestion avec Jane

Gérer le "happy path" (code 200), c'est facile. Mais dans la vraie vie, une API échoue : validation invalide (400), accès refusé (403) ou crash serveur (500).

Si nous laissons Jane deviner, elle lèvera des exceptions génériques HTTP. Mais nous pouvons faire mieux : nous pouvons uniformiser le format de nos erreurs pour que notre SDK PHP renvoie des objets structurés, faciles à manipuler dans un try/catch.

Définir un schéma d'erreur standard

Dans nos fichiers OpenAPI (cart.yaml et order.yaml), nous allons ajouter une définition réutilisable dans la section components. Cela permet d'avoir un format unique (par exemple : un message et un code) pour toutes nos erreurs.

Ajoutons ceci à la fin de nos fichiers YAML :

components:
  schemas:
    # ... nos autres modèles (Cart, Product...)

    # Notre modèle d'erreur standardisé
    Error:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Le message d'erreur pour le développeur
        code:
          type: integer
          description: Un code d'erreur interne spécifique

Référencer ce schéma dans les endpoints

Maintenant que le modèle Error existe, nous devons dire à chaque endpoint : "Si nous renvoyons une 400, 403 ou 500, le corps de la réponse respectera ce schéma".

Reprenons l'exemple de l'ajout d'un code de réduction sur une commande:

paths:
  /orders/{id}/discount:
    post:
      summary: 'Ajouter un code promo'
      # ... (requestBody, etc)
      responses:
        '200':
          description: 'Code promo appliqué'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

        # Gestion des erreurs standardisée
        '400':
          description: 'Données invalides (ex: code non trouvé)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Action non autorisée
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Commande introuvable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Erreur serveur
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Ce que Jane va générer pour nous

C'est ici que la magie opère. Lors de la génération, Jane va détecter ces configurations et produire deux choses très utiles :

Un POPO Error : Une classe PHP classique (App\Generated\Order\Model\Error) avec ses getters et setters.
Des Exceptions spécifiques : Pour l'endpoint ci-dessus, Jane va générer des exceptions comme AddDiscountBadRequestException ou AddDiscountNotFoundException.

Ces exceptions auront une méthode getError() qui retournera... notre instance du modèle Error remplie avec les données de l'API !

Cela permet d'écrire un code client très propre :

try {
    $api->addDiscount('C17891', new OrdersIdDiscountPostBody('NOEL2025'));
} catch (AddDiscountBadRequestException|AddDiscountNotFoundException $e) {
    // On récupère notre objet Error proprement
    $errorModel = $e->getResponse();
    echo "Erreur fonctionnelle : " . $errorModel->getMessage();
} catch (ClientExceptionInterface $e) {
    // Erreur réseau ou autre
}

En standardisant vos retours d'erreurs dans l'OpenAPI, vous garantissez que le code PHP généré est prévisible et facile à utiliser pour les développeurs qui consommeront votre SDK.

Lancer la génération du code !

C'est ici que la magie opère. Fini d'écrire des DTOs, des clients HTTP et des exceptions à la main. Jane va faire tout ce travail fastidieux pour nous.

Dans votre terminal, à la racine du projet, lancez simplement :

vendor/bin/jane-openapi generate --config-file .jane-openapi.php

Jane va lire le fichier .jane-openapi.php, détecter notre mapping et générer les fichiers correspondants. Si vous allez voir dans votre dossier generated/, nous avons deux nouveaux dossiers qui sont apparus : Cart et Order.

Une étape indispensable : l'autoloader

Avoir les fichiers PHP, c'est bien, mais pouvoir les utiliser, c'est mieux ! Comme ce sont de nouvelles classes dans un nouveau dossier, Composer ne les connaît pas encore.

Pour que Composer puisse charger ces nouvelles classes, nous devons mettre à jour le composer.json. Plutôt que de déclarer chaque service un par un, allons au plus simple : nous allons faire pointer le namespace parent App\Generated\ directement vers le dossier generated/.

Ouvrez votre composer.json et ajoutez ces lignes dans la section autoload :

"autoload": {
    "psr-4": {
        "App\\": "src/",
        "App\\Generated\\": "generated/"
    }
},

Ensuite, pour que cette modification soit prise en compte, régénérez l'autoloader :

composer dump-autoload

C'est tout ! Votre projet est maintenant prêt à utiliser les librairies générées.

Que contient ce dossier generated ?

Si vous êtes curieux (et vous devriez l'être), jetez un œil à l'intérieur de generated/Cart ou generated/Order. Vous y trouverez une structure très organisée :

generated/
├── Order
│   ├── Client.php
│   ├── Endpoint
│   ├── Exception
│   ├── Model
│   ├── Normalizer
│   ├── Runtime
│   │   ├── Client
│   │   └── Normalizer
│   └── Validator
└── Cart
    ├── Same file structure as Order
    └── ...

Client.php : Votre point d'entrée principal. C'est la classe qui contient toutes les méthodes comme createOrder(), addDiscount(), etc.
Endpoint/ : Chaque opération définie dans votre schéma OpenAPI (comme GET /carts/{id}) possède ici sa propre classe dédiée. C'est elle qui orchestre l'appel API : elle sait quelle méthode HTTP utiliser, quel corps de requête envoyer, comment transformer la réponse brute en un objet de votre Model et comment gérer les exceptions selon le code de retour.
Exception/ : C'est ici que se trouvent nos erreurs typées (AddDiscountBadRequestException, etc.) basées sur les codes HTTP et nos schémas d'erreurs.
Model/ : Vos POPO (Plain Old PHP Objects). Ce sont les classes Cart, Order, OrderInput, etc. Elles contiennent simplement des propriétés, des getters et des setters.
Normalizer/ : C'est le cœur de Jane (basé sur le composant Serializer de Symfony). Ces classes savent comment transformer vos objets en JSON et inversement.
Runtime/ : C'est la salle des machines. Ce dossier contient le code "support" nécessaire au fonctionnement global du SDK généré (configuration du client, normalizers de base). Ce sont des composants techniques qui font le lien entre votre code généré et les librairies tierces (comme le client HTTP PSR-18).
Validator/ : C'est la particularité liée à notre option "validation": true. Jane génère des classes de contraintes spécifiques (ex: OrderInputConstraint).
Détail technique : Ces classes étendent Compound de Symfony Validator. Elles regroupent toutes les règles définies dans votre OpenAPI (Required, Email, Regex etc.) en une seule classe appelable. Cela garde vos modèles propres tout en garantissant une validation stricte.

Utilisation pratique : intégrer les modèles Jane dans votre code

Maintenant que nos classes sont générées, comment les utiliser concrètement ?

Jane brille par sa rigueur : elle sécurise les échanges via ses Normalizers et force l'utilisation d'objets typés.

La validation automatique

L'un des atouts de Jane est qu'elle intègre la validation directement dans le processus de sérialisation et de désérialisation.

Cela signifie que le contrôle des données est actif dans les deux sens :

En entrée (Désérialisation) : Vous ne pouvez pas créer un objet PHP invalide à partir d'un JSON reçu.
En sortie (Sérialisation) : Vous ne pouvez pas générer un JSON invalide à partir d'un objet PHP (par exemple, si vous avez oublié de remplir un champ obligatoire avant de renvoyer la réponse).

Vous n'avez donc plus besoin d'appeler le validateur manuellement. Regardez le code généré dans le Normalizer (ici OrdersIdDiscountPostBodyNormalizer) : il vérifie les contraintes pendant la transformation.

Si vous utilisez le Serializer de Symfony dans votre contrôleur, la validation est implicite :

namespace App\Controller;

use App\Generated\Order\Model\OrdersIdDiscountPostBody; // Le DTO généré
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Serializer\SerializerInterface;
use Symfony\Component\Serializer\Exception\ValidationFailedException;

class OrderController extends AbstractController
{
    public function addDiscount(Request $request, SerializerInterface $serializer)
    {
        try {
            // C'est ici que la magie opère :
            // Jane désérialise ET valide en même temps.
            // Si le JSON est invalide (code manquant, trop court...), une exception est levée.
            /** @var OrdersIdDiscountPostBody $body */
            $body = $serializer->deserialize(
                $request->getContent(),
                OrdersIdDiscountPostBody::class,
                'json'
            );

        } catch (ValidationFailedException $e) {
            // On récupère les violations pour répondre une 400 propre via la constante Symfony
            return $this->json($e->getViolations(), Response::HTTP_BAD_REQUEST);
        }

        // Si on arrive ici, $body est un objet valide et typé !
        $code = $body->getCode();
        // ... traitement métier
    }
}

Le gain ? Votre code métier ne manipule jamais de données "sales". Et inversement, vous avez la certitude absolue que vos réponses API respectent toujours le contrat défini dans votre fichier YAML.

Gérer les erreurs (Exceptions typées)

C'est ici que notre travail sur les schémas d'erreurs 400 / 404 / 500 porte ses fruits. Jane a généré des exceptions spécifiques pour chaque cas d'erreur documenté.

Fini les vérifications manuelles du status code, place aux try/catch explicites :

use App\Generated\Order\Exception\AddDiscountBadRequestException;
use App\Generated\Order\Exception\AddDiscountNotFoundException;
use App\Generated\Order\Model\OrdersIdDiscountPostBody;

try {
    $payload = new OrdersIdDiscountPostBody();
    $payload->setCode('INVALID');

    $apiClient->addDiscount('order-12345', $payload);

} catch (AddDiscountBadRequestException $e) {
    // C'est une 400 spécifique à cette route (Response::HTTP_BAD_REQUEST)
    // On récupère notre objet Error structuré défini dans l'OpenAPI
    $errorModel = $e->getError();

    // Affiche : "Code promo invalide ou expiré"
    $logger->warning($errorModel->getMessage());

} catch (AddDiscountNotFoundException $e) {
    // C'est une 404 spécifique (Commande ou code de réduction introuvable)
    // ...
} catch (\Exception $e) {
    // Erreur réseau ou 500 générique
}

Communication inter-services : Quand le service Commande appelle le service Panier

Dans une architecture microservices, la communication synchrone (HTTP) est souvent le talon d'Achille. On se retrouve vite avec des appels curl ou Guzzle éparpillés, des tableaux associatifs non typés et, surtout, une confiance aveugle envers le service appelé.

Maintenant, nous allons voir comment Jane sécurise l'échange entre notre service Commande (le consommateur) et le service Panier (le producteur).

Le contrat comme dépendance : Réutiliser le schéma OpenAPI

Au lieu de redéfinir manuellement une classe PanierDTO dans le service Commande (qui finirait inévitablement par diverger de la réalité), nous utilisons directement la définition OpenAPI du service Panier.

Concrètement, cela signifie que le fichier openapi.yaml du service Panier devient une "dépendance" du service Commande.

Configuration Jane : Dans le service Commande, nous configurons Jane pour pointer vers ce fichier (via une URL, un submodule git, …).
Single Source of Truth : Si l'équipe Panier met à jour son modèle (par exemple, en ajoutant un champ promoCode), le service Commande le saura dès la prochaine régénération du code.

Génération d'un Client HTTP typé (SDK interne)

C'est une des fonctionnalités clé de Jane pour la communication inter-services. En plus des modèles (DTOs), Jane a généré un Client HTTP complet prêt à l'emploi (compatible PSR-18).

Pour l'utiliser, on va instancier le client via sa méthode statique create() :

use App\Generated\Panier\Client;

$panierClient = Client::create();
$panier = $panierClient->getPanier($uuid);

// $panier est une instance de la classe \App\Generated\Panier\Model\Panier
// L'IDE connaît toutes les propriétés :
$total = $panier->getTotal();
foreach ($panier->getItems() as $item) {
    // ...
}

Nous manipulons des objets PHP natifs, typés, générés spécifiquement pour cette interaction.

Validation automatique de la réponse

Que se passe-t-il si le service Panier a un bug et renvoie un prix sous forme de chaîne de caractères 10,50€ au lieu d'un nombre 10.50, ou s'il manque un champ obligatoire ?

Avec un client HTTP manuel, votre code planterait probablement plus loin, de manière obscure (Call to member function on null ou erreur de calcul), ou pire, corromprait vos données silencieusement.

Avec le client généré par Jane :

Le client valide automatiquement la réponse HTTP reçue par rapport au schéma OpenAPI ;
Si la réponse ne respecte pas le contrat (type incorrect, champ manquant), Jane lève immédiatement une UnexpectedValueException ou une InvalidResponseException ;
Fail Fast : L'application s'arrête net à la frontière du service, empêchant des données invalides de polluer votre logique métier de commande.

En résumé, Jane transforme un appel HTTP incertain en un appel de méthode PHP sûr et typé.

Validation stricte dans les tests

Au lieu de charger vos données de test et ne jamais vérifier leur intégrité, passez-les dans la moulinette de Jane.

Si votre donnée ne correspond plus à la réalité de l'API (changement de type, champ manquant), Jane le détecte immédiatement.

// 1. On charge la donnée brute (ici on prends un JSON en exemple
// mais un endpoint API fonctionnera pareil
$data = json_decode(file_get_contents('panier_fixture.json'), true);

// 2. On demande à Jane de créer l'objet.
// C'est ici que la magie opère : Jane vérifie TOUT le contrat via la validation
// dans le Normalizer généré
try {
    $panier = $serializer->denormalize($data, Panier::class);
} catch (Exception $e) {
    // Le test échoue immédiatement si le JSON est périmé !
    $this->fail('Vos données de test ne respectent plus le contrat OpenAPI : ' . $e->getMessage());
}

// 3. On utilise un objet PHP valide pour configurer le mock
// ou autre test que vous voudriez faire
$mockService->method('getPanier')->willReturn($panier);

Pourquoi c'est puissant ?

Cela transforme vos tests unitaires en tests de contrat légers. Vous n'avez plus peur que vos tests "passent au vert" alors qu'ils utilisent des données obsolètes qui feront planter la production.

Évolution et versioning : Faire évoluer votre API sans tout casser

Une API n'est jamais figée. Elle vit, elle change, elle s'étend. Le cauchemar de tout développeur est de déployer une mise à jour qui casse la communication entre les services. Avec Jane, l'impact d'une modification du contrat OpenAPI devient immédiatement visible dans votre code PHP.

Ajout d'un champ optionnel (Non-breaking change)

C'est le scénario idéal. Vous ajoutez, par exemple, une description facultative à votre objet Commande.

Dans l'OpenAPI : Vous ajoutez le champ sans le marquer comme required.
Après régénération Jane : Votre classe Commande gagne une propriété protected ?string $description = null; ainsi que ses getters et setters.
Impact : Nul. Votre code existant continue de fonctionner parfaitement car le constructeur reste compatible (le nouveau champ est initialisé à null par défaut). C'est une évolution en douceur.

Ajout d'un champ obligatoire (Breaking change)

C'est ici que Jane vous sauve la mise. Imaginons que le service Panier exige désormais un customerId pour chaque création de panier.

Dans l'OpenAPI : Le champ customerId est ajouté à la liste required.
Après régénération Jane : La signature du constructeur de la classe Panier change radicalement.
- Avant : public function __construct(string $uuid)
- Après : public function __construct(string $uuid, string $customerId)
Impact : Immédiat et visible. Partout dans votre code où vous instanciez un Panier sans ce nouvel argument, votre code ne fonctionne plus. Votre IDE (PhpStorm, VSCode) surligne les erreurs en rouge avant même que vous ne lanciez le moindre test.

Note clé : Jane transforme une erreur de "runtime" (qui arriverait en production) en une erreur de "compile-time" (qui arrive sur votre machine).

Régénération et impact sur le code : La boucle de sécurité

Le workflow de mise à jour devient alors très sécurisant :

Mise à jour du contrat : Vous récupérez la nouvelle version de openapi.yaml.
Régénération : Vous lancez la génération du code Jane.
Analyse d'impact : Vous lancez l'analyse statique (PHPStan, Psalm) ou simplement vos tests.
Correction : Jane vous a forcé à voir tous les endroits du code impactés par le changement. Vous ne pouvez pas "oublier" de traiter le nouveau champ obligatoire.

En résumé, Jane agit comme un révélateur de dette technique immédiat lors des mises à jour d'API.

Conclusion : Pourquoi passer à l'approche "Contract-First" avec Jane ?

Au fil de cet article, nous avons vu que Jane n'est pas simplement un générateur de code, c'est un changement de paradigme dans la façon de concevoir la communication entre vos services. En plaçant le schéma OpenAPI au centre du jeu, vous gagnez sur quatre tableaux majeurs :

Type Safety : L'armure de votre code

Fini les array mystérieux qui circulent d'un service à l'autre. Avec Jane, chaque donnée entrante ou sortante est encapsulée dans un objet PHP fortement typé.

Vous savez exactement ce que vous manipulez : des entiers sont des int, des dates sont des \DateTime. PHPStan et votre IDE vous remercient, et votre code devient auto-documenté par sa structure même.

Documentation Vivante

Souvent, la documentation est le parent pauvre du projet : écrite au début, jamais mise à jour, et finalement trompeuse.

Ici, la spécification OpenAPI est votre Source de Vérité. Puisque c'est elle qui génère le code qui tourne en production, elle est de facto toujours à jour.

Couplée à des outils de visualisation comme SwaggerUI ou ReDoc, cette documentation devient interactive et fiable pour toutes les équipes (frontend, mobile, partenaires). Ce que vous voyez dans la doc est exactement ce que le code attend.

Moins de Bugs en Production

En transformant les erreurs de runtime (données mal formées, champs manquants) en erreurs de "compile-time" (le code généré change, l'IDE signale l'erreur), vous capturez les bugs le plus tôt possible.

La validation automatique des réponses agit comme un filet de sécurité : aucune donnée corrompue ne peut pénétrer silencieusement dans votre système pour causer des erreurs en cascade plus loin.

Une DX retrouvée

C'est peut-être le point le plus important au quotidien. Plus besoin de faire des allers-retours incessants entre le code et une documentation PDF externe.

L'autocomplétion de l'IDE fonctionne instantanément.
Les refactorings sont sûrs.
Les tests sont plus simples à écrire et plus robustes.

Performance accrue

Au-delà de la sécurité et du confort, le gain de performance est significatif. Le code généré par Jane étant spécifique à vos modèles, il est beaucoup plus performant que l'utilisation générique de l'ObjectNormalizer du Serializer de Symfony. En évitant d'utiliser la Reflection lors de l'exécution de votre code, vos applications consomment moins de ressources et répondent plus vite.

Le mot de la fin : Arrêtez d'écrire vos clients HTTP et vos DTOs à la main. Laissez Jane faire, de manière optimisée, le travail répétitif et concentrez-vous sur ce qui a de la valeur : votre logique métier.

Arrêtez de deviner : Interceptez vos flux HTTP(s) avec MITMProxy

2025-12-04T13:42:00+01:00

Vous récupérez une codebase inconnue, vous savez qu’elle effectue des requêtes HTTP(s), mais vous ne savez pas vers où, ni ce qu'elle envoie ? C'est une situation classique. Nous allons voir comment intercepter et analyser ce trafic simplement.

Pour cela, nous utiliserons un proxy. C'est un intermédiaire qui se place entre votre code et le monde extérieur. Nous parlons de "Man In The Middle" (MITM). Non, aucun rapport avec Malcolm. Quoique... c'est exactement le principe : nous nous mettons au milieu pour écouter.

L'outil du jour s'appelle mitmproxy.

Installation de mitmproxy

C'est très simple. On récupère l'archive, on décompresse et on déplace les binaires.

# Download the binary (check https://www.mitmproxy.org/downloads/ for latest version)
wget https://downloads.mitmproxy.org/12.2.1/mitmproxy-12.2.1-linux-x86_64.tar.gz -O mitm.tgz

# Extract and cleanup
tar xzf mitm.tgz
rm mitm.tgz

# Move binaries to a global path
sudo mv mitm* /usr/local/bin

L'archive contient trois binaires. Nous utiliserons ici mitmweb, car il fournit une interface graphique web idéale pour débuter.

Exécution de mitmweb

Démarrons le proxy avec deux options explicites :

--web-port : le port de l’interface d'administration web.
--listen-port : le port d'écoute du proxy (par où transitent les requêtes).

mitmweb --web-port 9999 --listen-port 8888

Ouvrez votre navigateur sur : http://127.0.0.1:9999/. Note : Jetez un œil aux logs de mitmweb, un token de sécurité peut être requis.

Premier test en HTTP

La plupart des clients HTTP (curl, symfony/http-client, clients Go/Rust...) respectent une convention : si la variable d'environnement http_proxy existe, le trafic transite par celle-ci.

Testons avec curl :

# Send a request through the proxy
http_proxy=http://localhost:8888 curl http://perdu.com

<html><head><title>Vous Etes Perdu ?</title></head><body>[...]</body></html>

Si nous regardons l'interface web, nous verrons la requête et sa réponse. C’est propre, efficace. Mais le HTTP clair, c'est de l'histoire ancienne. Passons aux choses sérieuses.

Comment proxifier du HTTPS ?

mitmproxy gère le HTTPS nativement. Essayons la même méthode :

https_proxy=http://127.0.0.1:8888 curl https://perdu.com

curl: (60) SSL certificate problem: unable to get local issuer certificate
[...]

Échec. curl refuse la connexion. Pourquoi ?

mitmproxy n'est pas un simple passe-plat. Pour pouvoir nous montrer le contenu chiffré, il doit le déchiffrer. Pour ce faire, il "termine" la connexion SSL en se faisant passer pour le serveur final (perdu.com), puis initie une nouvelle requête vers le vrai serveur.

C'est une véritable attaque "Man In The Middle". Sauf que curl est bien élevé : il vérifie le certificat du serveur. Comme mitmproxy signe les réponses avec son propre certificat (inconnu de votre système), curl panique et coupe tout. Heureusement !

Solution 1 : Le mode "Bourrin" (Insecure)

Nous pouvons demander au client d'ignorer la sécurité.

# -k or --insecure allows insecure server connections
curl -k --proxy http://127.0.0.1:8888 https://perdu.com

C'est utile pour un test rapide, mais dangereux. De plus, ce n'est pas toujours possible (binaire compilé, code tiers sans option de configuration facile, etc.).

Exemple pratique avec Git :

# Check remote tags without cloning, bypassing SSL verification is risky but possible
git -c "http.proxy=127.0.0.1:8888" ls-remote --tags https://github.com/twigphp/twig

fatal: unable to access 'https://github.com/twigphp/twig/': server certificate verification failed. CAfile: none CRLfile: none

Note : nous aurions pu passer l’option -c "http.sslVerify=false", mais ca n’aide pas l’article 🙈

Solution 2 : La méthode propre (Trust the CA)

Pour que votre système accepte mitmproxy comme une autorité légitime, nous devons ajouter son certificat racine (CA) à votre magasin de certificats local.

Au premier lancement, mitmproxy a généré ses certificats dans ~/.mitmproxy/. Sous Debian/Ubuntu, voici la procédure pour les installer proprement :

Convertir et copier le certificat :

# Convert PEM to CRT format (if needed by your distro, usually for ca-certificates)
openssl x509 -in ~/.mitmproxy/mitmproxy-ca-cert.pem -inform PEM -out ~/.mitmproxy/mitmproxy.crt

# Copy to the CA store directory
sudo cp ~/.mitmproxy/mitmproxy.crt /usr/share/ca-certificates/extra
# Or for some systems
sudo cp ~/.mitmproxy/mitmproxy.crt /usr/local/share/ca-certificates/

Mettre à jour le store :

# Update the system's CA bundle
sudo update-ca-certificates

Si nous voyons 1 added, 0 removed; done., c'est gagné.

Nous pouvons maintenant lancer vos requêtes HTTPS sans le flag -k, elles apparaîtront en clair dans mitmweb.

https_proxy=http://127.0.0.1:8888 curl https://perdu.com
<html><head><title>Vous Etes Perdu ?</title></head><body>[...]</body></html>

Conclusion

Vous voilà équipés pour inspecter le trafic sortant de vos applications, même chiffré. Que ce soit pour débugger une API capricieuse, reverse-engineer un SDK tiers mal documenté ou comprendre pourquoi votre CI échoue, mitmproxy lève le voile sur la "boîte noire".

Gardez cet outil à portée de main, mais un dernier conseil : n'oubliez pas de nettoyer vos variables d'environnement (unset https_proxy) une fois le debug terminé. Sinon, vous passerez votre matinée de demain à vous demander pourquoi votre terminal n'a plus accès à Internet !