Face à une actualité internationale qui nous pousse à réduire nos dépendances technologiques vis-à-vis des acteurs américains (infrastructure comme IA), on peut construire un agent IA pleinement opérationnel 100 % hébergé et exécuté en Europe. Notre assistant de conférence tourne sur une stack open source européenne, du runtime jusqu’à l’application, fait son inférence en France avec Mistral, et ne stocke que le strict nécessaire côté données utilisateur·ices. La souveraineté, ici, c’est le résultat d’une série de choix d’architecture pris dès le développement. On détaille ces choix dans cet article. Vous pouvez retrouver la partie 1 et la partie 2 de ce retour d’expérience sur notre blog.

Contexte et enjeux

Le choix devenu commun est de passer par AWS, GCP, Azure et OpenAI ou Anthropic quand il s’agit d’un projet basé sur l’IA et qui nécessite un hébergement. Toutes ces entreprises étant soumises au cadre juridique des États-Unis, les données de l’application et de ses utilisateurs deviennent accessibles. Pour beaucoup d’organisations européennes, issues du secteur public, santé, ou simplement soumises au RGPD, ça pose des questions de conformité et de dépendance stratégique.

Inférence locale avec Mistral

Le modèle qui fait tourner l’assistant vient de Mistral AI, une entreprise française, et l’inférence a lieu sur le territoire de l’UE. Côté intégration, ça se résume à déclarer la plateforme et utiliser une clé d’API dans l’application.

Toutes les données (requêtes des utilisateur·ices, contexte de l’événement, appels d’outils générés par le modèle) restent dans la juridiction européenne. Pour un responsable de traitement au sens du RGPD, ça simplifie beaucoup les choses : plus besoin d’analyse d’impact sur les transferts hors UE (AIPD), plus de clauses contractuelles types pour les flux d’inférence, plus d’incertitudes sur où le traitement a lieu.

Réversibilité et interopérabilité

Une souveraineté qui enfermerait l’application chez un seul prestataire ne ferait que déplacer le problème de dépendance. On a donc pensé l’architecture pour garantir la réversibilité à chaque niveau.

• Le modèle est interchangeable : Symfony AI abstrait le fournisseur d’inférence derrière une interface générique. Passer de Mistral à un autre fournisseur, ou à un modèle à poids ouverts auto-hébergé sur une infrastructure GPU dédiée, c’est une simple modification de configuration et non pas une réécriture du code métier. Le prompt, les outils et l’interface restent inchangés.
• Le client est interchangeable aussi : comme le produit s’articule autour d’un serveur MCP (voir la Partie 1), les échanges passent par un protocole ouvert, sans SDK propriétaire entre l’agent et le serveur. L’interface de chat sous Symfony pourrait être remplacée par n’importe quel autre agent compatible MCP sans toucher au code serveur.

Une stack technologique européenne et open source

Le tableau ci-dessous récapitule la stack complète. Il n’y a aucune dépendance logicielle ni infrastructure hors d’Europe :

Chaque composant open source est auditable et peut être auto-hébergé intégralement, sans communication cachée vers des tiers hors Europe.

Minimisation des données dès la conception

La conformité RGPD est plus simple à gérer quand on ne collecte que l’essentiel dès le départ.

• Identités éphémères : à l’authentification via GitHub, le jeton est validé auprès de l’API tierce pour instancier un utilisateur en mémoire, le temps de la requête. Cette identité n’est jamais persistée en base, seul l’identifiant numérique stable de GitHub est conservé, pour l’associer aux votes et commentaires.
• Données minimales stockées : un vote ou un commentaire, c’est l’identifiant GitHub, le pseudo public, le contenu et un horodatage. Rien d’autre.
• Pas de stockage d’IP : le rate limiting s’appuie sur l’identifiant GitHub de l’utilisateur·ice connecté·e, pas sur l’adresse réseau. Les outils d’écriture sont protégés sans qu’on ait besoin de journaliser la moindre IP.
• Masquage des données sensibles : la couche temps réel peut faire transiter des jetons d’autorisation dans les paramètres de requête, donc le serveur filtre explicitement ces variables avant qu’elles atterrissent dans les logs.

Cohérence entre résidence et sécurité des données

Héberger les données en Europe ne sert à rien si l’application a des failles de sécurité par ailleurs. La Partie 2 détaille les mesures concrètes : validation systématique des tokens GitHub, rate limiting par utilisateur·ice, Content-Security-Policy à base de nonce, et commentaires marqués comme données non vérifiées pour limiter les risques d’injection de prompt indirecte.

Conclusion

On perçoit parfois la souveraineté comme une contrainte qui réduit les performances ou complique le développement. Ce projet montre le contraire : une stack open source européenne combinée à l’inférence Mistral a suffi pour livrer un agent fonctionnel (streaming, appels d’outils, persistance) sans les barrières réglementaires liées aux transferts de données.

Cinq principes ont guidé la démarche :

1. Une inférence localisée, isolée derrière une couche d’abstraction logicielle.
2. Un protocole ouvert, pour éviter le verrouillage technologique.
3. Des briques open source auditables (FrankenPHP, Symfony, API Platform, Mercure).
4. Un hébergement basé en Europe.
5. La minimisation des données intégrée directement dans le code.

On se retrouve la semaine prochaine ?

L’assistant est en ligne dès maintenant, avant même l’ouverture des portes : de quoi préparer votre venue, repérer les talks à ne pas manquer et construire votre agenda à l’avance. Rendez-vous les 17 et 18 septembre à EuraTechnologies pour la sixième édition de l’API Platform Conference !

Cet article, Souveraineté : de l’IA agentique qui garde vos données en Europe, est paru en premier sur Les-Tilleuls.coop.

La première partie de ce retour d’expérience expliquait le choix d’architecture : construire un serveur MCP plutôt qu’un chatbot isolé, pour que le service soit accessible à n’importe quel agent IA, l’interface de chat devenant simplement son premier client. Cet article rentre dans le détail technique de ce service et du client qui s’y connecte. La partie 3 évoque les outils souverains qu’on a utilisés.

La décision d’architecture la plus structurante a été de s’appuyer sur l’écosystème existant plutôt que d’écrire du code de transport MCP à la main. Pas de dispatcher JSON-RPC, pas de sérialiseur de schéma, pas de routeur d’outils développés maison : API Platform expose maintenant les ressources d’API comme des outils MCP via un seul attribut. La couche State, qui alimente déjà le REST et le GraphQL, fait le travail de handler d’outils sans qu’on ait rien à changer. Le reste de la stack : FrankenPHP, Mercure, Symfony AI et Mistral s’articule autour de cette brique centrale. On détaille chaque composant dans les sections qui suivent.

La forme du système

L’interface de chat n’est qu’un client parmi d’autres. Claude Desktop, un assistant d’IDE ou un script maison, du moment qu’ils parlent MCP, ils se connectent au même serveur et accèdent aux mêmes 21 outils. Cette interopérabilité découle directement des choix d’architecture qu’on a faits au départ.

Un attribut transforme une ressource en outil

Le support MCP d’API Platform permet de déclarer des outils directement dans les métadonnées de la ressource. Voici la ressource Feedback, qui gère les votes et les commentaires, avec deux de ses outils :

#[ApiResource(
    operations: [],
    mcp: [
        'talk-feedback' => new McpTool(
            name: 'talk-feedback',
            description: 'Read the community feedback for an API Platform Conference 2026 talk: number of votes, average rating and the comments (with author). Public — no authentication needed.',
            input: FeedbackInput::class,
            processor: TalkFeedbackProcessor::class,
            structuredContent: true,
        ),
        'vote-talk' => new McpTool(
            name: 'vote-talk',
            description: 'Rate an API Platform Conference 2026 talk (1–5). Requires a GitHub access token (sent as a Bearer token); one vote per talk per user — voting again updates your rating. Returns the updated feedback.',
            input: VoteInput::class,
            processor: VoteTalkProcessor::class,
            structuredContent: true,
        ),
        'comment-talk' => new McpTool(
            name: 'comment-talk',
            description: 'Post a comment on an API Platform Conference 2026 talk. Requires a GitHub access token (sent as a Bearer token); the comment is attributed to your GitHub login. Returns the updated feedback.',
            input: CommentInput::class,
            processor: CommentTalkProcessor::class,
            structuredContent: true,
        ),
    ],
)]
final class Feedback {/* properties */}

final readonly class VoteTalkProcessor implements ProcessorInterface
{
public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): Feedback
{
    /* Security & validation */

    $talk = $this->conference->findTalk($data->slug)
        ?? throw new \RuntimeException(\sprintf('Unknown talk "%s".', $data->slug));

    $existing = $this->em->getRepository(Vote::class)->findOneBy([
        'talkSlug' => $talk->slug,
        'authorId' => $user->githubId,
    ]);

    /* Upsert logic: adding or replacing existing vote for user */

    return $this->feedback->summary($talk->slug, $talk->title, $message);
}
}

{$SERVER_NAME:localhost} {
    root /app/public
    mercure { /* Configuration des jetons JWT et accès anonymes */ }
    php_server {
        worker {
            file ./public/index.php
        }
    }
}

final class CspNonceProvider implements ResetInterface
{
    private ?string $nonce = null;

    public function getNonce(): string
    {
        return $this->nonce ??= bin2hex(random_bytes(16));
    }

    public function reset(): void
    {
        $this->nonce = null;
    }
}

// Prepare context window
$messageBag = $this->buildMessageBag();
$execution = $this->conference->call($messageBag, ['stream' => true]);

foreach ($execution->asTextStream() as $delta) {
    $text = $delta->getText();

    if ('' === $text) {
        continue;
    }

    $answer .= $text;
// Publishes longest valid-UTF-8 prefix & leaves the incomplete tail for the next call
    $this->bufferAndPublish($topic, $byteBuffer, $text);
}
// Flush whatever was buffered
$this->flush($topic, $byteBuffer);

ai:
  platform:
    mistral:
      api_key: '%env(MISTRAL_API_KEY)%'
  agent:
    conference:
      platform: 'ai.platform.mistral'
      model:
        name: '%env(AI_MODEL)%'
        options:
          temperature: '%env(AI_TEMPERATURE)%'
      prompt:
        text: |
          You are the assistant for the API Platform Conference 2026
          (17–18 September 2026, EuraTechnologies, Lille — organized by Les-Tilleuls.coop).
          You help attendees explore the agenda, talks, speakers, schedule, partners and practical information.
          Rules:

Cet article, Transformer une API en boîte à outils pour agents : l’architecture de notre assistant de conférence, est paru en premier sur Les-Tilleuls.coop.

Trouver le talk qui correspond à vos objectifs, savoir qui va briller sur la scène FrankenPHP, caler votre agenda… La billetterie de l’API Platform Conference 2026 ferme dans quelques jours, et on a voulu vous accompagner jusqu’au bout avec un nouvel outil : un assistant IA avec qui échanger directement sur la conférence. On vous raconte ce projet en trois articles : celui-ci pose le contexte général, le second détaille l’architecture, et le troisième revient sur notre choix d’outils souverains. Prêt·es à tester ?

Les prémices du projet

Chaque année, l’API Platform Conference propose à Lille deux jours de programme chargé : des dizaines de conférences sur plusieurs tracks, des intervenant·es venu·es du monde entier, des ateliers, et toute la logistique qui va avec un événement en pleine croissance. Et chaque année, les mêmes questions reviennent côté participant·es : qu’est-ce qui se passe en ce moment, c’est quoi la prochaine conférence en salle 2, qui parle de tel sujet, où sont les stands des partenaires… On a voulu y répondre avec un assistant conversationnel.

La façon évidente de faire, c’est un chatbot classique : une interface, un LLM, un prompt, un accès aux données câblé derrière. C’est d’ailleurs par là qu’on a commencé. Mais en cours de route, une question de conception a fait bifurquer tout le projet, et la réponse s’est révélée beaucoup plus réutilisable qu’une simple fenêtre de chat. C’est ce recadrage qu’on raconte dans cet article, parce que c’est la leçon la plus transposable qu’on en a tirée, et elle ne doit presque rien à la technique.

L’idée de départ vient de techready.live, qui a montré tout ce qu’un bon compagnon d’événement peut apporter aux participant·es. Notre question a été : à quoi ça ressemble, cette expérience, à l’heure des agents IA ?

Une question qui a changé la conception

La question qu’on s’est posée : quand l’assistant doit savoir « quelle est la prochaine conférence en salle 2 », où vit cette connaissance ?

Si la réponse est « dans le chatbot », alors le chatbot, c’est le produit. Et toute autre façon d’accéder à la même info (Claude Desktop, un assistant d’IDE comme Cursor, le bot Slack d’une équipe, le script perso d’un·e collègue) devrait être reconstruite de zéro, avec sa propre copie de l’accès aux données, des règles métier et du prompt. La fenêtre de chat deviendrait à la fois l’interface et le plafond de verre.

On a donc inversé la logique. On a d’abord construit la connaissance de la conférence et les actions possibles pour un·e participant·e comme un service autonome, et traité l’interface de chat comme son premier client et pas comme le produit lui-même. Ce service s’appuie sur le Model Context Protocol (MCP), le standard ouvert pour exposer des outils à des agents IA. Le chat en est un consommateur parmi d’autres ; n’importe quel agent compatible MCP peut en être un autre.

Des capacités, pas des endpoints

Concevoir un serveur MCP, ça change subtilement la manière de penser par rapport à une API REST classique. Au lieu de raisonner en ressources et en endpoints, on raisonne en capacités et en verbes les actions concrètes qu’un·e utilisateur·ice fait vraiment.

Notre serveur s’organise autour des besoins réels d’un·e participant·e pendant l’événement :

• Explorer le programme : lister et rechercher des conférences, récupérer les détails d’une session ou d’un·e intervenant·e, parcourir l’historique d’un·e speaker, lister les catégories et les partenaires, lire les infos générales de l’événement.
• Se repérer dans le temps : savoir ce qui se passe maintenant et ce qui vient ensuite.
• Participer : noter une conférence, laisser un commentaire, lire les retours de la communauté.
• Planifier : ajouter une conférence à son agenda personnel, la retirer, le consulter.

Le projet compte vingt outils au total. Ce qui compte, c’est qu’ils portent des noms d’actions humaines, pas des noms de tables SQL. « Les prochaines conférences », c’est une capacité que n’importe quel·le participant·e comprend ; une query string avec un offset et une limite, c’est de la tuyauterie. Et quand celui qui consomme l’API est un modèle de langage qui doit décider quel outil appeler, c’est ce cadrage sémantique qui l’aide à choisir le bon outil et à lui passer les bons arguments.

La description de l’outil est l’interface

Le plus surprenant dans ce développement, c’est la documentation. Sur une API classique, la doc de référence s’adresse aux développeur·euses et reste, dans les faits, optionnelle : le code marche, que la doc soit bonne ou non. API Platform fait déjà mieux avec une doc OpenAPI générée automatiquement à partir du code, toujours à jour. Mais sur un serveur MCP, la description de chaque outil est lue par le modèle à chaque décision qu’il prend. Ce n’est plus de la documentation sur l’interface, c’est l’interface. Elle décide si l’agent appelle l’outil, et s’il l’appelle correctement.

Une description du genre « Voter pour une conférence » n’apprend quasiment rien au modèle. Voici celle qu’on a fini par écrire pour l’outil de notation :

Rate an API Platform Conference 2026 talk (1–5). Requires a GitHub access token (sent as a Bearer token); one vote per talk per user — voting again updates your rating. Returns the updated feedback.

En trois phrases, le modèle sait quelle plage de notes est valide, qu’une authentification est requise, que revoter met à jour la note au lieu de la dupliquer, et à quoi ressemble la réponse. On a passé plus de temps à écrire et réécrire ces descriptions que sur n’importe quel handler. Sur un projet MCP, ce sont elles qui font la différence entre un projet qui marche et un qui ne marche pas, ça vaut le coup de les traiter comme du vrai prompt engineering.

L’authentification comme frontière produit

L’essentiel du serveur est accessible sans création de compte : lire le programme ne demande rien. Écrire, en revanche : noter une conférence, laisser un commentaire ou se construire un agenda  demande une connexion GitHub. C’est un choix assumé, pas un détail technique : il définit qui a le droit de modifier les données et garde une trace des contributions.

Cette règle est portée par l’outil lui-même, pas par un client en particulier. Un agent qui essaie de voter sans token reçoit une réponse en langage clair lui expliquant qu’une connexion est nécessaire. Notre interface de chat traduit ça par un bouton « Se connecter avec GitHub » ; un autre client le présenterait autrement. Mais la règle vit à un seul endroit, sur le serveur, donc chaque client l’applique sans avoir à la réécrire.

Bring your own agent

Quand le produit est un service et non une appli figée, la distribution change de nature : ce n’est plus un app store, mais un petit bout de configuration. Un·e développeur·euse ajoute quelques lignes à son client IA préféré, et son assistant sait répondre aux questions sur la conférence et enregistrer ses votes. Pareil pour un assistant d’IDE ou un script écrit pour un besoin précis : chaque client accède aux mêmes vingt outils et au même comportement, sans qu’on ait à redévelopper quoi que ce soit de notre côté.

Pour que ce soit concret, on publie une page statique avec des instructions d’installation copier-coller pour les clients les plus courants. Le « bring your own agent », ça ne marche que si ça prend deux minutes à mettre en place.

Notre interface de chat garde toute son utilité : c’est le point d’entrée que la plupart des participant·es utiliseront, et on détaille sa construction dans la Partie 2. Mais ce n’est qu’une porte d’entrée parmi d’autres, pas là où se concentre la valeur du projet.

Retours d’expérience et bonnes pratiques

Quelques principes qui ont tenu la route, et qu’on appliquerait à n’importe quel projet MCP :

• Modéliser le domaine par des verbes. Quand les capacités portent le nom des actions de l’utilisateur·ice, les frontières entre outils se dessinent toutes seules, et le modèle choisit plus fiablement quel outil appeler.
• Traiter les descriptions comme de l’UX. Ça prend du temps à écrire et à tester contre le comportement réel du modèle.
• Préférer la sortie structurée à la prose formatée. Du contenu typé laisse chaque client (bulle de chat, panneau d’IDE, interface vocale) libre de le présenter comme il veut.
• Mettre la logique de contrôle côté serveur. Un client peut oublier l’authentification, les rate limits ou la validation ; le serveur, lui, doit les appliquer systématiquement.
• Voir l’interface comme un client, pas comme le produit. Ça reste utile d’en soigner une, mais ça ne doit pas devenir le seul moyen d’interagir.

Au final, ce qui compte dans ce projet, ce n’est pas tellement la fenêtre de chat qu’on a construite, mais le socle technique sur lequel n’importe quel futur client IA peut venir s’appuyer..

La suite du cheminement

Dans la Partie 2, on rentre dans le détail technique : comment API Platform transforme une ressource en outil MCP avec un seul attribut, comment le mode worker de FrankenPHP garde le serveur actif, et comment les réponses sont streamées jusqu’au navigateur avec Mercure. La Partie 3 montre que toute cette infrastructure peut tourner sur une stack entièrement européenne et open source, inférence comprise. 

Cet article, Comment nous avons créé un assistant IA pour l’API Platform Conference 2026, est paru en premier sur Les-Tilleuls.coop.

Webpack Encore arrive en fin de vie, et Symfony a publié son successeur officiel pour Vite et Rsbuild : Reprise. Le bundle était encore marqué expérimental quand nous avons migré (en 0.7, puis 0.8), mais c'était clairement la direction que prend le framework. Nous avons donc sauté le pas. Et depuis, la 1.0 est sortie, apportant ainsi la même promesse de rétrocompatibilité que Symfony.

Je vais vous raconter dans cet article comment s'est passée cette migration. Nous verrons d'abord ce que fait Reprise et ce qu'implique la migration mécanique, puis les vrais sujets qui nous ont occupés : le contrat implicite que notre base de code avait avec Webpack, une collection de « webpack-ismes » qui ne se révèlent qu'au runtime, et enfin la mise en place du hot reload dans notre stack Docker. Pour vous donner envie de lire jusqu'au bout : le build est passé de 75-100 secondes à une quinzaine de secondes, et nous avons supprimé 583 packages npm au passage 🎉.

Vous avez dit Reprise ?

Contrairement à Encore qui réimplémentait toute la chaîne de build par-dessus Webpack, Reprise ne fournit que la glue Symfony : la génération d'entrypoints.json et de manifest.json, les fonctions Twig reprise_entry_*, et le support du dev server. Tout le reste (Sass, TypeScript, React, code splitting, minification), c'est Vite qui le fait nativement.

La migration mécanique est vite pliée :

composer remove symfony/webpack-encore-bundle
composer require symfony/reprise
yarn add --dev vite @symfony/reprise

Un vite.config.ts par build, encore_entry_script_tags qui devient reprise_entry_script_tags dans les templates, et c'est à peu près tout. Sur le papier, quelques heures de travail.

Le contraste entre les deux configs illustre bien la philosophie. Avant, nous avions 200 lignes d'API chaînée Encore, où chaque capacité du bundler doit être déclarée explicitement :

// webpack.config.js (extrait)
Encore.setOutputPath('web/build/')
    .setPublicPath('/build')
    .addEntry('js/app', './assets/scripts/main.tsx')
    .addStyleEntry('css/app', './assets/styles/main.css')
    // … 6 autres entrées
    .disableSingleRuntimeChunk()
    .enablePostCssLoader()
    .enableReactPreset()
    .enableTypeScriptLoader()
    .autoProvideVariables({ 'bazinga-translator': 'Translator' })
    .addPlugin(new ESLintPlugin())
    .addPlugin(new StylelintPlugin({ /* … */ }))
    .copyFiles([{ from: './assets/images', to: 'images/[path][name].[ext]?[hash:8]' }])
    .configureFilenames({ js: '[name].js?[chunkhash]', /* … */ });

Après ? Une cinquantaine de lignes où Vite fait le gros du travail nativement. TypeScript et React n'ont plus besoin de loader, et les plugins ESLint/Stylelint sont remplacés par les scripts lint déjà présents dans la CI :

// vite.config.ts (extrait)
export default defineConfig(({ mode }) => ({
    build: {
        sourcemap: mode !== 'production',
        rollupOptions: {
            input: {
                'js/app': './assets/scripts/main.tsx',
                'css/app': './assets/styles/main.css',
                // … 6 autres entrées
            },
        },
    },
    plugins: [
        react(),
        tailwindcss(),
        symfony({ outputPath: 'web/build', publicPath: '/build/' }),
        copyStable([{ from: 'assets/images', to: 'images' }], '/build/', 'web/build'),
    ],
}));

Vous remarquez le copyStable sur la dernière ligne ? Il n'est pas fourni par Reprise, et c'est justement le sujet du chapitre suivant. Car comme nous allons le voir, le vrai sujet d'une migration de bundler n'est pas la config du bundler en elle-même.

Le contrat implicite avec Webpack

Vite hashe les noms de fichiers par défaut, c'est son modèle de cache-busting : app.js devient app-B7fAYn0O.js, et le manifest.json fait la correspondance. Sauf que notre projet avait un contrat exactement inverse, invisible tant qu'on ne le cherche pas :

• plus de 300 templates référencent des images en dur, façon asset('/build/images/logo.svg'), sans jamais passer par un manifest ;
• près de 250 templates utilisent un filtre Twig maison |inline qui lit les SVG directement sur le disque pour les inliner dans le HTML ;
• le cache-busting est global, par query string, à partir d'un fichier REVISION produit au déploiement.

Autrement dit, les chemins physiques des fichiers copiés doivent rester stables, et ce depuis des années. Réécrire 300 templates n'était évidemment pas envisageable. De plus, les emails envoyés par l'application utilisent également certains de ces assets (notamment les fonts), ils doivent donc rester disponibles aux mêmes urls.

Reprise proposait bien (en 0.7) une option copy pour remplacer le copyFiles() d'Encore, mais elle hashait systématiquement les noms de fichiers copiés, sans opt-out. Encore laissait choisir son pattern (images/[path][name].[ext]?[hash:8] chez nous : chemin stable sur disque, hash en query string). Notre réponse initiale a tenu en un plugin Vite d'une quarantaine de lignes, qui reproduisait le contrat d'Encore :

// vite-plugin-copy-stable.ts (extrait)
generateBundle(_options, bundle) {
    for (const { file, logicalName } of files(entries)) {
        const source = readFileSync(file);
        const hash = createHash('sha256').update(source).digest('hex').slice(0, 8);
        // Le fichier garde son chemin logique…
        this.emitFile({ type: 'asset', fileName: logicalName, source });
        // … et le hash part dans la valeur du manifest, en query string
        manifestEntries[keyPrefix + logicalName] = `${publicPath}${logicalName}?${hash}`;
    }
    // puis fusion de manifestEntries dans le manifest.json émis par Reprise
}

Résultat : zéro template modifié (hors les 4 layouts de base), le JS et le CSS profitent du hashing natif de Vite via entrypoints.json, et tout le reste garde ses chemins stables.

Ce besoin nous a semblé suffisamment universel pour le proposer upstream : symfony/reprise#81 ajoute une option hash: false par entrée copy, qui reproduit exactement ce contrat. Elle a été mergée et publiée dans Reprise 0.8 quelques jours plus tard : nos quarante lignes de plugin ont disparu au profit d'une ligne de config, avec des arborescences et des manifests strictement identiques.

Les webpack-ismes qui ne se voient qu'au runtime

Une fois le build vert, nous pensions être tirés d'affaires. Mais la CI nous attendait au tournant, avec de nombreux scénarios Behat en échec. Tous les problèmes que je vais lister ici ont le même point commun : le build passe, le typecheck passe, et pourtant le site ne fonctionne plus au runtime.

global n'existe pas

global.Translator = Translator;

Webpack aliasse silencieusement global vers window. Vite, non :

Uncaught ReferenceError: global is not defined

L'erreur survient au top-level du module, donc c'est tout le bundle qui meurt : plus une seule ligne de JS ne s'exécute sur le site. Le plus vicieux : @types/node étant installé, global est parfaitement typé et tsc ne bronche pas. Le fix est trivial (window.Translator = …), encore faut-il savoir que ces assignations existent.

Les require() dynamiques

<ReactSVG src={require(`../../../images/icons/${path}`)} />

Ce pattern repose sur les context modules de Webpack, qui embarquait tout le dossier icons/ pour résoudre l'expression au runtime. Vite ne les implémente pas :

Uncaught ReferenceError: require is not defined

L'exception éclate au premier rendu d'un composant avec icône, et React réagit en démontant tout l'arbre : pages de résultats intégralement vides, sans un message pour l'utilisateur. Nos icônes étant déjà copiées à chemins stables (voir plus haut), une URL directe a suffi : src={/build/images/icons/${path}}.

Les url() CSS qui ne suivent pas

Avec @tailwindcss/postcss, les @import CSS sont inlinés sans rebaser les chemins relatifs. Un url('../../fonts/brand-400.woff2') écrit dans un fichier importé se retrouve tel quel dans le CSS final, se résout depuis la racine et répond 404 : webfonts et images de fond ont disparues.

Le plugin officiel @tailwindcss/vite réécrit ces mêmes URLs vers l'asset émis ( url(/build/brand-400-Dm0XPNJo.woff2)) en plus d'être plus rapide. C'est l'intégration que Tailwind recommande quand on build avec Vite. Le rebasing côté PostCSS a bien été corrigé à plusieurs reprises upstream (voir l'issue #16636, fermée depuis), mais un fichier importé depuis notre propre code nous rejouait toujours le problème en 4.3.3. Je ne peux que vous recommander de ne plus passer par PostCSS si vous utilisez Tailwind v4 avec Vite.

Le fichier vendor en CommonJS

import Routing from '../../../vendor/friendsofsymfony/jsrouting-bundle/Resources/public/js/router.min.js';

Celui-là est retors : il fonctionne en build (le plugin commonjs de Rollup fait l'interop), mais crashe uniquement en dev :

The requested module '…/router.min.js' does not provide an export named 'default'

Vite ne prébundle que node_modules, et sert donc le fichier CJS de vendor/ tel quel à un navigateur qui attend un module ES. La solution est le package npm fos-router, qui est exactement le même que celui packagé dans le bundle Symfony. En prime, le package npm est en typescript : tsc a immédiatement débusqué une dizaine de window.location = url qui dormaient depuis des années (le module vendor étant any, tout ce qui en sortait échappait au typage).

Quand le site dépend d'un bug du bundler

Voici mon anecdote préférée de cette migration. Après le passage à Vite, un test de régression visuelle refusait obstinément de passer : sur une déclinaison du site, le logo s'affichait 60 % trop grand.

Nous avons tout vérifié : le fichier SVG copié, identique ; les règles CSS, identiques et dans le même ordre ; le HTML, identique. En dernier recours, le manifest Webpack de production, qui racontait une drôle d'histoire :

"build/images/logo-pro.svg": "/build/images/logo-pro.e42c1969.svg"

Un hash dans le nom de fichier, là où toutes les autres entrées copiées utilisaient une query string. Et le contenu de ce fichier hashé n'était pas le fichier demandé : c'était un autre SVG du même nom, situé dans un sous-dossier icons/, avec une classe CSS différente, donc une taille différente.

L'explication : les images émises par file-loader (dont tout le dossier icons/, embarqué par le require() dynamique vu plus haut) écrasaient les clés du manifest des fichiers copiés portant le même nom. Depuis des années, le site servait le mauvais fichier à cet endroit, et ce rendu accidentel était devenu la référence, jusque dans nos baselines de screenshots. Notre build Vite, plus propre, servait enfin le bon fichier… et cassait donc le test.

Nous avons audité les 31 collisions de noms du projet (une seule autre était visible) et pointé les templates vers le bon fichier, explicitement. Ce que je retiens de cette histoire, c'est qu'un bundler est avant tout un système de résolution : en changer révèle toutes les résolutions accidentelles dont votre site dépend sans que vous le sachiez.

Un pixel de différence

Toujours côté régressions visuelles : trois baselines ont bougé d'exactement 1 pixel après la migration. Un bouton centré, dont la largeur totale (icône dimensionnée en em + texte) tombe à un demi-pixel près différemment. En cause, le changement de minifieur CSS : cssnano (configuré avec calc: false précisément pour éviter ce genre d'arrondis) a laissé la place à esbuild.

0,01 % des pixels, invisible à l'œil, mais parfaitement reproductible. Le rendu de Vite est déterministe au pixel près d'un run à l'autre : nous avons comparé des captures à deux jours d'écart, zéro pixel de différence.

Corollaire qui vaut pour tous ceux qui font des tests de screenshots : ne régénérez jamais vos baselines sur le dev server. Le CSS non minifié y produit les mêmes écarts d'arrondis face au rendu buildé que compare votre CI, et vous chercherez longtemps pourquoi « ça passe en local ». Chez nous, la task de mise à jour des screenshots rebuild d'office avant de capturer.

Brancher le HMR dans la stack Docker

Le HMR (Hot Module Replacement ou remplacement de module à chaud) est le gain le plus visible de la migration pour les développeurs, et il mérite qu'on s'y attarde. Petite confession d'abord : avec Encore, notre « watch » se contentait d'écrire les fichiers sur le disque, et le vrai dev-server était pensé pour tourner dans Docker pour les PC sous Linux, sur la machine hôte (donc en dehors de Docker) pour les Macs (car ceux de l'époque souffraient trop). Avec Vite, nous voulions le HMR dans la stack, comme tout le reste, et pour tout le monde.

Les problèmes rencontrés

Nous avons eu trois problèmes à résoudre.

Atteindre le serveur depuis le navigateur. Nous avons d'abord sur-conçu la chose : route Traefik dédiée, TLS, service discovery. Puis nous avons retenu une solution bien plus simple, déjà adoptée sur un autre de nos projets : publier le port du conteneur sur l'hôte et servir en http://localhost:5173. Les navigateurs traitent localhost comme une origine sûre, donc pas de mixed content depuis une page HTTPS et zéro certificat à gérer.

Le cycle de vie. Notre premier montage lançait Vite dans un conteneur compose run éphémère. Mauvaise idée : un watch tué laisse un zombie qui squatte le port 5173 et continue d'écraser les fichiers en douce. Nous avons donc plutôt défini un service Compose dédié : up réutilise ou recrée toujours le même conteneur, ce qui rend le zombie impossible.

# docker-compose.dev.yml (extrait)
vite:
    image: "${PROJECT_NAME}-builder"
    command: bash -c "until [ -d node_modules/.bin ]; do sleep 2; done; yarn run ${VITE_SCRIPT:-dev}"
    ports:
        - "127.0.0.1:${PROJECT_VITE_PORT:-5173}:5173"

Le until node_modules n'est pas décoratif : au premier démarrage de la stack, Docker démarre le service avant que yarn install ne soit passé, et on ne veut pas d'un service en crash-loop.

Les pièges du conteneur. Deux classiques à connaître. Le watcher de Vite crawle par défaut tout le projet : avec un vendor/ de 100 000 fichiers, la limite inotify explose. Il faut donc l'exclure explicitement. Et méfiez-vous de vos patterns d'exclusion : notre **/var/**, pensé pour le cache Symfony, matchait /var/www, le dossier de travail du conteneur. Tout le projet était ignoré par le watcher, donc le HMR était inopérant : le serveur tourne, la page se charge, et rien ne se met à jour. Ancrez vos patterns au dossier du projet :

watch: {
    ignored: ['vendor', 'var', 'web'].map((dir) => path.resolve(__dirname, dir, '**')),
},

Dernier raffinement, la cohérence entre les modes : nos tasks de build stoppent le serveur de dev s'il tourne (sinon les pages repassent sur les assets buildés pendant qu'un serveur orphelin continue de tourner pour rien), et la task de watch le démarre. On ne peut ainsi pas se retrouver dans un état intermédiaire sans le savoir.

Et les worktrees ?

Avec l'IA devenant progressivement incontournable pour gagner en efficacité, nous travaillons de plus en plus avec des worktrees git, chacun avec sa stack Docker complète et isolée. C'est une feature native de notre template docker-starter : le nom de projet Compose est suffixé par le worktree, et tous les ports hôtes sont décalés automatiquement, ce qui permet d'avoir plusieurs stacks qui tournent en parallèle.

Le port du serveur Vite rejoint simplement ce mécanisme : chaque worktree a le sien, et deux développements en parallèle ont chacun leur HMR.

Il restait un détail à régler : Symfony génère des URLs d'assets absolues à partir des base_urls configurées, qui ne connaissent pas le port décalé. Dans un worktree, les pages allaient donc chercher leurs assets sur la stack du checkout principal, et on a mis un moment à comprendre pourquoi. Notre solution : un suffixe de port paramétrable dans les base_urls, vide par défaut (et en production) :

# config/packages/framework.yaml
framework:
    assets:
        base_urls:
            - 'https://%http.domain.front%%http.public_port_suffix%'

Et plutôt que de demander à chaque développeur de le renseigner à la main, la task Castor 🦫 qui démarre la stack détecte le worktree et synchronise la valeur dans un fichier parameters_override.yaml local (gitignoré, prévu pour la config personnelle) :

// Extrait de la task, appelée par `castor up`
$line = \sprintf("http.public_port_suffix: ':%d'", get_worktree_ports(get_worktree_name())['https']);
// … créé ou mis à jour dans parameters_override.yaml, sans toucher aux autres clés

Un nouveau worktree est ainsi utilisable en une seule commande, HMR compris.

Ce que nous avons perdu au passage

Pour être complet, voici ce que la migration nous a coûté :

• la minification svgo des images copiées a été abandonnée, à refaire à la source si le poids devient un sujet ;
• ts-loader faisait une analyse statique de code à chaque build, mais Vite ne le fait pas. Nous avons donc ajouté une nouvelle step dans la CI qui lance un yarn tsc --noEmit pour combler le trou (ne l'oubliez pas, c'est un vrai filet qui disparaît sinon) ;
• Reprise était expérimental au moment de la migration, avec une API susceptible de bouger d'une version à l'autre. Ce point s'est réglé tout seul depuis : la 1.0 est sortie et adopte la promesse de rétrocompatibilité de Symfony. Notre montée depuis la 0.8 s'est résumée à changer la contrainte de version, sans une ligne de code à toucher.

Une migration largement déléguée à l'IA

Un dernier point qui vous intéressera peut-être : nous avons laissé une IA faire le gros de cette migration. Pas la décision de migrer ni les choix structurants (le contrat d'assets, le mode de câblage du HMR), mais l'essentiel du travail mécanique et surtout l'itération sur les problèmes rencontrés.

Ce qui a rendu cela possible, ce n'est pas l'IA elle-même, c'est le filet de sécurité qui existait déjà autour du projet : une CI complète avec Behat, PHPUnit et nos tests e2e Playwright avec screenshots. Chaque webpack-isme du chapitre précédent a été détecté par un test, pas par un humain : les 19 scénarios Behat rouges pour le global fantôme, les screenshots pour le logo trop grand ou le pixel de différence, les 404 des fonts dans les captures. À chaque fois, l'IA a pu lire le rapport, reproduire le problème en local, corriger, et relancer la CI, sans que nous ayons à intervenir autrement que pour valider les choix.

Sans cette couverture de tests, la même migration aurait demandé une relecture visuelle de dizaines de pages à chaque itération, et nous n'aurions probablement pas osé déléguer autant. C'est un bon argument, si vous en manquiez, pour investir dans des tests de régression visuelle avant d'entreprendre ce genre de chantier.

Conclusion

Nous avons vu dans cet article que la migration mécanique d'Encore vers Reprise tient en quelques heures, et que le vrai travail se joue ailleurs : dans le contrat implicite que votre base de code entretient avec son bundler, et dans les quelques webpack-ismes qui ne se révèlent qu'au runtime. C'est là qu'il faut chercher si vous devez estimer une telle migration.

Le résultat en vaut la peine : notre build est cinq à six fois plus rapide, nous repassons sur la config par défaut de node avec 1 Go de heap (au lieu des 4 Go nécessaires auparavant), nous avons supprimé 583 packages npm, la config a été divisée par trois, et les développeurs ont enfin un hot reload avec fast-refresh React. En bonus, cela signifie également que le déploiement est également plus rapide de plus d'une minute, c'est appréciable !

Être early adopter d'un bundle expérimental a aussi ses bons côtés : le principal point de friction rencontré a fini en contribution upstream, mergée et publiée en quelques jours. La prochaine équipe qui migrera un site aux chemins d'assets figés aura une option de config là où nous avions initialement écrit un plugin local.

Dans cet article, nous allons voir pourquoi md5() ne peut pas nous aider, comment fonctionne SimHash, comment l'implémenter en PHP sans aucune dépendance, et surtout comment faire tourner la comparaison en base de données quand on a des millions de pages.

Le problème

Le crawler de redirection.io parcourt un site et récupère toutes ses pages. À la fin, on veut prévenir l'utilisateur : ces pages ont le même contenu.

Commençons par le cas facile. Deux pages strictement identiques :

$hashA = md5($contenuA);
$hashB = md5($contenuB);

Mais dans la vraie vie, les pages ne sont jamais strictement identiques. Prenez une boutique en ligne avec une fiche produit déclinée par ville :

Toutes nos paires sont expédiées sous 24 heures depuis notre entrepôt de Lyon.

Toutes nos paires sont expédiées sous 24 heures depuis notre entrepôt de Bordeaux.

Trois cents mots identiques, un seul mot qui change. Pour un moteur de recherche, ce sont des doublons. Pour md5(), ce sont deux pages qui n'ont rien à voir.

Pourquoi les fonctions de hachage habituelles ne nous aident pas

Le premier réflexe serait de se dire que deux contenus proches donnent deux hash proches. Vérifions :

echo md5('Bonjour le monde'), "\n";
echo md5('Bonjour le Monde'), "\n";

9cbfb998c9c4f8966d0df57e0065383a
1dacb65f3f3799ba5643cb3409e3aeec

Une seule lettre change, un m devenu M, et les deux empreintes n'ont plus rien en commun. Ce n'est pas un bug, c'est exactement ce qu'on demande à une fonction de hachage. Ça porte un nom : l'effet avalanche. Changer un seul bit en entrée doit faire basculer, en moyenne, la moitié des bits en sortie.

C'est indispensable en cryptographie et pour les tables de hachage. Pour notre problème, c'est l'inverse de ce qu'on veut.

Il nous faudrait une fonction de hachage qui préserve la ressemblance : deux textes proches doivent produire deux empreintes proches. Ça existe, ça s'appelle du locality sensitive hashing (hachage sensible à la localité), et SimHash en est le représentant le plus connu.

L'algorithme vient d'un article de Moses Charikar publié en 2002. Google l'a popularisé en 2007 dans un papier intitulé « Detecting Near-Duplicates for Web Crawling », où il explique comment dédupliquer 8 milliards de pages avec des empreintes de 64 bits. La méthode a donc été éprouvée.

Le principe : faire voter les morceaux du texte

Imaginez une élection avec 64 questions, chacune n'admettant que deux réponses : oui ou non. Question n°0 : oui ou non ? Question n°1 : oui ou non ? Et ainsi de suite jusqu'à la question n°63.

Les électeurs, ce sont les petits morceaux du texte. Chaque morceau a un avis sur les 64 questions, et cet avis vient de son propre hash : le bit n°0 de son hash est sa réponse à la question n°0, le bit n°12 sa réponse à la question n°12.

On dépouille ensuite question par question. Si les « oui » l'emportent, on note 1, sinon 0. On obtient 64 bits, et c'est l'empreinte du document.

Prenons maintenant un document de 300 mots, donc environ 300 électeurs, et changeons un mot. Seuls 2 ou 3 électeurs changent d'avis. Sur la plupart des questions, la majorité était assez large pour que ces quelques voix ne changent rien au résultat. L'empreinte reste presque la même : un ou deux bits basculent, sur les questions où le vote était serré.

À l'inverse, deux documents qui n'ont rien à voir ont des électeurs complètement différents. Les votes n'ont aucune raison de coïncider, et les deux empreintes diffèrent sur environ la moitié des bits.

La question « ces deux textes se ressemblent-ils ? » devient donc « ces deux entiers de 64 bits diffèrent-ils sur peu de bits ? ». Et ça, une base de données sait le faire très vite.

Étape 1 : découper le texte en shingles

Il faut d'abord fabriquer les électeurs. La solution évidente serait de prendre les mots un par un. C'est une mauvaise idée.

Avec des mots isolés, le document devient un sac de mots et l'ordre disparaît complètement. Ces deux phrases auraient exactement la même empreinte :

le chat mange la souris puis le chien attrape une balle rouge dans le jardin…
attrape balle chat chien dans jardin la le le le mange puis rouge souris une…

Avec des électeurs d'un seul mot, la distance entre ces deux textes est de 0. Ils sont considérés comme identiques, alors que le second n'a aucun sens.

La parade s'appelle un shingle (« bardeau », comme les tuiles d'un toit qui se chevauchent). Au lieu de prendre les mots un par un, on prend des groupes de mots consécutifs, en avançant d'un mot à chaque fois. Avec des shingles de 3 mots, la phrase le chat mange la souris donne :

le chat mange
   chat mange la
        mange la souris

Les groupes se chevauchent, donc l'ordre des mots est capturé : si on mélange les mots, tous les shingles changent. Sur le même test, la distance passe de 0 à 36 bits sur 63. On est passé de « identiques » à « rien à voir », ce qui est bien le résultat attendu.

Voici le code :

use function Symfony\Component\String\u;

function shingles(string $text, int $size = 3): array
{
    $words = u($text)->lower()->collapseWhitespace()->split(' ');

    if (\count($words) < $size) {
        return [];
    }

    $shingles = [];

    for ($i = 0, $max = \count($words) - $size; $i <= $max; ++$i) {
        $shingles[] = u(' ')->join(\array_slice($words, $i, $size))->toString();
    }

    return $shingles;
}

var_dump(shingles('le chat mange la souris'));

array(3) {
  [0] => string(13) "le chat mange"
  [1] => string(13) "chat mange la"
  [2] => string(15) "mange la souris"
}

Deux détails comptent :

• ->lower() évite que « Livraison » et « livraison » soient comptés comme deux électeurs différents ;
• ->collapseWhitespace() normalise les espaces. Sans lui, un simple retour à la ligne dans le HTML suffirait à créer un shingle bidon.

Notez enfin qu'un document de N mots produit N - 2 shingles avec $size = 3. Chaque mot apparaît dans 3 shingles au plus, donc changer un mot ne modifie que 3 électeurs.

Étape 2 : hacher chaque shingle

Chaque shingle doit maintenant produire ses 64 réponses. On lui applique une fonction de hachage classique (ici l'effet avalanche nous arrange : il garantit que deux shingles différents ont des avis indépendants), puis on lit les bits du résultat.

J'utilise xxh3, disponible nativement depuis PHP 8.1. Ce n'est pas une fonction cryptographique, mais on ne cherche pas à se défendre contre un attaquant : on veut une bonne dispersion, et surtout de la vitesse, puisqu'on l'appelle des centaines de fois par page.

$hash = unpack('J', hash('xxh3', 'le chat mange', true))[1];

printf("%064b\n", $hash);

Le troisième argument de hash() à true demande une sortie binaire (8 octets bruts) plutôt qu'hexadécimale. unpack('J', …) interprète ensuite ces 8 octets comme un entier 64 bits non signé, en Big-endian.

1101000100000011111000001000010101011010001111100011111100000011

Voilà les 64 réponses de ce shingle : oui à la question n°0 (le bit le plus à droite vaut 1), oui à la n°1, non à la n°2, etc.

Pourquoi pas hexdec() ?

Le réflexe naturel serait plutôt d'écrire ceci :

$hash = hexdec(hash('xxh3', $shingle)); // ✗ NON

Et ça ne marche pas :

var_dump(hash('xxh3', 'le chat mange'));       // string(16) "d103e0855a3e3f03"
var_dump(hexdec('d103e0855a3e3f03'));         // float(1.5061128442206372E+19)

hexdec() renvoie un float dès que la valeur dépasse PHP_INT_MAX. Or un float sur 64 bits n'a que 53 bits de mantisse : les 11 bits de poids faible sont perdus. Vos électeurs répondent alors n'importe quoi aux 11 dernières questions, et vous passez la soirée à chercher pourquoi l'algorithme marche mal.

Avec unpack('J', …), on récupère un vrai int. Il sera parfois négatif, PHP n'ayant pas d'entiers non signés, mais ce n'est pas grave : c'est la configuration des bits qui nous intéresse, pas la valeur numérique. Et ($hash >> $bit) & 1 lit correctement n'importe quel bit, même quand le nombre est négatif.

Étape 3 : compter les votes

On tient un compteur par question, initialisé à zéro. Chaque électeur qui répond « oui » l'incrémente, chaque « non » le décrémente.

$bits = 63;
$votes = array_fill(0, $bits, 0);

foreach ($shingles as $shingle) {
    $hash = unpack('J', hash('xxh3', $shingle, true))[1];

    for ($bit = 0; $bit < $bits; ++$bit) {
        if (1 === (($hash >> $bit) & 1)) {
            ++$votes[$bit];
        } else {
            --$votes[$bit];
        }
    }
}

Le +1 / -1 n'est pas un détail de style. Si on se contentait de compter les « oui », il faudrait ensuite comparer à la moitié du nombre d'électeurs. Avec +1 / -1, le seuil est simplement zéro : un compteur positif signifie que les « oui » l'emportent. C'est plus simple à écrire et à lire.

C'est aussi ici qu'on pourrait pondérer les électeurs. Rien n'oblige à voter par pas de 1 : on peut donner plus de poids aux shingles rares (à la TF-IDF), ou à ceux qui apparaissent dans un <h1>. C'est la version pondérée de SimHash, et c'est une extension naturelle de ce ++$votes[$bit]. Dans notre cas, le vote uniforme suffisait largement.

Étape 4 : construire l'empreinte

Il ne reste qu'à convertir les compteurs en bits :

$fingerprint = 0;

for ($bit = 0; $bit < $bits; ++$bit) {
    if ($votes[$bit] > 0) {
        $fingerprint |= 1 << $bit;
    }
}

1 << $bit fabrique un masque avec un seul bit à 1, à la position voulue, et le |= l'allume dans l'empreinte. Les compteurs négatifs ou nuls laissent le bit à 0.

La classe complète

Assemblons tout ça. Voici, à quelques détails près, ce qui tourne en production chez nous. Nous n'utilisons pas symfony/string dans la version finale pour des raisons de performances, je m'en suis servi plus haut pour la lisibilité.

<?php

final class SimHash
{
    public function compute(string $content, int $shingleSize = 3, int $bits = 63): ?int
    {
        $words = preg_split('/\s+/', mb_strtolower(trim($content)), -1, PREG_SPLIT_NO_EMPTY);

        if (\count($words) < $shingleSize) {
            return null;
        }

        $votes = array_fill(0, $bits, 0);

        for ($i = 0, $max = \count($words) - $shingleSize; $i <= $max; ++$i) {
            $shingle = implode(' ', \array_slice($words, $i, $shingleSize));

            $hash = unpack('J', hash('xxh3', $shingle, true))[1];

            for ($bit = 0; $bit < $bits; ++$bit) {
                if (1 === (($hash >> $bit) & 1)) {
                    ++$votes[$bit];
                } else {
                    --$votes[$bit];
                }
            }
        }

        $fingerprint = 0;

        for ($bit = 0; $bit < $bits; ++$bit) {
            if ($votes[$bit] > 0) {
                $fingerprint |= 1 << $bit;
            }
        }

        return $fingerprint;
    }
}

Trente lignes, zéro dépendance, un seul int en sortie. On peut le stocker dans une colonne BIGINT et l'oublier.

Le ?int mérite un mot. Si le texte est plus court que la taille d'un shingle, il n'y a aucun électeur, donc pas d'élection, donc pas d'empreinte. On renvoie null plutôt qu'un 0 qui ressemblerait à une vraie valeur et polluerait toutes nos comparaisons.

Comparer deux empreintes : la distance de Hamming

Nous savons fabriquer des empreintes. Reste à mesurer à quel point deux d'entre elles se ressemblent.

La mesure qui nous intéresse est simple : on compte le nombre de bits qui diffèrent. C'est la distance de Hamming.

A     = 1 0 1 1
B     = 1 0 0 1
        ✓ ✓ ✗ ✓   →  distance = 1

Deux opérations suffisent pour la calculer :

• un XOR (^), qui met à 1 exactement les bits où les deux nombres diffèrent ;
• un décompte des bits à 1 du résultat, opération qu'on appelle popcount.

Trois façons de compter des bits en PHP

PHP n'expose pas de popcount natif, contrairement au processeur qui a une instruction dédiée. Il y a donc plusieurs options, et le classement m'a surpris.

// 1. La boucle naïve : on regarde le bit de poids faible, on l'ajoute au total,
//    on décale d'un cran vers la droite, et on recommence jusqu'à épuisement.
function hamming(int $a, int $b): int
{
    $xor = $a ^ $b;
    $distance = 0;

    while (0 !== $xor) {
        $distance += $xor & 1;
        $xor >>= 1;
    }

    return $distance;
}

// 2. Kernighan : $x & ($x - 1) efface le bit à 1 le plus à droite.
//    On ne boucle donc qu'autant de fois qu'il y a de bits à 1.
function hammingKernighan(int $a, int $b): int
{
    $xor = $a ^ $b;
    $distance = 0;

    while (0 !== $xor) {
        $xor &= $xor - 1;
        ++$distance;
    }

    return $distance;
}

// 3. Le tricheur : on délègue tout au moteur.
function hammingSubstr(int $a, int $b): int
{
    return substr_count(decbin($a ^ $b), '1');
}

Sur 200 000 itérations :

Le « tricheur » gagne largement, et c'est logique : les deux autres exécutent leur boucle dans la VM PHP, alors que decbin() et substr_count() sont du C compilé. En PHP, la boucle la plus rapide est celle qu'on n'écrit pas.

Cela dit, dans notre code de production, cette fonction ne sert qu'aux tests unitaires.

Est-ce que ça marche ?

Vérifions sur un cas réaliste. Prenons une fiche produit de 300 mots environ, et fabriquons quatre variantes :

• promo : la même page, avec une phrase de bandeau promotionnel en plus (28 mots) ;
• ville : la même page, où « Lyon » devient « Bordeaux » (1 mot) ;
• femme : la déclinaison femme du produit (4 expressions changées) ;
• autre : une recette de gâteau au chocolat, qui n'a rien à voir.

Voici les distances de Hamming obtenues, sur 63 bits :

Le cas qui nous intéressait au départ, un seul mot de différence sur 300, donne une distance de 2. Pour rappel, md5() aurait donné deux empreintes totalement étrangères l'une à l'autre.

Les variantes plus substantielles, une phrase ajoutée ou une déclinaison produit, se situent entre 5 et 10. Elles se ressemblent, mais moins.

Le document sans rapport est à 27, soit un peu moins de la moitié de 63. C'est la valeur théorique attendue : deux documents indépendants ont une chance sur deux de tomber d'accord sur chaque question. Sur 300 paires de textes aléatoires, la moyenne est de 30,8 bits, avec des valeurs entre 20 et 45.

On obtient donc une grille de lecture assez nette :

Bien choisir ses paramètres

La taille des shingles

C'est un arbitrage entre sensibilité et robustesse. Un shingle de 1 mot ignore complètement l'ordre, nous l'avons vu : deux textes aux mots mélangés donnent une distance de 0. Un shingle de 8 mots est si spécifique que la moindre reformulation fait tout basculer.

3 mots est la valeur qu'on retrouve un peu partout dans la littérature, et c'est ce que nous utilisons. Ça capture les tournures de phrase sans être hypersensible.

La longueur minimale du document

C'est le paramètre qu'on oublie, et c'est le plus important. Reprenons l'élection : à 300 votants le résultat est stable, à 5 votants il bascule dès qu'une personne change d'avis.

Même modification, un mot changé, sur des documents de longueur croissante :

SimHash n'est fiable que sur des textes longs. Sur 20 mots, changer un mot déplace l'empreinte de 8 bits, bien au-delà du seuil que nous allons fixer, alors que les deux textes sont presque identiques. Sur 2 000 mots, la même modification est complètement absorbée.

C'est pour ça que notre code refuse de calculer une empreinte en dessous de 20 mots. En dessous, le résultat est du bruit, et un faux positif dans un rapport SEO coûte plus cher qu'une détection manquée.

Le seuil de décision

Reste à trancher : à partir de quelle distance déclare-t-on un quasi-doublon ?

Nous avons retenu 3, la même valeur que dans le papier de Google. Le tableau plus haut montre pourquoi c'est raisonnable : à 3 bits sur 63, on attrape « un mot a changé » (distance 2) sans attraper « c'est une variante du produit » (distance 5). Et on reste très loin des 31 bits du hasard.

Ce seuil dépend de vos données et de ce que vous préférez rater. Montez-le pour ratisser plus large, descendez-le si les faux positifs vous coûtent cher. C'est un réglage empirique, il faut le mesurer sur votre corpus.

63 bits, pas 64

Vous avez peut-être tiqué sur le $bits = 63 par défaut, alors que je vous parle de 64 bits depuis le début. C'est volontaire :

printf("%d\n", 1 << 62); //  4611686018427387904
printf("%d\n", 1 << 63); // -9223372036854775808  ← aïe

PHP n'a pas d'entiers non signés. Le bit 63 est le bit de signe : l'allumer rend l'empreinte négative. Ça ne casse pas l'algorithme en soi, le XOR et le popcount se moquent du signe, mais ça complique tout le reste de la chaîne :

• le décalage à droite >> propage le bit de signe ;
• la sérialisation JSON devient bizarre ;
• le stockage en base échoue si la colonne est un UNSIGNED BIGINT.

En se limitant aux bits 0 à 62, l'empreinte reste dans [0, PHP_INT_MAX]. Elle rentre sans discussion dans un BIGINT signé, un UInt64 ClickHouse ou un bigint PostgreSQL. On perd un bit sur 64, soit 1,5 % de précision, et on s'épargne toute une catégorie de bugs.

Comparer à l'échelle

Nous savons calculer des empreintes, mais nous n'avons pas encore trouvé les doublons.

Pour trouver toutes les paires de pages proches, il faut comparer toutes les paires. Avec N pages, ça fait N × (N-1) / 2 comparaisons. Sur un crawl de 1 000 pages, c'est 500 000 comparaisons et PHP s'en sort. Sur 100 000 pages, c'est 5 milliards, et c'est mort.

Il n'y a pas non plus d'astuce d'indexation évidente, parce que la distance de Hamming n'est pas un ordre. Deux empreintes voisines peuvent être numériquement très éloignées : il suffit que ce soit le bit de poids fort qui diffère. Un BETWEEN ou un index B-tree classique ne servent à rien.

Notre solution tient en une phrase : on ne le fait pas en PHP. On laisse la base de données s'en charger. Elle sait faire du XOR et du popcount nativement, sur des colonnes entières, en parallèle, sans jamais rapatrier une ligne en mémoire PHP.

Chaque base a sa fonction

Toutes les bases sérieuses savent compter des bits, même MySQL. Il faut juste connaître le nom local de la fonction. Chacune de ces requêtes renvoie exactement les mêmes distances que notre code PHP.

MySQL / MariaDB : BIT_COUNT() fait le popcount, et ^ le XOR.

SELECT a.url, b.url, BIT_COUNT(a.simhash ^ b.simhash) AS distance
FROM page a
JOIN page b ON a.url < b.url
WHERE BIT_COUNT(a.simhash ^ b.simhash) <= 3;

PostgreSQL (14 et plus) : bit_count() existe, mais travaille sur des chaînes de bits, d'où le cast. Attention, le XOR sur les entiers s'écrit # et non ^, qui est l'exponentiation.

SELECT a.url, b.url, bit_count((a.simhash # b.simhash)::bit(64)) AS distance
FROM page a
JOIN page b ON a.url < b.url
WHERE bit_count((a.simhash # b.simhash)::bit(64)) <= 3;

ClickHouse : bitCount() et bitXor(), tout en camelCase.

SELECT a.url, b.url, bitCount(bitXor(a.simhash, b.simhash)) AS distance
FROM page a
JOIN page b ON a.crawlId = b.crawlId
WHERE bitCount(bitXor(a.simhash, b.simhash)) <= 3;

SQLite : c'est le seul de la bande à n'avoir aucun popcount intégré. Il faut enregistrer une fonction utilisateur depuis PHP.

$pdo->sqliteCreateFunction('hamming', static function (int $a, int $b): int {
    return substr_count(decbin($a ^ $b), '1');
}, 2);

Ça fonctionne, mais on repasse par la VM PHP à chaque ligne, et on perd tout l'intérêt de la manœuvre. Pour ce genre de travail, SQLite n'est pas le bon outil.

Ce que nous faisons en production

Chez nous, les données de crawl vivent dans ClickHouse et la détection tourne à la fin du crawl. Le code ressemble à ça :

$sql = <<<'SQL'
    SELECT DISTINCT a.url AS url
    FROM crawl_urls a
    INNER JOIN crawl_urls b ON a.crawlId = b.crawlId
    WHERE
        a.projectId = :projectId
        AND a.crawlId = :crawlId
        AND a.contentSimhash IS NOT NULL
        AND b.contentSimhash IS NOT NULL
        AND a.url != b.url
        AND bitCount(bitXor(a.contentSimhash, b.contentSimhash)) <= :threshold
    SQL;

Trois remarques sur cette requête :

• a.url != b.url évite qu'une page soit son propre doublon. Sa distance à elle-même vaut 0, elle passerait tous les seuils du monde ;
• le IS NOT NULL des deux côtés, c'est notre ?int de tout à l'heure qui revient. Les pages trop courtes n'ont pas d'empreinte, et elles ne doivent pas participer ;
• le SELECT DISTINCT et l'absence de a.url < b.url : ici nous ne cherchons pas les paires, nous voulons marquer les pages concernées d'un drapeau contentNearDuplicated. Chaque page qui a au moins un voisin proche est signalée.

Le garde-fou

Cette requête reste un produit cartésien. ClickHouse est rapide, mais N² finit toujours par gagner. Nous avons donc mis une limite très bête, mais très efficace :

if ($eligibleCount > CrawlConstants::MAX_URLS_FOR_NEAR_DUPLICATE_DETECTION) {
    $this->logger->info('Skipping near-duplicate content detection: too many eligible URLs.', [
        'crawlId' => $crawl->id,
        'eligibleCount' => $eligibleCount,
    ]);

    return;
}

Au-delà de 25 000 pages, nous ne faisons pas la détection de quasi-doublons. C'est un compromis assumé : cette analyse tourne sur le chemin critique de fin de crawl, et il vaut mieux une fonctionnalité absente qu'un crawl qui ne se termine jamais. La détection de doublons exacts, elle, n'est qu'un GROUP BY : elle continue de tourner quel que soit le volume.

Aller plus loin : le principe des tiroirs

Et si 25 000 pages ne suffisaient pas ? Il existe une astuce, décrite dans le papier de Google, qui permet d'indexer les recherches par distance de Hamming.

Le principe des tiroirs dit que si vous rangez 3 chaussettes dans 4 tiroirs, au moins un tiroir est forcément vide.

Appliquons-le. On découpe nos 63 bits en 4 blocs. Si deux empreintes diffèrent d'au plus 3 bits, alors ces 3 bits se répartissent dans au plus 3 blocs, donc au moins un bloc est strictement identique entre les deux empreintes. Et un bloc identique, un index B-tree classique sait le trouver instantanément.

On stocke donc les 4 blocs dans 4 colonnes indexées :

CREATE TABLE page (
    url     text,
    simhash bigint,
    b0 int GENERATED ALWAYS AS ((simhash >> 48) & 32767) STORED,
    b1 int GENERATED ALWAYS AS ((simhash >> 32) & 65535) STORED,
    b2 int GENERATED ALWAYS AS ((simhash >> 16) & 65535) STORED,
    b3 int GENERATED ALWAYS AS (simhash & 65535) STORED
);

CREATE INDEX ON page (b0);
CREATE INDEX ON page (b1);
CREATE INDEX ON page (b2);
CREATE INDEX ON page (b3);

La recherche se fait ensuite en deux temps : un filtrage par index pour récupérer une poignée de candidats, puis une vérification exacte sur ce petit paquet.

SELECT p.url, bit_count((p.simhash # :target)::bit(64)) AS distance
FROM page p
WHERE (
       p.b0 = (:target >> 48) & 32767
    OR p.b1 = (:target >> 32) & 65535
    OR p.b2 = (:target >> 16) & 65535
    OR p.b3 = :target & 65535
  )
  AND bit_count((p.simhash # :target)::bit(64)) <= 3;

Le WHERE avec les OR passe par les index et ne remonte qu'un nombre réduit de lignes. La dernière condition, coûteuse, ne s'applique plus qu'à ces candidats. On est passé d'un balayage complet à une recherche indexée.

Un point mérite d'être souligné : ce filtrage n'a aucun faux négatif. Ce n'est pas une heuristique, c'est une garantie mathématique. Toute paire à distance ≤ 3 partage forcément au moins un bloc. Sur 25 000 paires d'empreintes générées à distance ≤ 3, les 25 000 partagent au moins un bloc identique.

En contrepartie, la méthode ne marche que pour le seuil pour lequel on l'a dimensionnée. Pour un seuil de 3 il faut 4 blocs, pour un seuil de 7 il en faudrait 8, avec 8 index. Le coût en stockage et en écriture grimpe vite. C'est le genre d'optimisation qu'on met en place quand on l'a mesurée nécessaire, pas avant.

Ce que SimHash ne sait pas faire

Il y a des limites, autant les connaître :

• Ce n'est pas une mesure de similarité fine. SimHash répond « proche » ou « pas proche », pas « similaire à 73 % ». La distance de Hamming approxime la similarité cosinus, mais l'approximation est grossière dans les valeurs intermédiaires. Si vous avez besoin d'un vrai score, il vous faut autre chose ;
• Ça ne comprend rien au sens. Deux textes qui disent la même chose avec des mots différents auront des empreintes sans rapport. SimHash compare des suites de mots, pas des idées. Pour de la similarité sémantique, il faut regarder du côté des embeddings vectoriels, avec un autre budget ;
• Ce n'est pas cryptographique. SimHash est conçu pour que des entrées proches donnent des sorties proches, c'est-à-dire l'inverse des propriétés qu'on attend d'une fonction de hachage sécurisée. Fabriquer une collision est trivial. Ne l'utilisez jamais pour de la sécurité.

Il existe enfin une alternative sérieuse : MinHash, qui approxime la similarité de Jaccard plutôt que la similarité cosinus. Elle donne un score plus exploitable, mais elle demande de stocker plusieurs dizaines de valeurs par document, là où SimHash tient dans un seul entier. Pour poser un drapeau booléen sur des pages web, l'entier unique gagne largement.

Conclusion

SimHash tient en une idée : faire voter les morceaux d'un document, bit par bit. Quelques électeurs qui changent d'avis ne renversent pas le scrutin, donc deux textes proches produisent deux empreintes proches. Le problème du « contenu presque identique » se ramène alors à compter des bits qui diffèrent.

C'est cette réduction qui rend la chose utilisable. Un document devient un BIGINT. La question « ces pages se ressemblent-elles ? » devient BIT_COUNT(a ^ b) <= 3, une expression que MySQL, PostgreSQL et ClickHouse évaluent nativement, sans jamais remonter une ligne jusqu'à PHP.

Chez nous, ça représente trente lignes de PHP à l'écriture, une requête SQL à la lecture, et un garde-fou à 25 000 URL pour dormir tranquille. Ce n'est ni sophistiqué ni parfait, mais ça fonctionne, ça se relit, et ça détecte effectivement les fiches produit qui ne diffèrent que par le nom d'une ville.

Un algorithme de 2002 qui fait toujours le travail. Pas mal non ?

Nous avons récemment corrigé un problème de lenteur sur une application Symfony en production. Le diagnostic nous a pris un certain temps, car la cause était contre-intuitive : le responsable était le composant Cache de Symfony, ou plus précisément sa protection contre le cache stampede, un mécanisme que nous ne connaissions pas vraiment avant cet épisode.

Comme il est peu documenté et qu'il peut concerner beaucoup d'applications, voici le détail du problème, la démarche de diagnostic, et le correctif que nous avons retenu.

Le symptôme : une médiathèque très lente

Sur cette application, la médiathèque de l'admin est propulsée par JoliMediaBundle. Depuis quelque temps, son affichage était devenu très lent : à l'ouverture d'un dossier de médias, le premier affichage prenait entre 10 et 20 secondes de TTFB (Time To First Byte), parfois davantage. Les circonstances de cette lenteur étaient assez curieuses :

• la première visite d'un dossier était lente, mais les visites suivantes étaient instantanées ;
• l'environnement de préproduction, pourtant identique (même code, même configuration, même stockage), était parfaitement fluide ;
• sans lien apparent, d'autres parties de l'application souffraient de lenteurs aléatoires : un même endpoint d'API répondait tantôt en 100 ms, tantôt en 5 secondes.

Un problème qui ne se reproduit ni en local ni en préproduction, et qui frappe au hasard : le diagnostic s'annonçait laborieux 😅

Les fausses pistes

Une médiathèque lente, des fichiers sur un montage réseau : le suspect naturel, c'est le stockage. C'est donc par là que j'ai commencé : vérification des options de montage, mesure des I/O, benchmark de lecture ou d'écriture des fichiers... tout allait bien de ce côté.

Au passage, ce n'est d'ailleurs pas si surprenant : JoliMediaBundle est conçu pour rester performant même lorsque le stockage est lent. Les variations d'images sont pré-générées, les métadonnées sont mises en cache, et les pages d'admin ne déclenchent pas de traitement d'image à la volée. Il faut chercher ailleurs.

Deuxième piste : les endpoints d'API aléatoirement lents. L'un d'eux passe par un transformer qui agrège des données coûteuses à calculer - données mises en cache applicatif pour éviter de refaire le calcul à chaque requête. Persuadés que les requêtes SQL sous-jacentes étaient le goulot d'étranglement, nous avons ouvert plusieurs pull requests pour les optimiser : index, réécriture de requêtes, réduction du nombre d'allers-retours...

Résultat : des requêtes plus propres, mais aucune amélioration mesurable en production. L'endpoint continuait de mettre parfois 5, voire 10 secondes à répondre. Quand une optimisation SQL ne change rien, c'est souvent que le temps n'est pas passé dans le SQL.

Profiler plutôt que supposer

Après ces deux échecs, on a fait ce que nous aurions dû faire dès le début : profiler les transactions lentes en production, plutôt que d'empiler les hypothèses. Sur une trace de la médiathèque, une ligne écrasait toutes les autres :

Symfony\Component\Cache\LockRegistry::compute - 14,8 secondes de self-time

14,8 secondes passées non pas à calculer quoi que ce soit, mais à attendre un flock(). L'application ne passe pas son temps à lire des fichiers ni à exécuter des requêtes, elle attend qu'un verrou posé par le composant Cache de Symfony se libère. Le cache, ce composant que l'on ajoute précisément pour aller plus vite, est donc d'un coup devenu notre goulot d'étranglement... Oups !

Il est temps d'aller lire son code pour comprendre ce qui se passe dans une $cache->get().

LockRegistry, la protection anti-stampede de Symfony

Avant ce debugging, je n'étais pas vraiment familier de cette classe et ne savais pas précisément ce qui se passe lorsqu'on écrit ce code pourtant banal :

$value = $this->cache->get('my_key', function (ItemInterface $item): array {
    $item->expiresAfter(3600);

    return $this->computeSomethingExpensive();
});

Imaginez une clé de cache très demandée qui expire. Au moment de l'expiration, toutes les requêtes en cours constatent simultanément le cache miss, et toutes lancent le recalcul de la valeur en parallèle. Si le calcul est coûteux (une grosse requête SQL, un appel d'API externe...), des dizaines de processus exécutent alors le même calcul au même moment, et saturent la base de données ou le service distant. C'est le cache stampede (la ruée vers le cache), et c'est un vrai problème.

Heureusement, Symfony propose contre ce phénomène deux protections complémentaires:

1. l'expiration probabiliste anticipée (le paramètre "$beta" de CacheInterface::get()) : ce paramètre permet de moduler la probabilité qu'une clé de cache soit re-calculée en avance, même si elle n'est pas encore expirée. Plus une valeur approche de sa date d'expiration, plus il devient probable qu'une requête la recalcule avant l'expiration, ce qui lisse les recalculs dans le temps et évite que tous les recalculs soient groupés à heure fixe ;
2. le LockRegistry : au moment de recalculer une valeur, un verrou est posé pour que le premier arrivé calcule pendant que les autres attendent le résultat, plutôt que de tous calculer chacun de leur côté. Ainsi, si deux requêtes HTTP nécessitent le recalcul de la clé de cache "foo", la première qui arrive pose un verrou et lance le calcul, tandis que la seconde attend que le verrou se libère pour lire la valeur recalculée. Le recalcul n'est donc effectué qu'une seule fois.

Le principe est sain. C'est son implémentation qu'il faut connaître pour comprendre notre problème.

Des verrous posés sur... les fichiers du vendor

Comment poser un verrou partagé entre tous les processus PHP d'une machine (et oui... si un worker et une requête HTTP sont tous deux susceptibles de recalculer une clé de cache, il faut trouver un moyen de partager les verrous entre ces processus), sans dépendre d'un service externe ? La réponse apportée par la classe LockRegistry est astucieuse : en posant des flock() sur des fichiers dont on est sûr qu'ils existent sur toutes les installations... les fichiers PHP du composant Cache lui-même !

// vendor/symfony/cache/LockRegistry.php
private static array $files = [
    __DIR__.\DIRECTORY_SEPARATOR.'Adapter'.\DIRECTORY_SEPARATOR.'AbstractAdapter.php',
    __DIR__.\DIRECTORY_SEPARATOR.'Adapter'.\DIRECTORY_SEPARATOR.'AbstractTagAwareAdapter.php',
    __DIR__.\DIRECTORY_SEPARATOR.'Adapter'.\DIRECTORY_SEPARATOR.'AdapterInterface.php',
    // ... la liste des fichiers du dossier Adapter/ du composant, soit 24 fichiers actuellement
];

Chaque clé de cache est affectée à l'un de ces fichiers par un modulo sur son hash :

$key = self::$files ? abs(crc32($item->getKey())) % \count(self::$files) : -1;

Il faut bien mesurer ce que cela implique :

• il n'existe que 24 "slots" de verrous pour toute la machine ;
• ces slots sont partagés par toutes les clés de cache, tous les pools (le pool Redis de vos données métier, le pool système, ceux de vos bundles...), et tous les processus PHP de l'hôte - php-fpm comme CLI ;
• deux clés qui n'ont rien à voir l'une avec l'autre peuvent tomber sur le même slot, par simple collision de crc32() % 24.

Autrement dit : quand un processus recalcule une valeur, il tient un verrou que n'importe quel autre recalcul, de n'importe quelle autre clé de la machine, a environ une chance sur 24 de devoir attendre. Si le calcul dure quelques millisecondes, personne ne le remarque. S'il dure plusieurs secondes, tout le monde peut le payer.

Ce mécanisme explique au passage l'un de nos symptômes : la médiathèque était rapide en revisite parce que le verrou n'est pris qu'au moment de recalculer une valeur. Tant que la clé est chaude dans le cache, aucun verrou n'est sollicité. Seuls les cache miss paient l'addition.

À l'assaut des coupables : des workers de calculs coûteux

Reste maintenant à comprendre qui monopolise ces verrous. Sur notre application, les serveurs frontaux ne font pas que servir du HTTP : ils font aussi tourner les workers "Messenger" - une dizaine de processus par machine, qui consomment des messages en continu. Parmi ces messages, certains déclenchent des résolutions DNS effectuées en PHP, dont les résultats sont mis en cache applicatif avec un TTL de 120 secondes, pour éviter de solliciter inutilement les serveurs de noms. Le traitement de certains messages peut même nécessiter plusieurs résolutions DNS, et donc plusieurs accès au cache.

Faisons le calcul :

• une résolution DNS peut être lente : plusieurs requêtes en série vers plusieurs serveurs de noms, avec des timeouts qui se cumulent - le callback de cache peut durer plusieurs secondes ;
• un TTL de 120 secondes sur des milliers de domaines vérifiés en continu, cela signifie des recalculs permanents ;
• 10 workers par machine qui enchaînent ces recalculs, cela signifie qu'à tout instant, une bonne partie des 24 slots de LockRegistry est tenue par un worker en train d'attendre une réponse DNS.

Pendant ce temps, côté php-fpm, une requête d'admin arrive : la médiathèque doit calculer les métadonnées d'un dossier froid, appelle $cache->get(), tombe par collision sur un slot tenu par un worker... et attend. Parfois quelques centaines de millisecondes, parfois 15 secondes. Pire encore, il peut très bien arriver que, pour un lock donné, plusieurs "perdants" s'accumulent derrière le verrou, chacun attendant que le précédent libère le slot. Le TTFB de la médiathèque devient alors très variable, pouvant même parfois mener à des timeouts côté navigateur.

Pour vérifier cette hypothèse, nous avons simplement arrêté les workers concernés sur les trois frontaux : la médiathèque est instantanément redevenue rapide 🎉

Oui, les workers CLI utilisent LockRegistry

En lisant le code du composant, on pourrait croire que la protection anti-stampede est désactivée en CLI : la méthode setCallbackWrapper() de ContractsTrait contient un opt-out explicite lorsque PHP_SAPI vaut cli, les processus CLI étant supposés courts et peu concurrents.

Mais cet opt-out ne fonctionne que sur les branches 4.4 et 5.4. Depuis la branche 6.0, le passage aux propriétés typées) a ajouté directement dans doGet() une initialisation de $this->callbackWrapper ??= LockRegistry::compute(...);, et lors du merge de 5.4 dans 6.0, cette ligne a été conservée. Depuis Symfony 6.0, le wrapper est donc systématiquement initialisé à LockRegistry::compute() lors de doGet(), rendant ainsi inopérant l'opt-out pour le CLI. Les workers Messenger, processus CLI de longue durée, utilisent donc bien les mêmes verrous flock() que php-fpm... Et c'est exactement ce qui pose souci dans notre configuration.

Isoler les callbacks lents tout en conservant des locks

Évidemment, on ne va pas désactiver la protection anti-stampede de Symfony car elle est très utile. Elle fonctionne très bien pour protéger de race conditions lors de recalculs rapides. Le vrai problème, c'est le mélange des genres : des callbacks qui durent plusieurs secondes ne devraient pas partager leurs verrous avec le reste de l'application.

L'approche que nous avons choisie consiste donc à doter les callbacks lents, peu critiques, de leur propre pool de cache, avec leur propre stratégie de verrouillage. Le reste de l'application continue de bénéficier de LockRegistry pour des callbacks rapides.

Un pool dédié

Premier ingrédient du correctif : un pool de cache spécifique pour le résolveur DNS - même serveur Redis que le pool partagé, mais un adapter distinct :

# config/packages/cache.yaml
framework:
    cache:
        pools:
            dns.cache:
                adapter: cache.adapter.redis
                provider: 'redis://%env(REDIS_HOST)%'

Le service consommateur cible explicitement ce pool grâce à l'attribut #[Target] :

final readonly class DnsResolver
{
    public function __construct(
        #[Target('dns.cache')]
        private CacheInterface $cache,
        ...
    ) {
    }
}

Remplacer LockRegistry par un verrouillage basé sur les clés

Second ingrédient : remplacer, sur ce pool uniquement, la stratégie de LockRegistry par un verrouillage par clé de cache, en s'appuyant sur le composant Lock et un store Redis. Deux résolutions DNS de domaines différents peuvent ainsi se calculer en parallèle sans se gêner, et surtout sans gêner personne d'autre.

Les adapters de cache de Symfony exposent le point d'extension qu'il nous faut : AbstractAdapter::setCallbackWrapper(), qui permet de substituer son propre callable à LockRegistry::compute(). Notre wrapper en reproduit la sémantique :

final readonly class DnsCacheStampedeProtection
{
    private const int RETRY_DELAY_US = 100_000;

    public function __construct(
        private LockFactory $lockFactory,
        private float $lockTtl = 30.0,
        private float $maxWait = 10.0,
    ) {
    }

    public function __invoke(callable $callback, ItemInterface $item, bool &$save, CacheInterface&CacheItemPoolInterface $pool, \Closure $setMetadata, ?LoggerInterface $logger = null, ?float $beta = null): mixed
    {
        $lock = $this->lockFactory->createLock('dns-cache:' . $item->getKey(), $this->lockTtl);
        $deadline = microtime(true) + $this->maxWait;

        while (true) {
            if ($lock->acquire()) {
                // nous avons gagné la course : on calcule, on sauve, on libère
                try {
                    $value = $callback($item, $save);

                    if ($save) {
                        $setMetadata($item);
                        $pool->save($item->set($value));
                        $save = false;
                    }

                    return $value;
                } finally {
                    $lock->release();
                }
            }

            // quelqu'un d'autre calcule cette clé : on attend un peu, puis on
            // tente de relire la valeur qu'il a sauvegardée (avec beta = 0,
            // pour ne pas déclencher d'expiration anticipée)
            usleep(self::RETRY_DELAY_US);

            // ... relecture du pool, et calcul sans verrou si le délai
            // d'attente maximal est dépassé : le verrouillage ne doit
            // jamais empêcher d'obtenir une valeur
        }
    }
}

L'extrait ci-dessus est abrégé ; la version complète gère la relecture du pool avec beta = 0, le timeout d'attente et un mode dégradé : si le store de verrous est injoignable ou si l'attente dépasse $maxWait, on calcule sans verrou. Une protection anti-stampede qui empêcherait l'application de fonctionner serait en effet un remède pire que le mal.

Une compiler pass pour installer ce wrapper

Reste à "brancher" ce wrapper sur le pool. Petit piège d'intégration : en environnement de dev, le profiler de Symfony décore chaque pool d'un TraceableAdapter, qui n'expose pas setCallbackWrapper(). Un appel effectué à l'exécution sur le service injecté échouerait donc en dev. La solution consiste à passer par une compiler pass, qui ajoute l'appel de méthode sur la définition du service - la CacheCollectorPass de Symfony sait ensuite déplacer ces appels sur l'adapter interne lorsqu'elle installe sa décoration :

final readonly class DnsCachePoolPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        $container->getDefinition('dns.cache')
            ->addMethodCall('setCallbackWrapper', [new Reference(DnsCacheStampedeProtection::class)])
        ;
    }
}

Et c'est tout : le reste de l'application n'a pas bougé d'une ligne, et continue de bénéficier de LockRegistry pour ses callbacks rapides. On aurait peut-être aussi pu jouer avec la priorité du décorateur, mais cette solution n'a pas été explorée.

Une autre approche : agrandir le pool de verrous

Maintenant que nous avons isolé les callbacks lents, la situation est déjà bien plus saine. Cela dit, on peut quand même considérer que la limitation à seulement 24 fichiers de lock, c'est finalement assez peu, surtout si ça peut suffire à provoquer des collisions entre clés de cache qui n'ont rien à voir les une avec les autres.

Nous avons donc choisi d'agrandir le nombre des verrous disponibles, afin que, pour les pools qui emploient encore LockRegistry, le risque de collision et d'attente indue soit restreint.

En effet, rien n'oblige à se limiter aux 24 fichiers du vendor. Par exemple, on peut choisir de générer, au moment du déploiement, un dossier contenant un millier de fichiers immutables, qui seront utilisés par LockRegistry comme "supports" des appels à flock() pour diluer fortement la probabilité de collision.

L'appel doit être fait le plus tôt possible (en tout cas avant le premier $cache->get()) ; Kernel::boot() est un bon candidat, puisqu'il couvre à la fois les entrées HTTP et les processus CLI :

// src/Kernel.php
use Symfony\Component\Cache\LockRegistry;

class Kernel extends BaseKernel
{
    public function boot(): void
    {
        parent::boot();

        // 1000 fichiers immutables créés au déploiement
        LockRegistry::setFiles(glob($this->getProjectDir() . '/var/cache-locks/*.lock'));
    }
}

C'est simple et efficace pour réduire les collisions, mais cela ne fait que repousser le problème : tant que des callbacks de plusieurs secondes cohabitent avec le trafic web dans le même mécanisme de verrouillage, la contention finira par revenir.

En conclusion

Après déploiement du correctif, la médiathèque est redevenue fluide, y compris à la première visite d'un dossier - les 10 à 22 secondes de TTFB ont disparu, et les différents endpoints d'API aléatoirement lents se sont "assagi". Sur l'un d'eux, qui utilise le cache dans un transformer, le premier appel "froid" est ainsi passé de 5 secondes à 50 millisecondes sans avoir besoin de toucher ni au SQL ni au code métier, mais uniquement en cessant d'attendre derrière des résolutions DNS qui ne nous concernaient pas.

Au final, il y a quelques bonnes leçons à tirer de cette expérience. D'abord, mettre en cache, ce n'est pas une opération gratuite. On a tendance à considérer $cache->get() comme un réflexe sans risque : "au pire, ça ne servira à rien, et au mieux, ça accélèrera les choses". Ce n'est pas tout à fait vrai :

• dès lors qu'une protection anti-stampede entre en jeu, chaque recalcul de valeur interagit avec un système de verrous partagé, et un callback lent peut pénaliser des parties de l'application qui n'ont rien à voir avec lui. Avant de mettre en cache un calcul, posez-vous la question : combien de temps dure-t-il, au pire ?
• et au-delà de cette considération, nous sommes assez partisans de l'approche "moins de code = moins de bugs" : si on n'a pas strictement besoin de cache, autant s'en passer !

Exécuter des workers (asynchrones) sur les mêmes machines que des services web (synchrones) amplifie le problème. Même si c'est une pratique économique et courante, cela pose des soucis car LockRegistry raisonne par machine : des workers qui recalculent en continu des valeurs coûteuses partagent par défaut leurs 24 slots de verrous avec les requêtes web.. Et ça peut nous réserver de (mauvaises) surprises !

Le profiling a bien aidé pour comprendre ce problème. L'attente d'un flock() est invisible dans les métriques classiques : le niveau du CPU reste bas, les requêtes SQL sont rapides, les logs sont muets. En gros, on a l'impression que tout va bien..! Si nous n'avions pas eu sous la main une trace qui montre où le temps s'écoule réellement, nous chercherions encore. Peu importe l'outil utilisé pour profiler - Blackfire 💛, Sentry, ou tout autre outil capable d'afficher le temps passé fonction par fonction : l'important est d'en avoir un en production, et de le consulter avant de formuler des hypothèses.

Enfin, une approche défensive consiste à toujours isoler les callbacks lents dans des pools dédiés, avec un mécanisme de lock construit sur mesure. C'est la leçon la plus actionnable : si certains de vos callbacks de cache sont structurellement lents (appels réseau, calculs lourds), donnez-leur leur propre pool et une stratégie de verrouillage par clé. Quelques dizaines de lignes de code suffisent, et le reste de votre application vous dira merci!

D'où je viens

Ce qui suit est mon parcours, pas une histoire de PHP. D'autres ont vécu ces mêmes années très différemment.

Mon histoire commence en 2013, quand PHP n'était pas le choix évident qu'il allait devenir, donc j'ai appris le C : pointeurs, gestion mémoire manuelle, segfaults. Ensuite je suis passé à l'Objective-C pour du développement iPad, avec un peu de Smalltalk à côté, pour maintenir un vieux site interne.

Pendant cette période, je suis tombé amoureux du web. J'ai rejoint une entreprise qui faisait du PHP, un langage complètement nouveau pour moi. La stack là-bas, c'était PHP 5.x, pas d'autoloading, presque aucune librairie, et pas de framework. Composer et Symfony existaient déjà, on ne les utilisait simplement pas. Chaque projet démarrait de zéro, et on réinventait beaucoup de roues. C'était plus dur, oui, mais c'était comme ça chez nous.

Puis j'ai déménagé à Paris, et c'est là que j'ai découvert les frameworks. Laravel et Symfony faisaient tous les deux du bruit, et j'ai commencé par Laravel. D'un coup, une communauté entière avait déjà résolu les problèmes que je résolvais seul. Pour moi, les frameworks n'étaient pas juste des outils, c'était un multiplicateur.

J'ai fini par passer à Symfony, que j'utilise et que j'aime toujours aujourd'hui. Tout ce dont vous avez besoin est faisable avec, et même plus.

Avec le recul, un motif se répète : j'ai suivi là où la technique m'emmenait. Chaque époque a changé l'unité de mon travail : des lignes de C, aux librairies, aux frameworks. Cet article parle de ce que je pense être l'étape suivante, celle qu'on est en train de vivre.

La vague des LLM

Pendant des années, les frameworks ont eu l'air d'être le bout de la route. Puis un nouveau type d'outillage est apparu.

La première vague est arrivée en 2021, avec GitHub Copilot : de l'auto-complétion sous stéroïdes. Vous commenciez une ligne, la machine la finissait. Ça semblait magique. En 2023, Cursor a relevé le niveau : toujours de l'auto-complétion de notre code, mais avec beaucoup plus de choses intégrées, comme discuter avec sa codebase, faire des éditions inline, et écrire des blocs entiers de code depuis une simple instruction. Et depuis 2025, Claude Code a pris la tête sur les agents IA, avec des modèles capables de livrer des features complètes tout seuls.

La progression est claire : d'abord un outil qui complétait notre code plus vite, puis un outil qui en écrivait une partie pour nous, et maintenant des agents qui construisent des features entières. L'unité de travail a encore changé : des frameworks aux features.

Cette vague n'est pas restée entre les mains de quelques gros acteurs. La concurrence a explosé, et les modèles open-weight ont rejoint la course : DeepSeek, en particulier, a secoué le monde de l'IA en délivrant des performances de niveau frontier pour une fraction du coût, et il était loin d'être seul. Pour nous, développeurs, ça a changé la question de l'accès : les modèles puissants ne sont plus enfermés chez un seul fournisseur. Vous pouvez choisir le modèle qui correspond à chaque tâche, mélanger les fournisseurs dans le même workflow, ou faire tourner des modèles plus petits sur votre propre machine avec des outils comme Ollama.

Chacune de ces vagues a redéfini une partie de notre métier. Mais à mon avis, ce n'était que le lever de rideau : le vrai changement n'est pas l'agent en lui-même, c'est l'environnement dans lequel on le fait tourner.

Entrée en scène de l'ADE

Le premier indice est venu de Cursor lui-même. Avec Cursor 2.0, il s'est mis à cacher les choses qu'on croyait essentielles : l'arborescence de fichiers, le panneau git, l'éditeur au centre. Ce qui restait, c'était une conversation avec un agent. Sans le nommer, c'est ça un ADE : un Agent Development Environment. Là où un IDE est construit autour de vous en train d'éditer des fichiers, un ADE est construit autour de vous en train de diriger des agents, et de discuter avec eux pour construire des produits.

Le nom est nouveau et pas encore très répandu, mais je l'aime bien, justement parce qu'il trace une ligne claire entre la façon dont on développe aujourd'hui avec des IDE et ce qui arrive ensuite.

Après Cursor, Jean est allé loin dans le paradigme ADE. Le raisonnement est simple : si les agents travaillent pour vous, vous devriez pouvoir lancer plusieurs tâches en même temps. Jean embarque donc une gestion native des git worktrees : chaque tâche vit dans sa propre copie isolée du dépôt. Combiné à l'intégration des pull requests et des issues GitHub, vous pouvez prendre une issue, obtenir un worktree tout neuf, et avoir un agent qui travaille dessus en quelques secondes.

Puis un collègue m'a parlé d'Orca. Il fait tout ce que fait Jean, avec encore plus d'intégrations : Jira et Linear sont supportés nativement, donc pendant que je travaille sur quelque chose je peux attraper une issue et créer immédiatement un worktree pour l'attaquer. Chaque tâche a son propre terminal, son navigateur et son contexte, et c'est du bring-your-own-subscription : Claude Code, Codex, OpenCode et les autres, côte à côte.

Rien de la vague des agents n'est perdu en route non plus. Agents, commands, skills : tout ce qu'on a construit se transpose. Un ADE ne remplace pas cette boîte à outils, il se pose par-dessus, et ça ne fait que la renforcer.

C'est pour ça qu'un ADE, ce n'est pas « un IDE avec un panneau IA greffé dessus ». Les primitives sont différentes : pas des fichiers et des buffers, mais des tâches, des worktrees et des agents. L'IDE partait du principe d'un développeur, une copie de travail, un fil de travail. L'ADE part du principe que vous en orchestrez plusieurs à la fois.

Mon setup au quotidien

Un avertissement avant de plonger : mon agent CLI principal est OpenCode, donc tous les exemples de cette section tournent autour de lui. Mais rien ici n'est spécifique à OpenCode : la plupart de ces astuces se transposent directement à Claude Code, Codex, ou l'agent que vous préférez.

Orca lui-même

Orca embarque beaucoup de features pensées pour vous simplifier la vie, et la première c'est l'intégration avec les outils de suivi d'issues : GitHub issues, Jira et Linear sont tous supportés. De là, vous pouvez prendre une nouvelle issue ou consulter celles sur lesquelles vous travaillez déjà, lire tous les détails, et créer un worktree directement depuis l'issue. Quand vous faites ça, le prompt par défaut est le lien de l'issue (ça va beaucoup nous servir plus loin, gardez le en tête).

Quand vous jonglez avec plusieurs features ou issues en même temps, chacune dans son worktree, il devient vite difficile de se souvenir de ce qu'il reste à faire sur laquelle. C'est pour ça qu'Orca vous donne un kanban board. Chaque colonne est entièrement personnalisable ; dans mon cas j'en ai quatre :

• « Todo » contient les features et les issues à traiter ;
• « Waiting » est pour les tâches bloquées où j'ai besoin d'un retour de la personne liée à l'issue ;
• « In progress » est ce sur quoi je travaille activement ;
• « Draft » est pour les tâches où j'ai ouvert une draft pull request sur GitHub. Comme je travaille sur beaucoup de features en même temps, je lance rarement toute la suite de tests en local, donc je laisse la CI le faire sur la draft PR et je reviens vérifier les résultats (quand il y a trop d'échecs, je lance quand même les tests en local). Une fois que tout est vert, j'ouvre la PR pour review et je supprime le worktree local.

Dans la continuité de mon état « Draft », une autre chose que j'aime bien dans Orca, c'est le dock de droite. Il contient un explorateur de fichiers du projet où vous pouvez éditer les fichiers directement, comme dans un IDE. Un deuxième onglet liste toutes les sessions d'agents du worktree courant : quand je suis passé à Orca, il a immédiatement retrouvé toutes mes sessions OpenCode en cours à ce moment-là, donc j'ai pu reprendre sans rien perdre. Un troisième onglet couvre git : fichiers modifiés et stagés, et vous pouvez commit depuis là (ou demander à votre agent de le faire). Et le dernier onglet montre les runs GitHub Actions de votre pull request, donc quand j'ai une draft PR, je peux vérifier où en est la CI sans jamais quitter Orca.

Ce sont les trois features que j'utilise le plus, mais il y en a plein d'autres. Les quick commands permettent de préparer des scripts complets à lancer sur un worktree : j'ai une command « Install deps » qui installe tout ce qu'il faut quand j'ai besoin d'outils comme PHP CS Fixer ou PHPStan. Il y a aussi l'intégration mobile, qui ouvre un tunnel sur le réseau local pour que vous puissiez atteindre vos agents Orca depuis votre téléphone (ajoutez un VPN et ça marche de partout ; je m'en suis servi de temps en temps à la salle de sport). Et ce n'est qu'une fraction de ce qu'Orca propose, il y a beaucoup plus à découvrir.

Mes agents

C'est dans les agents que j'ai le plus investi. Encore un avertissement : je travaille principalement avec Jira, donc certains agents ci-dessous sont orientés Jira, mais ils peuvent facilement être adaptés aux GitHub issues ou à Linear si besoin. Voici le détail complet de ce à quoi ressemble mon sélecteur d'agents :

• build est l'agent intégré qui fait les modifications. C'est le seul agent de cette liste autorisé à toucher au code.
• plan est l'autre agent intégré, utilisé simplement pour planifier.
• heavy-plan est le même que plan, mais adossé à un modèle plus performant : si plan tourne sur un modèle de classe Sonnet, celui-ci tourne sur un équivalent Opus. Je le garde pour les travaux importants ou risqués.
• jira-analyst prend un lien Jira, regarde tous les détails de l'issue, ses parents, et les PR ouvertes à son sujet, puis résume ce qui est demandé, ce qui a déjà été fait, et ce qui pourrait être fait dans le code. C'est mon point de départ numéro un, 95 % du temps.
• jira-feedback couvre le tour suivant : la QA a testé une de mes pull requests et a trouvé une erreur. Cet agent revérifie le ticket Jira depuis son lien, trouve la PR associée, checkout la branche en local, et essaie de comprendre le feedback et de faire de premières hypothèses.
• pr-review-planner intervient quand une PR est ouverte en review et que quelqu'un a laissé des commentaires : il les lit tous et propose comment je pourrais les traiter. Répondre à une review arrête d'être une séance d'archéologie et devient l'exécution d'une checklist.
• pr-reviewer est pour l'autre côté des reviews : quand j'ai une grosse PR à review, je la review toujours moi-même, et en parallèle je lance cet agent pour qu'une review IA attrape ce que j'aurais, peut-être, manqué.

Vous avez peut-être remarqué un motif : à part build, ce sont tous des agents d'analyse. Ils lisent, résument et planifient, mais ils ne touchent pas au code. Cette contrainte est inscrite dans la définition de l'agent elle-même. Voici un extrait abrégé de jira-analyst :

---
mode: primary
model: opencode-go/deepseek-v4-flash
temperature: 0.2
---

You are a technical analyst for Jira issues. When given a Jira issue URL or
issue key, you analyze the ticket and deliver exactly two things: a clear
summary of what the issue is about, and a concrete list of actions the
developer must take to resolve it.

You are strictly read-only. You NEVER modify the codebase: no edits, no file
creation, no refactoring, no "quick fixes". Your only output is analysis and
explanation.

### Investigating the codebase

The action plan must be grounded in the real code, not generic advice:

- grep/glob for the classes, routes, services, config keys, or error messages
  mentioned in the ticket.
- Use `git log`/`git blame` on the affected area to find recent related
  changes: regressions are often introduced by an identifiable commit.
- Check `gh pr list --search "<KEY>"` for existing or past PRs referencing
  the ticket.

La règle read-only n'est pas qu'une promesse dans le prompt : le même fichier porte un bloc de permissions qui rend les éditions impossibles dès le départ.

Les permissions dans OpenCode

OpenCode résout chaque appel d'outil vers une action parmi trois : allow l'exécute sans demander, ask me demande d'abord, et deny le bloque purement et simplement. Ce qui compte ici, c'est qu'il part de valeurs par défaut permissives, la plupart des permissions sont en allow d'origine, donc un agent d'analyse n'est read-only que si vous le dites explicitement. Dans le frontmatter de l'agent, ça donne ça :

---
description: Analyze a Jira ticket and produce an action plan
mode: subagent
permission:
  edit: deny
  webfetch: deny
  bash:
    "*": deny
    "git *": allow
    "gh *": allow
    "jira *": allow
---

La clé permission est indexée par nom d'outil : read, glob, grep, list, bash, task, skill, webfetch, websearch. Vous les passez en revue un par un et vous décidez ce que chacun a le droit de faire, et une entrée "*" fixe la valeur par défaut pour tout ce que vous n'avez pas nommé. Notez que edit est la seule exception à la règle une clé pour un outil : elle couvre tout ce qui écrit sur le disque, donc edit, write, patch et multiedit se retrouvent tous derrière ce deny unique. Le reste reste ouvert, donc l'agent peut toujours lire, grep, glob et lancer les commandes dont il a besoin pour enquêter, et c'est tout ce qu'il fera jamais.

C'est dans le bloc bash que ça devient intéressant. Les règles sont matchées par pattern et la dernière règle qui matche gagne, donc le catch-all passe en premier et les règles spécifiques viennent après :

bash:
  "*": deny           # défaut : rien ne s'exécute
  "git *": allow      # ...sauf git
  "git push *": deny  # ...mais jamais push

Lisez de haut en bas, chaque ligne restreint ou rouvre celle du dessus. Inversez l'ordre et le catch-all avale silencieusement tout le reste. Un dernier piège : les patterns matchent la commande parsée, arguments compris, donc "git" seul ne matche qu'un git nu, tout ce qui a des arguments a besoin du wildcard.

Ce bloc est ce qui transforme « merci de seulement analyser » en quelque chose que l'agent ne peut pas contourner, même si le prompt dérive ou si le ticket essaie de l'entraîner ailleurs.

Et comme ces agents ne font qu'analyser, ils n'ont pas besoin du modèle le plus cher avec une grosse créativité : un modèle rapide et pas cher à faible température fait le travail, de manière déterministe. Si vous voulez les prompts complets, tous mes agents sont disponibles dans ce gist.

Quand Orca et les agents s'emboîtent

Vous vous souvenez du détail d'Orca que je vous avais demandé de garder en tête : quand vous créez un worktree depuis une issue, le prompt par défaut est le lien de l'issue. C'est ici que ça paie. Comme jira-analyst et jira-feedback prennent tous les deux un lien d'issue en entrée, je n'ai presque rien à faire. Je sélectionne mon issue dans l'intégration Jira d'Orca, il ouvre un nouveau worktree, démarre mon agent, et copie le lien. Il ne me reste qu'à basculer sur le bon agent et à le lancer. De « je prends ce ticket » à « un agent l'analyse dans un worktree isolé », il y a deux clics et zéro copier-coller.

La même astuce marche dans l'autre sens, une fois que le worktree a déjà disparu. Quand une PR revient à la vie, parce que la QA a trouvé une erreur ou qu'un reviewer a laissé des commentaires, je crée un nouveau worktree depuis la PR elle-même, dans l'intégration GitHub d'Orca cette fois. L'agent s'ouvre avec le lien de la PR comme prompt, je lance jira-feedback ou pr-review-planner dessus, et tout le reste se fait automatiquement.

Pour vous donner une idée du rythme que tout ça crée : au début de la journée, je vérifie si mes draft PR en cours ont des erreurs. Si ce n'est pas le cas, je prends jusqu'à trois ou quatre issues Jira et je lance mon agent jira-analyst sur toutes, puis je fais généralement de la code review pendant qu'elles tournent. Quand un agent a fini d'analyser, une grosse lecture m'attend : l'idée est de me concentrer d'abord sur la première tâche terminée, de l'envoyer en exécution, puis de prendre la deuxième pendant que la première est occupée, et ainsi de suite, jusqu'à ce que je n'aie plus de tâches et que je reprenne de nouvelles issues.

Mes commandes

Là où les agents portent un rôle complet, les commands sont plus proches de recettes : de petits prompts répétables que je lance à la demande. Deux des miennes sont généralistes :

• /commit-and-pr est plutôt direct : elle génère un message de commit et une description de pull request. Si le dépôt courant a une template GitHub disponible, elle l'utilise comme base pour la description de la PR.
• /activity récupère toute mon activité Jira et GitHub sur les dernières 24 heures, pour m'aider à ne rien oublier pendant mes daily stand-ups. Les autres commands sont très liées à mes projets, et pour les comprendre il faut savoir une chose de notre workflow : une PR est ouverte, la PR est reviewée, puis elle est mise dans une milestone pour être déployée sur un environnement de qualification à des fins de test. C'est comme ça que j'en suis venu à ces commands :
• /github-awaiting-review récupère toutes les pull requests ouvertes et en attente de review, sous forme de liste prête à être copiée dans Slack.
• /github-milestone-triage récupère toutes les pull requests qui ont leur review et qui doivent être testées, et sort une jolie liste que je peux copier dans Slack aussi.
• /milestone-build prend un lien de milestone en argument, rassemble toutes les PR de cette milestone, et crée une release branch pour qu'on puisse déployer chaque changement qu'elle contient. Elle gère aussi les conflits de merge en chemin.

Mes skills

Côté skills, je n'en ai aucune faite maison. J'utilise plutôt un catalogue : la plupart des miennes viennent de superpowers-symfony, une collection de skills orientées Symfony, complétée par quelques skills liées aux projets qui décrivent, par exemple, comment un message de commit ou une description de pull request doit être écrite sur chaque projet. C'est aussi ce qui garde la command commit-and-pr simple : la command n'explique pas comment écrire quoi que ce soit, elle fait juste le travail, et les conventions viennent de ces skills. Ce n'est pas grand-chose, et c'est volontaire : j'ai toujours eu le sentiment qu'on se tourne trop souvent vers les skills, alors que ce qu'on veut vraiment est une command ou un agent.

La philosophie des permissions

Vous l'avez peut-être deviné en lisant le détail de mes agents : tout mon outillage IA est read-only par défaut, et build est le seul agent autorisé à écrire du code. Ce n'est pas un accident, c'est la règle dont tout le reste découle. Les agents proposent, l'humain décide. Considérez ça comme mon contrepoint à la mode des « YOLO agents », où on laisse un agent partir en roue libre avec toutes les permissions.

Derrière cette règle, il y a une conviction : tout code généré avec une IA vous appartient. Le modèle l'a écrit, mais c'est votre nom sur le commit. Être généré par une IA n'exempte pas une seule ligne de review : vous devez toujours vérifier ce qu'elle fait, et comment elle le fait, exactement comme du code que vous auriez écrit vous-même.

La meilleure façon de garder cette review supportable est d'investir avant que le code existe. Je lis les sorties de plan en entier, à chaque fois. Je discute des détails avec l'IA, je conteste les parties qui ne correspondent pas à ce que j'avais en tête, et j'ajuste parfois les prompts de mes agents en chemin, pour que l'exécution atterrisse au plus près de ce que j'ai réellement demandé.

Ensuite je lis le code. Tout le code, diff par diff, de la même façon que je reviewerais la PR d'un collègue : est-ce que ça fait ce que le plan disait, est-ce que ça le fait comme je l'aurais fait, et est-ce qu'il y a là-dedans quelque chose que je ne saurais pas expliquer dans six mois ? Investir dans le plan fait qu'il reste très peu de problèmes à ce stade, mais c'est bien le but. La review reste courte parce que le travail a eu lieu en amont, pas parce que je l'ai bâclée.

Pourquoi ça me rend productif

Il est temps d'appuyer tout ça avec quelque chose de plus concret que de l'enthousiasme. Les gains ne sont pas uniformes : certains sont spectaculaires, d'autres sont marginaux, et ça vaut la peine d'être honnête sur qui est quoi.

Le cœur de tout ça, ce sont jira-analyst et jira-feedback, les deux agents qui m'ont fait aimer ce workflow. Là où je travaille, on a une équipe « focus » : tout le monde peut travailler sur tout, des stocks au retail en passant par la gestion client. Le changement de contexte entre les issues est énorme, et c'est exactement ce que jira-analyst absorbe : il m'explique tout ce que j'ai besoin de savoir avant de plonger dans ma tâche. Selon l'issue, ça me fait gagner jusqu'à une demi-journée, parfois une journée entière. C'est aussi l'agent dans lequel j'ai le plus investi : son prompt a été amélioré itération après itération pour arriver au point actuel.

pr-review-planner est une bénédiction du même ordre. Traiter les retours de review me prenait beaucoup de temps, parce que chaque commentaire demande son contexte : quel code il vise, ce que le reviewer voulait dire, quelles sont les options. Maintenant je lance l'agent, je lis la sortie, et j'ai tout ce qu'il me faut pour décider quoi faire, commentaire par commentaire.

Côté commands, github-awaiting-review et github-milestone-triage ont remplacé une corvée : parcourir toutes les PR, vérifier qui a créé chaque issue et qui la review, construire le message Slack, l'envoyer. Selon le nombre de PR ouvertes, ça pouvait me coûter jusqu'à 20 minutes. Maintenant je lance la command, je reviens plus tard, et c'est fait. Et les minutes ne sont même pas le vrai gain : le vrai gain, c'est que je ne casse plus mon focus pour ça. Un truc aussi simple appartient à un prompt, et mon attention reste sur mes tâches. Et je vais être honnête sur milestone-build : le gain de temps brut est faible, puisque avant elle je faisais simplement un git merge de chaque branche dans une release branch, puis un push. Ce qu'elle enlève, c'est tout ce qu'il y a autour des merges : je ne gère plus les conflits, ni la vérification de quelles PR doivent être dedans, tout ça est automatisé.

Et puis il y a Orca lui-même. La majorité de ma routine quotidienne vit maintenant dedans : je n'ouvre Jira que pour m'assigner des tickets, GitHub pour review les PR des autres développeurs, et Slack pour partager les listes que mes commands préparent (et si un jour je peux faire tout ça depuis Orca, je serai content). Moins d'outils veut dire moins de choses auxquelles penser, et tout va plus vite. Et la gestion des worktrees mérite un dernier mot : j'ai essayé de créer les worktrees à la main, puis de demander à un agent de les créer pour moi. Que des outils comme Jean et Orca s'en occupent nativement est une avancée formidable pour cette philosophie ADE.

Conclusion

En regardant tout ce chemin, le motif du début tient toujours : j'ai suivi là où la technique m'emmenait, une fois de plus. Des lignes de C aux librairies, des librairies aux frameworks, des frameworks aux features. Sauf que cette fois, la technique n'est ni un langage ni un framework : c'est un collègue. Il lit les tickets, analyse le code, propose des plans ; je dirige, je review, et je décide.

Et pour être honnête jusqu'au bout : tout n'est pas encore fluide. Les worktrees sont une bénédiction, mais il reste des trous, et le plus gros pour moi est l'infrastructure locale. Faire tourner plusieurs copies du même site veut dire des conflits Docker, donc quand je travaille dans un worktree, j'évite au maximum de lancer Docker. On a travaillé sur de l'outillage pour adoucir ça : nos conteneurs sont maintenant préfixés avec le nom du worktree, par exemple. Mais certaines pièces résistent : on utilise Traefik comme routeur HTTP, et vous ne pouvez pas en faire tourner plus d'un, donc il faudra encore du travail d'outillage avant que tout ça tourne bien côte à côte.

Des aspérités comme celles-ci sont le signe d'un écosystème jeune, pas d'une mauvaise direction. Les IDE ont mis des décennies à devenir ce qu'ils sont ; les ADE commencent à peine, et ils ont déjà changé mon quotidien plus que n'importe quel outil depuis les frameworks. Je ne sais pas quel ADE va gagner, ni si ceux que j'utilise aujourd'hui seront encore là dans cinq ans. Mais je sais que je ne reviendrai pas à un environnement construit pour moi seul : les agents ont rejoint l'équipe, et ils méritent un bon bureau eux aussi.

Sur un de nos projets, nous avions déjà des tests Behat pour le fonctionnel, et des tests PHPUnit pour le métier. Mais aucun de ces tests ne disait « la page d’accueil ne ressemble plus à la page d’accueil ». C’est exactement ce que font les tests de non-régression visuelle, et Playwright le fait très bien nativement.

Dans cet article, nous allons voir la stack que nous avons mise en place sur ce projet : les tests eux-mêmes, les tasks Castor pour les piloter, le passage par Docker pour avoir un rendu stable entre les machines de l’équipe, et enfin comment nous postons les images de diff directement dans un commentaire de la pull request.

Le principe : toHaveScreenshot()

Playwright, la solution que nous utilisons déjà pour nos tests E2E, propose une assertion faite pour ça : toHaveScreenshot(). Elle prend une capture de la page, la compare avec l’image de référence commitée dans le dépôt, et échoue si les deux diffèrent trop. En l'occurrence, Playwright vérifie si le nombre de pixels différents entre les 2 images est inférieur à un seuil configuré.

Notre fichier application/e2e/screenshots.spec.ts couvre les pages structurantes du site : la home, la page de résultats de recherche, une page de détail, etc. Plusieurs pages, autant d'images de référence, et de quoi attraper l’immense majorité des régressions CSS.

Un test ressemble à ça :

test('homepage screenshot', async ({ page }) => {
    await page.goto(homeUrl);
    // The search form is a React component that mounts client-side;
    // wait for it so the layout below does not shift.
    await page.locator('#tab-search').waitFor({ state: 'visible' });
    await stabilize(page);

    await expect(page).toHaveScreenshot('homepage.png', {
        fullPage: true,
        animations: 'disabled',
        maxDiffPixels: 100,
        // The header image is picked at random server-side, so mask it.
        mask: [page.getByTestId('homepage-header-image')],
    });
});

Écrire le test en lui-même est donc assez trivial. Toute la difficulté de l’exercice est ailleurs : il faut que la page soit déterministe. Un test visuel qui échoue une fois sur trois ne sert à rien, car au bout de deux semaines toute l’équipe relance le job sans même regarder. Nous avons donc passé pas mal de temps, non pas à écrire les tests, mais à supprimer une par une toutes les sources de variation.

Attendre que la page soit vraiment stable

Le piège classique : la capture est prise pendant que la page finit de se construire. Images en lazy loading, blocs asynchrones, polices web qui provoquent un reflow au moment où elles arrivent… La capture est techniquement valide, mais elle ne correspond à rien de reproductible.

D’où ce petit helper, appelé dans tous les tests :

// Wait for the page to be visually stable before taking a full-page screenshot:
// network idle (lazy images / async blocks) + web fonts loaded (avoids reflow).
async function stabilize(page: Page): Promise<void> {
    await page.waitForLoadState('networkidle');
    await page.evaluate(() => document.fonts.ready);
}

Et quand ça ne suffit pas, on attend explicitement l’élément qui pose problème. Sur la home, c’est le formulaire de recherche (un composant React monté côté client) ; sur une autre page, c’est un Swiper qui se réorganise après le networkidle :

await page.locator('.js-swiper-expertises.c-swiperinitialized').first().waitFor({ state: 'visible' });

La classe c-swiperinitialized n’est ajoutée qu’une fois le carrousel initialisé : c’est donc un bon signal pour savoir que le rendu final est atteint.

Masquer ce qui est volontairement aléatoire

Certaines zones ne seront jamais stables, et c’est normal : c’est le produit qui le veut. L’image d’en-tête de la home est tirée au sort côté serveur. Sur la page d'un point de vente, le bloc FAQ s’affiche aléatoirement, et les horaires d’ouverture mettent en avant le jour courant… qui change tous les jours.

Plutôt que de chercher à contourner le problème, on peut simplement demander à Playwright de masquer ces zones : elles seront recouvertes d’un aplat avant la comparaison.

Pour parvenir à cela, il faut lister les éléments à masquer directement dans la config de Playwright :

mask: [
    page.getByTestId('faq-block'), // display randomly
    page.getByTestId('store-timetable'), // current day open by default (changes daily)
],

Nous utilisons ici des data-testid plutôt que des classes CSS : cela donne un point d’accroche stable, qui ne bougera pas à la prochaine refonte du style.

Fixer le viewport et tolérer une poignée de pixels

Deux derniers réglages, dans playwright.config.ts et dans les tests :

use: {
    ignoreHTTPSErrors: true,
    /* Fixed viewport to keep screenshot dimensions deterministic across machines. */
    viewport: { width: 1280, height: 900 },
    trace: 'on-first-retry',
},

Un viewport fixe garantit que les dimensions de la capture ne dépendent pas de la machine. Quant au maxDiffPixels (50 sur la plupart des pages, 100 sur la home qui est plus chargée), il laisse passer les micro-variations d’antialiasing sans laisser passer un vrai décalage de bloc. C’est un curseur à régler : trop bas, les tests deviennent flaky ; trop haut, on rate des régressions. Ces valeurs se sont stabilisées à l’usage.

Un rendu stable grâce à Docker

Il reste malgré tout une source de variation, et c’est probablement la plus importante : une capture d’écran n’est pas seulement le résultat de votre HTML et de votre CSS, c’est aussi le résultat du moteur de rendu de la machine qui a pris la capture. Rendu des polices, antialiasing, sous-pixels : macOS et Linux ne produisent tout simplement pas les mêmes pixels.

Playwright en est d’ailleurs conscient, puisqu’il suffixe les images de référence par plateforme. Voici le contenu de notre dossier de snapshots :

application/e2e/screenshots.spec.ts-snapshots/
├── detail-page-chromium-linux.png
├── homepage-chromium-linux.png
├── list-page-chromium-linux.png
├── pro-homepage-chromium-linux.png
├── store-homepage-chromium-linux.png
└── store-page-chromium-linux.png

Notez bien le suffixe -chromium-linux. Or, notre équipe est mixte : certains développent sur macOS, d’autres sur Linux. Si chacun lance Playwright sur son hôte, il faut soit commiter deux jeux d’images (-darwin et -linux) et les maintenir en double, soit accepter que les collègues sur Mac échouent systématiquement sur des tests pourtant verts en CI. Aucune des deux options n’est satisfaisante.

Heureusement, la solution est celle que nous appliquons déjà à tout le reste sur ce projet : tout tourne dans Docker. Les navigateurs Playwright sont installés dans un conteneur dédié à tout le tooling du projet (Composer, nodejs, etc.), jamais sur l’hôte, et les tests sont exécutés dedans. Ainsi, que ce soit les développeurs sous Mac ou Linux, ou bien depuis le runner de CI, c'est toujours le même environnement de rendu qui est exécuté. Les images de référence sont générées une fois, dans le conteneur sous Linux, et valent pour tout le monde.

Quant aux binaires des navigateurs, ils atterrissent dans le cache par défaut de Playwright ($HOME/.cache/ms-playwright). Sur notre projet, ce dossier est un volume monté : ils survivent ainsi aux reconstructions de conteneur et ne sont pas re-téléchargés à chaque lancement.

projects: [
        {
            name: 'chromium',
            use: { ...devices['Desktop Chrome'] },
        },
    ],

Puis on demande à Playwright d'installer uniquement Chromium :

yarn playwright install chromium'

Grâce au cache natif et à l'utilisation d'un seul navigateur, nous gagnons une quinzaine de secondes de temps d'exécution du job E2E dans notre CI.

Piloter les tests avec Castor

Comme souvent quand nos projets nécessitent de lancer des commandes, nous avons mis en place une task Castor pour simplifier la DX. Le but est que personne n’ait jamais besoin de savoir dans quel conteneur, ni avec quelles variables d’environnement, Playwright doit tourner :

#[AsTask(description: 'E2E Playwright Tests')]
function e2e(?string $filter = null, bool $updateScreenshots = false): void
{
    io()->section('Running E2E Playwright Tests...');

    // Browsers are downloaded in the default cache directory ($HOME/.cache/ms-playwright), which
    // is a mounted volume: the download only happens once. Only chromium is needed by the tests.
    io()->comment('Installing Playwright browsers...');
    docker_compose_run('yarn playwright install chromium');

    $command = 'yarn playwright test';

    // Optionally filtered to a single spec
    if (null !== $filter) {
        $command .= ' ' . escapeshellarg($filter);
    }

    if ($updateScreenshots) {
        io()->comment('Running tests and updating screenshots...');
        $command .= ' --update-snapshots';
    }

    docker_compose_run($command);
}

Pour résumer, cette task va :

1. s’assurer que le navigateur utilisé par les tests est installé ;
2. lancer les tests, éventuellement filtrés sur un seul fichier de spec ;
3. et, si on le lui demande, régénérer les images de référence plutôt que de les comparer.

Le workflow au quotidien tient alors en trois commandes :

# Lancer les comparaisons
castor qa:e2e --filter screen

# En cas d’échec : ouvrir les images de diff (les différences ressortent en rouge)
castor qa:e2e-diff

# Si les différences sont légitimes (modification CSS, ajout de contenu…) :
# régénérer les images de référence
castor qa:e2e --update-screenshots

La task qa:e2e-diff ne fait pas grand-chose, mais elle évite d’avoir à fouiller dans test-results/ pour trouver le bon PNG :

#[AsTask(description: 'Open the diff images of the last failing screenshots')]
function e2e_diff(): void
{
    $diffs = glob(\dirname(__DIR__) . '/application/test-results/*/*-diff.png') ?: [];

    if ([] === $diffs) {
        io()->success('No screenshot diff found. All screenshots match.');

        return;
    }

    foreach ($diffs as $diff) {
        io()->writeln('Opening ' . basename($diff));
        open($diff);
    }
}

Notez que Playwright n’écrit ces fichiers -diff.png que pour les captures ayant réellement échoué. Il n’y a donc rien à filtrer : ce qui se trouve dans le dossier est exactement ce qui est cassé.

Poster les diffs dans la pull request

Tout ceci fonctionne très bien en local. En CI, en revanche, l’expérience était nettement moins agréable : un job rouge, un message « expected 50 pixels, got 3400 », et il fallait ensuite aller récupérer les images à la main pour comprendre ce qui avait changé.

Nous avons donc ajouté une étape supplémentaire à la CI : quand un screenshot échoue, les images sont postées dans un commentaire de la pull request, avec l’attendu, l’obtenu et le diff côte à côte dans un tableau Markdown. La personne qui relit voit le problème directement en ouvrant la PR, sans avoir à cliquer sur « Détails ».

Le job GitHub Actions reste très simple, puisque toute la logique est déportée dans des tasks Castor :

- name: E2E Playwright Tests
  run: castor qa:e2e

- name: Report E2E screenshot failures on the PR
  if: ${{ failure() && github.event_name == 'pull_request' }}
  run: castor qa:e2e-report-failures
  env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      E2E_PR_NUMBER: ${{ github.event.pull_request.number }}
      E2E_RUN_ID: ${{ github.run_id }}
      GITHUB_REPOSITORY: ${{ github.repository }}
      GITHUB_SERVER_URL: ${{ github.server_url }}

- name: Clear E2E screenshot report on the PR
  if: ${{ success() && github.event_name == 'pull_request' }}
  run: castor qa:e2e-clear-report
  env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      E2E_PR_NUMBER: ${{ github.event.pull_request.number }}
      GITHUB_REPOSITORY: ${{ github.repository }}

Il reste une contrainte à contourner : on ne peut pas afficher une image dans un commentaire GitHub sans que celle-ci soit accessible via une URL publique. Nous hébergeons donc les images sur notre préproduction, en réutilisant l’accès SSH dont on se sert déjà pour le déploiement :

$remoteUser = 'deploy';
$remoteHost = 'preprod-web01';
$remoteDir = '/var/www/sites/www.example.com/current/web/images/_e2e';
// Careful: pick a host that is NOT behind a Basic auth, or GitHub cannot fetch the images.
$publicBaseUrl = 'https://static-preprod.example.com/images/_e2e';
$retentionDays = 30;

Castor fournit justement tout ce qu’il faut pour piloter une machine distante, avec ssh_run(), ssh_upload() et ssh_download(). Une fois les images rangées dans un dossier de staging local, l’envoi tient en deux appels :

// Upload the whole staging directory. ssh_upload() always runs scp with "-r", and copying a
// source directory onto a non-existing destination creates it: remove any leftover from a
// previous attempt on the same run first, otherwise scp would nest it inside itself.
$remoteRunDir = $remoteDir . '/' . $runKey;
ssh_run(
    \sprintf('rm -rf %s && mkdir -p %s', escapeshellarg($remoteRunDir), escapeshellarg($remoteDir)),
    host: $remoteHost,
    user: $remoteUser,
);
ssh_upload($staging, $remoteRunDir, host: $remoteHost, user: $remoteUser);

Le commentaire est ensuite construit à la main en Markdown :

$body .= "## ❌ Régression visuelle E2E\n\n";
$body .= \sprintf("Des screenshots ont changé sur ce run ([logs](%s)).\n\n", $runUrl);

foreach ($screenshots as $screenshot) {
    $base = \sprintf('%s/%s/%s/%s', $publicBaseUrl, $runKey, $screenshot['testDir'], $screenshot['name']);
    $body .= \sprintf("### `%s`\n\n", $screenshot['name']);
    $body .= "| Attendu | Obtenu | Diff |\n| --- | --- | --- |\n";
    $body .= \sprintf(
            "| %s | %s | %s |\n\n",
            null !== $screenshot['expected'] ? \sprintf('![attendu](%s-expected.png)', $base) : '—',
            null !== $screenshot['actual'] ? \sprintf('![obtenu](%s-actual.png)', $base) : '—',
            \sprintf('![diff](%s-diff.png)', $base),
        );
}

Quelques détails supplémentaires méritent d’être mentionnés.

Un commentaire « sticky » plutôt qu’un nouveau à chaque run

Une PR avec plusieurs allers-retours finirait vite avec une dizaine de commentaires de robot. Pour éviter ça, nous plaçons un marqueur HTML invisible en tête du corps du message :

// Hidden marker used to identify the sticky E2E screenshots report comment on a PR.
const E2E_REPORT_MARKER = '<!-- e2e-screenshots-report -->';

Il suffit ensuite de parcourir les commentaires de la PR à la recherche de ce marqueur :

const E2E_GITHUB_API_BASE = 'https://api.github.com';

function e2e_find_report_comment(array $options, string $repo, string $pr): ?int
{
    $page = 1;
    do {
        $listUrl = \sprintf('%s/repos/%s/issues/%s/comments?per_page=100&page=%d', E2E_GITHUB_API_BASE, $repo, $pr, $page);
        $comments = http_request('GET', $listUrl, $options)->toArray();
        foreach ($comments as $comment) {
            if (str_contains($comment['body'] ?? '', E2E_REPORT_MARKER)) {
                return $comment['id'];
            }
        }
        ++$page;
    } while (100 === \count($comments));

    return null;
}

Les $options sont communes à tous les appels, et regroupent l’authentification et les en-têtes attendus par l’API :

function e2e_github_options(string $token): array
{
    return [
        'auth_bearer' => $token,
        'headers' => [
            'Accept' => 'application/vnd.github+json',
            'X-GitHub-Api-Version' => '2022-11-28',
        ],
    ];
}

Et selon qu’on a trouvé un commentaire existant ou non, on fait un PATCH sur celui-ci ou un POST d’un nouveau :

$options = e2e_github_options($token);
$existingId = e2e_find_report_comment($options, $repo, $pr);

if (null !== $existingId) {
    $url = \sprintf('%s/repos/%s/issues/comments/%d', E2E_GITHUB_API_BASE, $repo, $existingId);
    http_request('PATCH', $url, [...$options, 'json' => ['body' => $body]])->getContent();
    io()->success(\sprintf('Updated PR #%s comment with %d screenshot(s).', $pr, \count($screenshots)));
} else {
    $url = \sprintf('%s/repos/%s/issues/%s/comments', E2E_GITHUB_API_BASE, $repo, $pr);
    http_request('POST', $url, [...$options, 'json' => ['body' => $body]])->getContent();
    io()->success(\sprintf('Posted a comment on PR #%s with %d screenshot(s).', $pr, \count($screenshots)));
}

La même fonction de recherche est réutilisée par la task qa:e2e-clear-report : quand les tests repassent au vert, on retrouve le commentaire par son marqueur et on le supprime (DELETE), pour que la PR ne garde pas la trace d’un problème déjà corrigé.

Dédoublonner les retries

En CI, Playwright réessaie deux fois (retries: process.env.CI ? 2 : 0) et écrit les résultats de chaque tentative dans des dossiers frères <test>-retryN. Sans traitement, la même régression apparaîtrait donc trois fois dans le commentaire. Nous regroupons les images par test et par capture, en ne gardant que la tentative la plus élevée :

// Retries live in sibling "<test>-retryN" directories; strip the suffix for a stable key.
$testDir = basename($dir);
$retry = 0;
if (preg_match('/^(.*)-retry(\d+)$/', $testDir, $matches)) {
    $testDir = $matches[1];
    $retry = (int) $matches[2];
}

$key = $testDir . '/' . $name;
if (isset($screenshots[$key]) && $screenshots[$key]['retry'] >= $retry) {
    continue;
}

Purger les vieilles images

Enfin, comme nous poussons des images sur un serveur partagé à chaque échec, il faut éviter que le dossier ne grossisse indéfiniment. Un find sur les dossiers de run trop anciens fait l’affaire. Notez le allowFailure : le ménage ne doit pas faire échouer le rapport s’il se passe mal.

// Prune old run directories so the shared folder does not grow forever.
ssh_run(
    \sprintf(
        'find %s -mindepth 1 -maxdepth 1 -type d -mtime +%d -exec rm -rf {} +',
        escapeshellarg($remoteDir),
        $retentionDays,
    ),
    host: $remoteHost,
    user: $remoteUser,
    allowFailure: true,
);

Au bout du compte, toute la logique pour poster les régressions visuelles en commentaire dans GitHub représente environ 200 lignes de PHP, mais cette amélioration nous fait gagner du confort au quotidien : on passe d’un « le job E2E est rouge » à un « ah oui, le footer a pris 4px » sans quitter la page de la PR.

Le cas des fixtures aléatoires

Il reste une dernière source de variation, et c’est celle qui nous a demandé le plus de tâtonnements.

Nos fixtures utilisent nelmio/alice, et donc Faker, ce qui implique de l’aléatoire : des titres, des prix, des descriptions, des noms générés à la volée. Or une page de détail ne peut évidemment pas produire une capture stable si le prix affiché change à chaque chargement des fixtures.

Nous avions déjà fait en sorte d'éviter les soucis d'aléatoire dès le début du projet car les tests Behat avaient le même besoin d'avoir des contenus stables dans le temps, et la solution tient en une ligne de configuration :

# application/config/packages/nelmio_alice.yaml
when@dev: &dev
    nelmio_alice:
        locale: 'fr_FR' # Default locale for the Faker Generator
        seed: 42

when@test: *dev

Avec un seed fixe, Faker devient déterministe : les mêmes fixtures rechargées produisent exactement les mêmes données, et donc exactement les mêmes pixels. Problème réglé, en apparence.

Sauf que le déterminisme d’un générateur pseudo-aléatoire est positionnel. Le seed garantit une séquence de valeurs, mais pas l’affectation d’une valeur donnée à un objet donné. Si vous ajoutez une entité au milieu d’un fichier de fixtures, par exemple pour un test Behat qui n’a rien à voir avec le visuel, vous consommez un tirage supplémentaire, et tout ce qui vient après décale d’un cran dans la séquence. Les prix changent, les titres changent, et les captures d’écran deviennent rouges à cause d’un test fonctionnel sans aucun rapport.

Le symptôme est assez déroutant la première fois qu’on le rencontre : la PR ne touche pas une ligne de CSS, et pourtant les tests visuels échouent.

La règle que nous nous sommes donnée est simple : quand une capture change à cause d’un décalage de fixtures, on change la fixture impactée puis on régénère l’image. Concrètement, on identifie la donnée qui a bougé sur la page (un prix, un titre, un nom) et on lui donne une valeur en dur au lieu de la laisser à Faker :

# Avant : la valeur dépend de la position du tirage dans la séquence.
title: '<sentence()>'
price: '<numberBetween(100000, 900000)>'

# Après : la valeur est figée, et ne bougera plus jamais.
title: 'Une valeur figée pour les tests de screenshots'
price: 245000

Le commentaire de PR est précieux pour ça : il montre immédiatement quelle donnée a changé. Constater qu’un prix est passé de 245 000 € à 312 000 € prend deux secondes, là où le déduire d’un compteur de pixels est impossible.

L’intérêt de procéder ainsi, c’est que la correction est définitive et que l’effort est réparti dans le temps. Nous ne figeons pas toutes les fixtures d’un coup - ce serait un gros chantier, et une bonne partie n’apparaît de toute façon dans aucune capture. Nous figeons uniquement celles qui nous ont réellement posé problème, au moment où elles nous le posent. Au fil des PR, les données visibles sur les pages sous test deviennent progressivement déterministes, et ce type d’échec se raréfie de lui-même.

En résumé

Grâce à Playwright, Docker et Castor, nous avons pu mettre en place une détection des régressions visuelles qui reste simple à l’usage :

• toHaveScreenshot() fait tout le travail de comparaison, sans outil externe ni service tiers à payer ;
• le passage par Docker garantit un rendu identique sur les postes de l’équipe et en CI, quel que soit l’OS ;
• les tasks Castor masquent la plomberie et installent leurs dépendances toutes seules ;
• le déterminisme est obtenu par un ensemble de petits réglages : viewport fixe, attente explicite de stabilisation, masques sur les zones volontairement aléatoires et seed sur les fixtures ;
• les diffs postés directement dans la pull request rendent chaque échec compréhensible en un coup d’œil.

Quelques captures d’écran seulement, et quelques centaines de lignes de configuration : ce n’est évidemment pas une couverture exhaustive du site, et ce n’est pas le but. Mais depuis leur mise en place, les régressions de mise en page sur les pages structurantes sont détectées avant la mise en production, et non plus après.

Si Sylius s’est imposé dans l’écosystème e-commerce, c’est notamment grâce à sa capacité à s’adapter à des besoins métier très variés sans imposer une architecture rigide. Son système d’extensions permet de faire évoluer progressivement les fonctionnalités tout en conservant les mécanismes du cœur du framework.

Fin d'année dernière, nous avons lancé le JoliMediaBundle, un bundle Symfony dédié à la gestion de bibliothèques de medias.

Il était déjà accompagné de deux bridges pour SonataAdmin et EasyAdmin.

La Genèse du bridge

Récemment arrivé chez JoliCode et expert Sylius, j’ai rapidement engagé des discussions autour de l’intégration du MediaBundle dans cet écosystème. C’est ainsi qu’est née l’idée de ce nouveau bridge, visant à connecter harmonieusement la gestion des médias avec Sylius.

La gestion des médias dans Sylius

Avant d’introduire ce nouveau bridge, il est utile de faire un état des lieux de la gestion des médias dans Sylius aujourd’hui.

Par défaut, Sylius propose un système simple mais efficace pour associer des images aux principales ressources du catalogue, comme les produits ou les taxons. Cette gestion repose sur des entités d’images directement liées aux ressources, avec quelques métadonnées basiques (type, position, etc.).

Cette approche répond parfaitement aux besoins classiques d’un site e-commerce : illustrer un produit, afficher des visuels de catégories, ou encore gérer des galeries simples.

En revanche, certaines limites apparaissent dès que les besoins deviennent plus transverses. Notamment :

• la difficulté à réutiliser facilement un même média à plusieurs endroits sans duplication ;
• l’absence d’une organisation centralisée des fichiers (dossiers, tags, recherche…) ;
• une gestion éclatée des médias, propre à chaque ressource.

En pratique, chaque entité embarque ses propres fichiers, ce qui fonctionne bien à petite échelle mais devient rapidement contraignant dès que le volume de médias augmente ou que plusieurs équipes interviennent.

Le bridge Sylius et JoliMediaBundle

C’est précisément ce constat qui a motivé la réflexion autour d’une gestion des médias plus centralisée et réutilisable au sein de l’écosystème Sylius, en s’appuyant sur le JoliMediaBundle développé chez JoliCode. Pour répondre à ces limites, nous avons développé le bridge Sylius pour ce bundle. L’objectif n’est pas de modifier le fonctionnement de Sylius ni de réécrire sa gestion des médias, mais d’y ajouter une couche d’intégration propre, basée sur ses mécanismes d’extension.

Dans un projet Sylius, les médias sont utilisés dans les images produit, les images de taxons et les avatars administrateurs. Ces usages sont bien intégrés au modèle natif mais restent isolés les uns des autres. Le bridge vient enrichir ce fonctionnement en introduisant une médiathèque centralisée.

Il est également pensé pour être compatible avec la Sylius Stack au sens large, et pas uniquement avec un contexte e-commerce. Il peut ainsi s’intégrer dans des back-offices Sylius utilisés comme base d’application, où la gestion de médias est un besoin transverse à plusieurs domaines fonctionnels. Cela permet d’utiliser la même approche de médiathèque centralisée dans des projets plus généraux construits avec Sylius.

Concrètement, l’approche repose sur des extensions simples et ciblées :

• extension des entités Sylius concernées lorsque cela est nécessaire ;
• remplacement des champs de formulaire dans le back-office pour utiliser le sélecteur de médias du JoliMediaBundle ;
• intégration progressive via les points d’extension fournis par Sylius.

Cette stratégie permet de conserver les usages métier actuels tout en introduisant une gestion plus cohérente et réutilisable des médias. Chaque image (produit, taxon, administrateur) garde son rôle, mais s’inscrit désormais dans une logique commune de médiathèque.

L’intégration reste volontairement discrète : le bridge agit comme une surcouche qui s’insère dans l’écosystème Sylius sans en modifier les fondations.

C’est cette approche progressive qui rend l’adoption possible dans un projet existant, sans refonte du modèle de données ni rupture fonctionnelle.

La question devient alors plus concrète : comment ce bridge s’insère-t-il techniquement dans Sylius, et quels sont les mécanismes utilisés pour relier proprement la médiathèque au modèle existant ?

Une intégration simple dans Sylius

Lorsque vous avez installé le Media bundle, il faut activer le bridge Sylius :

// filepath: config/bundles.php
return [
    // ...
    JoliCode\MediaBundle\Bridge\Sylius\JoliMediaSyliusBundle::class => ['all' => true],
];

Ensuite, on active les routes pour le back-office :

# filepath: config/routes/joli_media.yaml
_joli_media_sylius:
    resource: "@JoliMediaSyliusBundle/src/Admin/Controller/"
    prefix: /admin/media

Et enfin, on importe la configuration du package :

# filepath: config/packages/joli_media_sylius.yaml
imports:
    - { resource: "@JoliMediaSyliusBundle/config/app.php" }

L’idée est de s’appuyer sur les mécanismes d’extension classiques de Symfony et Sylius, afin de rester le moins intrusif possible.

Un trait réutilisable pour les médias

La première brique consiste à utiliser un trait permettant d’ajouter une gestion de média à n’importe quelle entité métier :

Vous pouvez associer un média à une entité Doctrine Sylius, tout en conservant une logique simple côté domaine. Cela synchronisera le champ path existant dans Sylius.

Extension des entités Sylius

Cette approche s’intègre naturellement aux entités existantes. Par exemple, pour les images produit :

namespace App\Entity\Product;

use Doctrine\ORM\Mapping as ORM;
+use JoliCode\MediaBundle\Bridge\Sylius\Doctrine\ORM\EntityWithMediaImageTrait;
use Sylius\Component\Core\Model\ProductImage as BaseProductImage;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_product_image')]
class ProductImage extends BaseProductImage
{
   +use EntityWithMediaImageTrait;
}

On étend ainsi une entité Sylius sans en modifier le cœur, en ajoutant uniquement la capacité de manipuler un média via le bundle.

Intégration dans le back-office

Enfin, côté administration, l’intégration passe par une extension de formulaire Sylius. Le champ fichier natif est remplacé par un composant dédié au JoliMediaBundle :

class ProductImageTypeExtension extends AbstractTypeExtension
{
   public function buildForm(FormBuilderInterface $builder, array $options): void
   {
       $builder->add('file', MediaChoiceType::class, [
           'property_path' => 'media',
       ]);
   }

   public static function getExtendedTypes(): iterable
   {
       yield ProductImageType::class;
   }
}

Cela permet de brancher directement la médiathèque dans l’interface d’administration Sylius, sans casser les formulaires existants.

Ces Forms extensions sont directement fournies par le bridge, il vous suffit de les déclarer dans Symfony:

# config/services.yaml
services:
   JoliCode\MediaBundle\Bridge\Sylius\Admin\Form\Extension\AvatarImageTypeExtension: null
   JoliCode\MediaBundle\Bridge\Sylius\Admin\Form\Extension\ProductImageTypeExtension: null
   JoliCode\MediaBundle\Bridge\Sylius\Admin\Form\Extension\TaxonImageTypeExtension: null

Le File input est remplacé par celui du Media bundle.

Pour les plus observateurs, vous pouvez remarquer que nous avons modifié le template pour retirer l’aperçu fourni par Sylius nativement.

La Médiathèque est le point fort du Media bundle. Elle permet de visualiser mais également d’organiser votre arborescence.

Une vue « Grid » est également disponible pour afficher les images en plus grand format.

Une page détails du media permet d’obtenir davantage d’informations ainsi que les options d’intégration.

Un onglet « Variations » est disponible afin de consulter les différentes variantes de vos médias, avec leurs tailles, formats et dimensions respectifs.

Il est ainsi possible d’utiliser le système de compression du JoliMediaBundle au lieu du système natif de Sylius (utilisant LiipImagine).

Remplaçons les images dans la liste des produits :

<?php

namespace App\Grid\Mutator;

use Sylius\Bundle\AdminBundle\Grid\ProductGridInterface;
use Sylius\Bundle\GridBundle\Builder\Field\TwigField;
use Sylius\Component\Grid\Builder\GridBuilderInterface;
use Sylius\Component\Grid\Attribute\AsGridMutator;
use Sylius\Component\Grid\Mutator\GridMutatorInterface;

#[AsGridMutator(
    grid: 'sylius_admin_product', 
    // ou
    grid: ProductGridInterface::NAME // constante ajoutée sur Sylius 2.3
)]
class ReplaceImageFromProductGridMutator implements GridMutatorInterface
{
    public function __invoke(GridBuilderInterface $gridBuilder): void
    {
        $gridBuilder
            ->withFields(
                TwigField::create('image', template: 'admin/product/grid/field/image.html.twig'),
            )
        ;
    }
}

Ainsi on remplace le field image en utilisant notre propre template Twig.

<!-- templates/admin/product/grid/field/image.html.twig ->
{% from '@JoliMediaSylius/admin/shared/helper/product_image.html.twig' import image %}


<div class="thumbnail-box-image">
   {{ image(data) }}
</div>

Le résultat est identique en apparence, mais on peut voir que l’image a été traitée par le JoliMediaBundle en y regardant de plus près :

Utilisation dans le shop

Le mécanisme cœur de Sylius n’étant pas modifié, les images continuent de fonctionner comme auparavant côté front. Elles peuvent donc être traitées directement par LiipImagine par défaut, sans nécessiter d’adaptation spécifique. Il n’est pas obligatoire, dans un premier temps, d’aller plus loin que cette intégration côté administration. Il est ensuite possible d’améliorer progressivement la qualité du rendu des images en effectuant les ajustements nécessaires côté front, comme décrit dans la documentation du bundle.

Réorganiser votre médiathèque

Un mécanisme de propagation des changements dans vos entités permet de déplacer ou renommer vos médias librement, sans casser les références existantes dans votre application. Cette approche facilite non seulement la recherche et l’identification des médias dans le back-office, mais également la réorganisation progressive de la médiathèque au fil du temps, que ce soit pour restructurer une arborescence, harmoniser des noms de fichiers ou regrouper certains médias par domaine fonctionnel.

Conclusion

Sylius propose déjà une base solide pour la gestion des médias dans un contexte e-commerce. Le JoliMediaBundle apporte une vision plus transversale et structurée de la gestion des fichiers. Le bridge entre les deux ne cherche pas à opposer ces approches, mais à les faire coexister proprement. En pratique, cette combinaison permet de conserver la simplicité du modèle Sylius tout en introduisant une médiathèque centralisée, réutilisable et plus adaptée à des projets qui grandissent ou se complexifient. C’est aussi une manière de prolonger la philosophie même de Sylius : rester extensible, sans imposer de rigidité, tout en laissant la liberté d’adapter l’architecture aux besoins réels du projet.

Il y a peu, je me suis mis à rejouer à Magic: The Gathering avec des amis. C’est un jeu de cartes à collectionner dans lequel on construit des decks pour affronter ses adversaires à travers divers modes de jeux possibles. Le jeu existe depuis 1993 et n’a cessé d’évoluer depuis. Résultat : même les joueurs et joueuses les plus expérimenté·es se font parfois surprendre par certaines règles ou interactions de cartes. Alors pour moi, qui n’avait pas joué depuis 20 ans , autant vous dire qu’à chaque partie, je passe un bon moment sur Internet à chercher telle ou telle règle pour éviter de faire n’importe quoi. C’est là que je me suis dit que ce serait sympa d’avoir à portée de main un petit assistant à qui poser directement mes questions. Pourquoi ne pas simplement ouvrir ChatGPT ou un autre agent conversationnel, me direz-vous ? Déjà parce que je souhaitais éviter au maximum les hallucinations, comme une réponse qui viendrait d’un fil Reddit d’il y a dix ans et ne correspondrait pas ou plus à la réalité. Ensuite, et surtout, parce que c’était l’occasion parfaite de coder un petit truc et d’apprendre en même temps !  C’est comme ça que j’ai décidé de me lancer dans la création d’une application mobile basée sur des LLM et du RAG. Si vous souhaitez jeter un œil au code (encore un peu en chantier, ne jugez pas), il se trouve sur GitHub.

RAG : qu’est-ce que c’est, et pourquoi ?

Pour nos lecteurs et lectrices francophones, mon collègue Clément a fait un chouette article sur l’architecture RAG ainsi qu’un talk au dernier Forum PHP. C’est d’ailleurs cela qui m’a poussé vers ce choix : je préférais guider le modèle en basant ses réponses sur les règles à jour et la liste des cartes existantes plutôt que de risquer une hallucination. Un chatbot classique aurait aussi potentiellement plus de difficultés, avec de simples recherches web par exemple à déterminer l’interaction entre plusieurs cartes.

J’ai donc choisi le corpus suivant, qui en soit devrait permettre de couvrir la majeure partie des cas d’usage classiques :

• la liste complète des règles de Magic à jour, disponible sur le site web du jeu.
• la liste complète des cartes, téléchargeable via l’API de Scryfall en JSON.

Comme ça, désormais, avec un peu de manipulation de prompt, je peux m’assurer que le chatbot ne répondra qu’en basant ses réponses sur les règles et les cartes, en les citant précisément, et qu’il me répondra “Je ne sais pas” plutôt que d’inventer une réponse.

“Attends, tu fournis l’ensemble des règles et des cartes au contexte du LLM à chaque question que tu poses ?”

Fort heureusement non ! C’est là que la partie RAG intervient. On va tout d’abord préparer un pipeline d’ingestion et d’embedding des données :

Pour les règles, l’idée va être de : 

• Télécharger la liste des règles au format .txt
• Parser et séparer le texte en chunks, qui correspondront chacun à une section (ou sous-section) des règles. À noter que ces chunks n’ont pas de taille fixe : ils s’adaptent au paragraphe de la règle, car il est nécessaire d’avoir l’intégralité de celui-ci pour conserver un maximum de sens.
• Insérer ces chunks en base de données.

Pour base de données, j’ai choisi PostgreSQL. Grâce à son extension pgvector, elle nous permettra par la suite de stocker des versions vectorisées de ces règles, et surtout de les requêter pour faire remonter celles qui ressemblent le plus à la question posée !

Une fois insérée, une ligne de règles va pouvoir ressembler à ça en base : 

On voit qu’elles y sont bien découpées par sous-section.

Pour les plus attentifs·ves, vous avez pu remarquer la colonne “embedding” dans la capture d’écran d’au-dessus, c’est l’étape suivante.

L’embedding, c’est le moment où l’on va transformer le corps du texte de la règle en un vecteur qui portera au mieux la sémantique de cette règle, et qu’on pourra plus facilement comparer aux vecteurs des questions posées, pour trouver les règles qui s’approchent le plus desdites questions. Pour réaliser cela, j’ai choisi de faire au plus simple. Pas besoin de créer son propre modèle d’embedding, nous allons appeler l’API d’OpenAI (choix arbitraire ici, il est aussi tout à fait possible de choisir un modèle de Voyage, ou Qwen3 par exemple) avec comme modèle text-embedding-3-small, qui est peu coûteux, et fait largement l’affaire pour nos besoins. Le flux est très simple : récupérer chaque ligne de la table de règles, envoyer le contenu à l’API d’embedding, recevoir un vecteur et l’insérer dans la ligne correspondante.

Concernant les cartes, même principe au départ :

• Récupérer toutes les cartes au format JSON depuis l’API de Scryfall.
• Décoder le body de la réponse, puis effectuer quelques manipulations pour gérer les cas spécifiques (comme les cartes à double face).
• Insérer le tout dans notre table en base de données.

On a finalement une table qui ressemble à ça : 

Par contre ici, on va spécifiquement choisir de ne PAS embedder les cartes en vecteurs ! 

En effet, lorsque des questions concernant des cartes seront posées, on ne veut pas qu’il y ait une tentative de comparaison sémantique sur les titres des cartes. Une question à propos de la carte “Lightning bolt” ne doit pas essayer de remonter plusieurs cartes dont le titre aurait un sens similaire, au risque de suggérer de mauvaises informations au LLM derrière.

Néanmoins, avoir une tolérance au “fuzzy typing” est tout de même important, et ajouter un index Trigram (grâce à l’extension pg_trgm) sur le nom des cartes nous donne cette flexibilité. 

Et le LLM dans tout ça ?

A ce stade, toutes les données sont prêtes. C’était une étape quasi-offline qui nous a permis d’avoir une base de données remplies pour que le LLM ne puisse piocher que dans ces informations. Elle est potentiellement à répéter tous les quelques mois pour avoir les dernières versions des règles et des cartes.

Voici un schéma explicatif du flux final : 

L’application mobile est une petite app React Native / Expo façon chatbot, avec une zone de saisie utilisateur et un espace pour afficher la réponse finale. Je ne rentrerai pas forcément dans les détails ici, mais le code est disponible sur le dépôt pour les curieux·ses !

Lorsque l’utilisateur envoie son message, celui-ci est réceptionné par un simple serveur HTTP en Go avec quelques routes d’API disponibles, dont la principale : POST /chat est un passe-plat classique qui va prendre la question, la passer à un service, et renvoyer la réponse formatée de ce service.

Regardons donc plutôt le service en question :

func (e *Engine) Answer(ctx context.Context, question string) (*Result, error) {
    p, err := e.prepare(ctx, question)
    if err != nil {
        return nil, err
    }
    answer, err := e.llm.Generate(ctx, p.analysis.AnswerLanguage, p.context)
    if err != nil {
        return nil, err
    }
    return &Result{
        Answer:   answer,
        Analysis: p.analysis,
        Rules:    p.rules,
        Glossary: p.glossary,
        Cards:    p.cards,
    }, nil
}

func (e *Engine) prepare(ctx context.Context, question string) (*prepared, error) {
    analysis, err := e.llm.Preprocess(ctx, question)
    if err != nil {
        return nil, err
    }

    vecs, err := e.embed.Embed(ctx, []string{analysis.QuestionEN})
    if err != nil {
        return nil, err
    }
    query := vecs[0]

    rules, err := retrieval.SearchRules(ctx, e.conn, query, e.k)
    if err != nil {
        return nil, err
    }
    glossary, err := retrieval.SearchGlossary(ctx, e.conn, query, e.k)
    if err != nil {
        return nil, err
    }

    var cards []CardContext
    seen := make(map[string]bool)
    for _, name := range analysis.Cards {
        c, err := retrieval.ResolveCard(ctx, e.conn, name)
        if err != nil {
            return nil, err
        }
        if c == nil || seen[c.OracleID] {
            continue // no confident match, or already added
        }
        seen[c.OracleID] = true
        rulings, err := retrieval.Rulings(ctx, e.conn, c.OracleID)
        if err != nil {
            return nil, err
        }
        cards = append(cards, CardContext{Card: *c, Rulings: rulings})
    }

    return &prepared{
        analysis: analysis,
        rules:    rules,
        glossary: glossary,
        cards:    cards,
        context:  buildContext(question, rules, glossary, cards),
    }, nil
}

const q = `
        SELECT rule_number, section_title, body, embedding <=> $1::vector AS dist
        FROM rules
        WHERE embedding IS NOT NULL
        ORDER BY embedding <=> $1::vector
        LIMIT $2`

const q = `
        SELECT oracle_id, name, mana_cost, type_line, oracle_text, similarity(name, $1) AS sim
        FROM cards
        WHERE name % $1
        ORDER BY sim DESC, length(name)
        LIMIT 1`

Une fois toutes ces infos remontées, il ne nous reste plus qu’à appeler un LLM (ici Sonnet 5, pour de meilleures capacités de raisonnement et de synthèse qu’Haïku, et toujours un prix raisonnable) avec elles pour renvoyer une réponse construite uniquement sur ces résultats !
Voici le prompt :

You are a Magic: The Gathering rules assistant for a casual playgroup.

Answer the question using ONLY the provided context (Comprehensive Rules excerpts, glossary entries, and card data). Follow these rules strictly:

– Ground every claim in the context. Do NOT use outside knowledge of the rules, even if you are confident — the context is the single source of truth.

– Cite the specific rule numbers you rely on, in parentheses, e.g. (601.2a). Every rule claim needs a citation.

– If the provided context does not contain enough to answer correctly, say so plainly (« Je ne suis pas sûr d’après les règles récupérées … ») rather than guessing.

– Be concise and concrete. Walk through the interaction step by step when it is subtle.

– Card data is from Scryfall.

– Write in plain text — no Markdown (no #, *, backticks or tables). Use short paragraphs, and simple « –  » bullets only if a list genuinely helps. The answer is shown in a mobile chat bubble.

– Write your entire answer in the language identified by this ISO code: %s.

La réponse du LLM est alors streamée à l’application mobile, et l’utilisateur la voit s’afficher sur son écran

Voici quelques petits exemples :

Mais si je lui demande des infos qui ne matchent pas :

La conclusion du MJ

En partant d’un simple débat de table sur une obscure règle de Magic datant de 1995, on a fini par mettre sur pied un pipeline RAG complet, robuste et résolument moderne.

De l’ingestion des données au requêtage sémantique dans PostgreSQL avec pgvector, en passant par un double niveau de LLM, notre assistant est désormais paré à toute épreuve. Le tout est propulsé par un serveur en Go et une application mobile React Native / Expo.

Ce petit side project de passionné·e démontre aussi que, bien architecturée, l’IA dépasse le stade de gadget sujet aux hallucinations pour devenir un outil de précision redoutable. Vous souhaitez échanger sur vos problématiques de RAG ? Discutons-en !

Cet article, Un RAG Magique !, est paru en premier sur Les-Tilleuls.coop.

L’idée est séduisante, mais sous sa forme la plus simple (un dump statique, versionné, régénéré à la main) elle a un défaut rédhibitoire : il faut penser à le régénérer dès qu’une migration ou une fixture change. En pratique, un tel dump finit toujours par diverger de la réalité. Soit on oublie de le mettre à jour et les tests tournent sur des données périmées, soit on le régénère « au cas où » à chaque fois, et on perd tout le bénéfice.

J’ai eu l’occasion de mettre tout ça en place sur un projet client, une application Symfony dont la CI commençait à traîner en longueur. C’est ce contexte réel qui sert de fil rouge à cet article : nous allons voir comment transformer cette astuce en un vrai cache, automatique, adressé par son contenu, et qui s’invalide tout seul.

Petites précision avant de commencer :

• Sur ce projet, toute l’automatisation (installation, fixtures, build, tests…) passe par des tâches Castor. Les extraits de code de cet article sont donc des tâches Castor, écrites en PHP, que la CI appelle comme n’importe quelle commande.
• Nous utilisons des runners Github Action self-hosted sur un même serveur. Nous pouvons donc jouer avec le cache en partageant directement des dossiers entre les jobs. Mais il reste possible de faire la même chose avec les runners cloud fournis par Github en jouant avec les actions de cache natives.

Le coût qu’on veut éviter

Préparer la base de données de test de notre application n’est pas anodin. À chaque build, il faut :

• Créer le schéma de la base principale en rejouant les migrations Doctrine (118 migrations, 542 requêtes SQL, ~10 s rien que pour ça) ;
• Provisionner une seconde base, « géographique » : nos entités reproduisent le schéma d’un référentiel fourni par un prestataire tiers, mais on n’importe pas sa base complète, bien trop volumineuse. On fait donc un doctrine:schema:create, puis on charge nos propres fixtures pour cette base, dont un jeu de fichiers SQL d’environ 57 Mo ;
• Charger les fixtures métier (avec Alice) ;
• Générer les localisations à partir de ces données géo, puis recalculer les entités qui en dépendent ;
• Réindexer le tout dans Elasticsearch.

Bout à bout, la seule construction de la base tourne autour de 50 secondes. Et comme chaque suite de tests tourne dans son propre job (PHPUnit, Behat, e2e…), on ne veut surtout pas payer ce coût plusieurs fois. Dans notre CI, un unique job prepare-application construit l’application et la base une fois, et tous les autres jobs en repartent.

Mais même une seule fois par build, c’est déjà trop. La grande majorité des pull requests ne touche ni aux migrations, ni aux fixtures, ni aux modèles. Reconstruire la base à l’identique à chaque push, c’est du gâchis.

L’idée : un snapshot adressé par son contenu

Le raisonnement est simple. L’état final de la base est déterministe : à migrations, fixtures et code de chargement identiques, on obtient exactement la même base. Si on sait résumer « tout ce qui détermine la base » en une empreinte, alors on peut :

1. calculer cette empreinte au début de la préparation ;
2. si un dump correspondant existe déjà, le restaurer et s’arrêter là ;
3. sinon, tout reconstruire comme avant, puis sauvegarder le dump sous cette empreinte pour la prochaine fois.

C’est le principe du cache adressé par le contenu (content-addressed), exactement comme Docker le fait avec ses layers. Mais toute la difficulté tient dans une seule question : comment savoir si le dump en cache est encore valable ?

La clé de cache, le cœur du système

C’est la partie la plus intéressante. La clé est un hash SHA-256 du contenu de tout ce qui influence les données. Voici la fonction qui la calcule :

function fixtures_snapshot_key(): string
{
    $root = PathHelper::getRoot();


    $hash = hash_init('sha256');
    hash_update($hash, SNAPSHOT_VERSION);       // bust manuel global
    hash_update($hash, date('Y-m-d'));          // bucket journalier

    // Les dossiers dont le contenu change le jeu de données
    $dirs = [
        $root . '/application/migrations',
        $root . '/application/fixtures',
        $root . '/application/src/Model',
        $root . '/application/src/Location',
        $root . '/application/src/Command/Debug',
        $root . '/application/src/Command/Location',
    ];

    foreach (finder()->files()->in($dirs)->sortByName() as $file) {
        hash_update($hash, substr($file->getPathname(), \strlen($root) + 1)); // le chemin…
        hash_update_file($hash, $file->getPathname()); // …et le contenu
    }

    // La config Doctrine et le lock des dépendances comptent aussi
    $extraFiles = finder()->files()->in($root . '/application/config/packages')->name('doctrine*.yaml')->sortByName();
    foreach ($extraFiles as $file) {
        hash_update($hash, substr($file->getPathname(), \strlen($root) + 1));
        hash_update_file($hash, $file->getPathname());
    }
    hash_update_file($hash, $root . '/application/composer.lock');

    return hash_final($hash);
}

Trois décisions méritent qu’on s’y arrête.

On hashe le contenu, pas un timestamp ni un hash de commit. C’est ce qui rend le cache correct. Le jour où quelqu’un ajoute une migration ou modifie une fixture, le contenu change, donc la clé change, donc on reconstruit, automatiquement, sans que personne n’ait à y penser. À l’inverse, une pull request qui ne touche qu’un template ou une feuille de style retombe sur la même clé et restaure le dump en quelques secondes. Cerise sur le gâteau : ça marche aussi avec des modifications non commitées, puisqu’on lit les fichiers directement sur le disque.

On inclut le chemin des fichiers dans le hash, pas seulement leur contenu. Sans ça, renommer ou déplacer un fichier sans en changer le contenu passerait inaperçu.

Un bucket journalier (date('Y-m-d')) entre dans la clé. Beaucoup de pages et de requêtes dépendent d’une notion de récence : « les articles publiés ces 7 derniers jours », « les annonces qui expirent bientôt »… Les fixtures qui les alimentent sont donc datées relativement à aujourd’hui. Si on figeait le même dump indéfiniment, ces dates vieilliraient : au bout de quelques jours, une entité « publiée il y a 2 jours » se retrouverait datée d’il y a une semaine, sortirait du périmètre testé, et casserait un test qui vérifie un affichage « récent ». En intégrant la date du jour dans la clé, on force au minimum une reconstruction quotidienne, ce qui garde ces données fraîches sans surcoût notable.

Enfin, une constante SNAPSHOT_VERSION permet d’invalider tous les snapshots d’un coup, à la main, si on modifie la logique de génération elle-même. La ceinture et les bretelles.

Restaurer ou reconstruire

Maintenant que la clé est calculée, le reste est mécanique. Le dump vit dans un dossier persistant, partagé entre les jobs et les builds successifs du runner (le même volume qui sert déjà de cache Composer/Yarn) :

$snapshotFile = "$HOME/fixtures-snapshots/{$key}.sql.gz";

if (file_exists($snapshotFile)) {
    // Hit : on restaure et on repart
    run("gunzip -c {$snapshotFile} | mariadb -h mysql -u root -p***");

    return;
}

// Miss : toute la reconstruction habituelle…
// …puis on sauvegarde pour la prochaine fois :
run("mariadb-dump --single-transaction --databases geo_fixtures app_fixtures \
     | gzip > {$snapshotFile}.tmp.$$ && mv {$snapshotFile}.tmp.$$ {$snapshotFile}");

Deux remarques sur ce bout de code.

Redis et Elasticsearch sont exclus du dump. Redis et Elasticsearch sont des datastores à part. J'ai préféré gardé leur fonctionnement actuel, c'est à dire que nous continuons à les recharger systématiquement, aussi bien sur un hit que sur un miss. Ce n’est pas gênant : ces deux étapes ne représentent que quelques secondes dans la CI. Le gros du temps à gagner était ailleurs.

L’écriture du dump est atomique, et ce détail-là fait toute la différence entre un cache qui marche et un cache qui vous cause plus de soucis qu’autre chose. On écrit dans un fichier temporaire unique (.tmp.$$, avec le PID du process), puis on le renomme (mv). Sur nos runners self-hosted partagés, deux pull requests peuvent très bien construire la même clé au même moment, ou un build peut être annulé en plein mariadb-dump. Sans cette précaution, un autre build restaurerait un dump tronqué et échouerait de façon aléatoire, le pire type de bug de CI. Le mv étant atomique sur un même système de fichiers, un fichier final n’existe que s’il est complet.

Le résultat

Voici les chiffres, mesurés sur deux runs réels de notre CI (même machine, avant et après) :

Le provisionnement de la base (la partie qui reconstruisait les schémas, chargeait les fixtures géo et rejouait les fixtures métier) tombe de ~53 s à ~6 s : un gunzip piped dans mariadb, et c’est tout. Le reste de la tâche (rechargement Redis, réindexation Elasticsearch) tourne dans les deux cas, d’où les ~14 s résiduelles.

Pour la grande majorité des pull requests, celles qui ne touchent pas au modèle de données, la préparation de la base passe donc d’une minute à quelques secondes. Et le jour où l’on touche vraiment aux migrations ou aux fixtures, le cache se reconstruit tout seul, sans qu’on ait à y penser, parce que sa clé a changé.

Si vous ne deviez retenir qu’une chose, ce serait celle-ci : ce qui fait la valeur de ce cache, ce n’est ni la compression ni le mariadb-dump, c’est la clé. Un cache n’est utile que s’il est à la fois agressif (il évite un maximum de travail) et correct (il ne sert jamais de données périmées). En dérivant la clé du contenu exact qui produit la base, on obtient les deux d’un coup, et plus personne n’a à se demander « faut-il régénérer le dump ? ». La réponse est dans le hash.

Sylius E-commerce fournit un grand nombre de grilles prêtes à l'emploi, qu'il est possible de personnaliser pour répondre aux besoins de votre projet.

Jusqu'à présent, cette personnalisation reposait principalement sur des surcharges de configuration YAML ou sur les Grid events. Ces approches fonctionnent toujours, mais elles atteignent rapidement leurs limites dès que l'on souhaite introduire de la logique métier ou bénéficier d'une API plus moderne et plus agréable à utiliser.

Avec la sortie du GridBundle 1.16, qui sera intégré à Sylius 2.3, une nouvelle approche devient la solution officielle : les Grid mutators. Les anciennes méthodes sont désormais dépréciées et disparaîtront progressivement.

Un Grid mutator est une classe PHP chargée de modifier une grille existante avant sa construction. Il s'appuie sur le même GridBuilder que les grilles PHP, offrant ainsi une API typée, facilement testable et familière pour les développeurs Symfony.

Dans cet article, nous verrons pourquoi cette évolution était nécessaire, quels sont les avantages des Grid mutators et comment commencer à les utiliser dès aujourd'hui afin d'anticiper les futures migrations de Sylius.

Un peu d'histoire

Historiquement, les grilles de Sylius sont déclarées dans la configuration du GridBundle.

Sylius fournit des fichiers de configuration pour toutes ses grilles dont vous pouvez voir l'un des fichiers de configuration dans cet exemple.

Bien qu'elles soient encore très puissantes, on ne peut pas appliquer d'intelligence à ces grids, comme retreindre les données selon le profil de l'utilisateur.

Les grilles PHP

Mais depuis de nombreuses années, le composant Grid propose de configurer les grilles en utilisant le Grid builder.

<?php

namespace App\Grid;

use App\Entity\Book;
use Sylius\Bundle\GridBundle\Builder\Field\StringField;
use Sylius\Component\Grid\Attribute\AsGrid;
use Sylius\Component\Grid\Builder\GridBuilderInterface;

#[AsGrid(
    name: 'app_book',
    resourceClass: Book::class
)]
final class UserGrid
{
    public function __invoke(GridBuilderInterface $gridBuilder): void
    {
        $gridBuilder
            ->orderBy('title', 'asc')
            ->withFields(
                StringField::create('title')
                    ->setLabel('Titre'),
                StringField::create('author')
                    ->setLabel('Auteur'),
            )
        ;
    }
}

Comme vous pouvez le voir, la DX est très proche d'un Doctrine QueryBuilder ou d'un Symfony FormBuilder.

Les avantages :

• rapprocher les grilles des FormBuilder et QueryBuilder ;
• bénéficier d'une API typée ;
• améliorer l'autocomplétion ;
• simplifier les tests ;
• éviter les manipulations de tableaux YAML.

De plus, nous sommes maintenant capables d'ajouter de la logique métier.

Exemples :

if (!$this->authorizationChecker->isGranted('ROLE_SUPER_ADMIN')) {
    $gridBuilder->removeField('internalNotes');
}

ou encore

if ($this->featureFlag->isEnabled('new_catalog')) {
    $gridBuilder->addField(...);
}

Customiser une grille

Reprenons pour exemple la grille des produits fournie par Sylius.

Je vous propose, à titre d'exemple, de retirer le champ image en voyant d'abord les anciennes méthodes, puis la nouvelle façon officielle.

En modifiant dans la config du package

Comme les grilles de Sylius E-commerce sont actuellement définies dans la configuration Symfony, nous pouvons utiliser un fichier de configuration pour customiser celle-ci.

Nous pouvons ainsi utiliser ce fichier YAML fourni par Sylius Standard et ajouter la configuration suivante :

# config/packages/_sylius.yaml
sylius_grid:
    grids:
        sylius_admin_product:
            fields:
                image:
                    enabled: false

C'est relativement simple dans ce cas basique, mais, je le rappelle cette façon est dépréciée sur le GridBundle 1.16.

Pour introduire la nouvelle façon, commençons d'abord en utilisant également un fichier de configuration Symfony mais cette fois avec un fichier PHP.

<?php
// config/packages/sylius_grid.php

$gridBuilder = GridBuilder::create('sylius_admin_product')
    ->removeField('image')

return App::config(['sylius_grid' => (new GridConfig())->addGrid($gridBuilder)->toArray()]);

Nous utilisons ici la classe App fournie par Symfony 7.4 (ou 8.x) pour modifier la configuration du GridBundle. Il y a de la fioriture dans ce fichier, mais nous voyons déjà l'usage de la méthode removeField du GridBuilder que nous allons pouvoir utiliser dans le Grid mutator.

Cette API de GridBuilder n'est pas réservée aux fichiers de configuration PHP. C'est justement elle qui est exploitée par les Grid mutators.

En utilisant les Grid mutators

<?php

namespace App\Grid\Mutator;

use Sylius\Bundle\AdminBundle\Grid\ProductGridInterface;
use Sylius\Component\Grid\Attribute\AsGridMutator;
use Sylius\Component\Grid\Builder\GridBuilderInterface;
use Sylius\Component\Grid\Mutator\GridMutatorInterface;

#[AsGridMutator(
    grid: 'sylius_admin_product', 
    // ou
    grid: ProductGridInterface::NAME // constante ajoutée sur Sylius 2.3
)]
class RemoveImageFromProductGridMutator implements GridMutatorInterface
{
    public function __invoke(GridBuilderInterface $gridBuilder): void
    {
        $gridBuilder->removeField('image');
    }
}

Comme vous pouvez le voir, nous utilisons simplement un attribut PHP fourni par le GridBundle qui nous injecte directement le GridBuilder.

Sylius 2.3 nous permettra de basculer entre sa configuration de grilles dans la config (dépréciée) et celle en PHP. Vous pouvez utiliser les mutators dans les deux cas, ce qui facilite la transition. Nous allons donc probablement devoir migrer nos surcharges de configuration de grilles vers des Grid mutators, ce qui nous amène au chapitre suivant.

Convertir les grilles

Si vous utilisez des grilles customs, c'est-à-dire des grilles qui ne sont pas fournies par Sylius directement, vous devez créer un nouveau service qui comportera l'attribut AsGrid. Afin de vous faciliter cette conversion, il existe un outil officiel : le Sylius Grid Converter.

Et pour les surcharges de grilles Sylius ? A l'heure où j'écris ces lignes, l'option mutator n'existe pas encore, mais elle va arriver très prochainement !

Et les Grid events ?

Les Grid events sont l'ancienne solution pour customiser vos grilles si vous souhaitez utiliser du PHP plutôt que de surcharger la config en YAML. Il faut dans ce cas écouter l'évènement GridDefinitionConverterEvent.

namespace App\Grid;

use Sylius\Component\Grid\Event\GridDefinitionConverterEvent;
use Sylius\Component\Grid\Definition\Field;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: 'sylius.grid.admin_product', method: 'editFields')]
final class RemoveImageFromProductGridListener
{
    public function editFields(GridDefinitionConverterEvent $event): void
    {
        $grid = $event->getGrid();

        $grid->removeField('image');
    }
}

Cela ressemble beaucoup aux grids mutators, mais vous attaquez directement l'objet Grid definition et non le GridBuilder. Le builder fournit davantage de helpers pour vous aider à construire cette définition. Un autre inconvénient de cet event listener est qu'il faut deviner le nom de l'event.

Comme nous le disions plus haut, ces Grid events sont dépréciées dans Sylius GridBundle 1.16, alors débarrassez-vous en.

Conclusion

Les Grid mutators apportent enfin une manière claire, typée et testable de personnaliser les grilles Sylius. En s'appuyant sur le GridBuilder, ils offrent une API moderne, familière aux développeurs Symfony et bien plus adaptée aux besoins actuels que les anciennes surcharges YAML ou les Grid events.

Avec l'arrivée de GridBundle 1.16 et de Sylius 2.3, ils deviennent la nouvelle approche officielle pour faire évoluer les grilles. L'adoption peut se faire progressivement, puisqu'ils sont compatibles aussi bien avec les grilles déclarées en YAML qu'avec les nouvelles grilles PHP.

Si vous commencez dès aujourd'hui à migrer vos surcharges de configuration et vos Grid events vers des Grid mutators, la transition vers les prochaines versions de Sylius sera largement simplifiée. Vous profiterez également d'une API plus agréable à utiliser, plus facile à maintenir et à déboguer au quotidien.

La sécurité des applications ne dépend pas uniquement du code spécifique développé pour un projet, mais également de la robustesse des briques technologiques fondamentales sur lesquelles il repose. Dans cette optique de sécurisation globale des infrastructures, notre coopérative Les-Tilleuls.coop est heureuse d’annoncer la nomination d’Alexandre Daubois au sein de la PHP Foundation en tant que développeur spécialisé en sécurité. L’annonce officielle est disponible directement sur le site web de la fondation.

La gestion des signalements de sécurité à l’ère de l’intelligence artificielle

Ces derniers mois, la PHP Foundation a constaté une augmentation significative du nombre de rapports de sécurité soumis sur le dépôt officiel php-src. Cette hausse est directement liée à l’utilisation croissante des outils d’intelligence artificielle, qui facilitent la génération automatisée de signalements.

Quelque soit la nature de ces rapports, l’équipe restreinte de la fondation doit obligatoirement traiter et valider chaque soumission. Une fois validée, chaque faille potentielle nécessite d’être classifiée, corrigée, revue puis intégrée au code source. Face à ce flux constant, le besoin de renforcer l’équipe s’est avéré nécessaire pour maintenir le rythme des corrections et traiter les problématiques existantes.

Une expertise technique au service de l’écosystème open source

Alexandre consacrera plusieurs heures par semaine au triage et à la résolution de ces rapports de sécurité entrants. Il s’appuiera pour cela sur son expérience technique de l’écosystème (notamment en tant que membre de la Core Team Symfony et contributeur à FrankenPHP et à PHP core) ainsi que sur sa collaboration préalable avec l’Ecosystem Security Team de la fondation.

Cette intégration s’inscrit dans la continuité de la démarche de Les-Tilleuls.coop, dont les interventions vont de la couche applicative jusqu’au cœur même de. En contribuant directement à la maintenance de PHP, la coopérative participe activement à la pérennité et au durcissement de l’outil technique principal de ses clients et partenaires. Sur ce dernier point, l’implication de la coopérative est structurelle : FrankenPHP, le serveur d’application moderne qu’édite la coopérative, a officiellement rejoint l’organisation GitHub de PHP en 2025 sous le parrainage de la PHP Foundation.

L’ensemble des équipes félicite Alexandre Daubois pour cette nomination qui vient valider son expertise et son engagement en faveur d’un web open source sécurisé. Face à la recrudescence des failles de sécurité exposées dans le monde entier, notre équipe reste à vos côtés pour auditer, sécuriser et fiabiliser vos applications au quotidien.

Cet article, Sécurité PHP : Alexandre Daubois rejoint la PHP Foundation pour renforcer le cœur du langage, est paru en premier sur Les-Tilleuls.coop.