JoliCode blog - les derniers articles

dotAI 2026 : De l’illusion d’autonomie à la réalité du terrain, reprendre le contrôle sur nos agents

2026-09-25T15:42:00+02:00

Nous étions à la dotAI 2026. Et comme il est de coutume, voici notre retour sur ce qu’on a aimé, ce qui s'y est dit et ce qu’on y a appris. Bonne lecture !

L’année écoulée a été marquée par l’essor des architectures multi-agents et des harnesses, ces surcouches qui entourent un LLM pour le transformer en travailleur autonome. Peu à peu, nous délaissons nos IDE au profit des ADE, et passons désormais l'essentiel de notre temps à planifier et à relire du code plutôt qu'à en écrire.

Cette évolution rapide transforme nos métiers au quotidien, et c'était précisément l'enjeu de cette édition : choix d'architecture, mise en place de garde-fous, anatomie des modèles, souveraineté ainsi que cas d’usage concrets. Retour sur les grandes idées qui ont rythmé la journée.

L'IA dans le workflow dev : Reprendre le contrôle sur la boucle de revue

L'arrivée massive des agents dans le quotidien des équipes produit un volume inédit de code et de Pull Requests, déplaçant le véritable goulot d'étranglement de la production de code vers la capacité humaine de relecture. Guillaume Vernade (Google DeepMind) et Greg Qualls comparent ce phénomène au comportement d'un stagiaire junior hyperactif ou d'un cerveau TDAH. Les agents manquent intrinsèquement de mémoire de travail à long terme, saturent leur fenêtre de contexte et interrompent en permanence les développeurs pour valider des micro-décisions ou faire relire du code non testé qui échoue aux CI.

Face à cette saturation, la tentation de se réfugier dans des "usines logicielles autonomes" (dark software factories, l'idée d'une chaîne où l'IA fait tout, toute seule) ou des spécifications purement formelles est une impasse (c'est l'idée d'écrire un cahier des charges ultra-exhaustif pour contrôler l'IA au mot près). Comme l'explique Stanislas Polu (Dust), rédiger et maintenir des spécifications formelles exhaustives devient aussi complexe que d'écrire le code lui-même. Pire encore, lorsqu'un bug survient en production à 4 heures du matin, personne ne peut réparer un système construit comme une boîte noire que plus aucun humain ne comprend. Le code reste le meilleur niveau d'abstraction pour maintenir la compréhension d'une équipe. Pour reprendre le contrôle, la solution réside dans le loop engineering : externaliser les fonctions exécutives de l'agent via des listes de tâches externes persistant hors du contexte, imposer des budgets d'exécution stricts, mettre en silo l'architecture applicative pour isoler l'impact des PRs et exiger l'exécution de tests automatisés complets par l'agent avant toute relecture humaine.

Lorsque ces garde-fous sont en place, les gains de productivité deviennent massifs : chez Anthropic, Ian Massingham indique que Claude rédige désormais plus de 80 % du code mergé avec une productivité multipliée par 8. Cependant, atteindre cette maturité nécessite d'adopter un reaper mindset : la capacité d'une équipe à supprimer sans regret ses anciens outils, RAG complexe ou briques de prompt engineering dès qu'une nouvelle génération de modèles les rend obsolètes.

Sous le capot : interprétabilité, espace latent, post-training et optimisation

Pour comprendre ce qui se passe dans la tête d'une IA, David Louapre (Hugging Face / Science Étonnante) et Aygalic Jara nous font visiter son "cerveau" vectoriel. L'interprétabilité mécanistique cherche à repérer quel concept s'allume dans les réseaux de neurones. En modifiant les vecteurs d'activation internes (le steering), David Louapre a montré en direct (voir le replay de son talk) comment forcer un modèle à devenir obsédé par la Tour Eiffel ! C'est une technique calquée sur la fameuse expérience du Golden Gate Claude d'Anthropic, que vous pouvez d'ailleurs reproduire chez vous via des librairies d'exploration comme TransformerLens.

De son côté, Aygalic Jara (replay de sa présentation ici) a rendu la détection d'hallucinations beaucoup moins abstraite. Au lieu d'analyser le texte final généré par l'IA, son approche consiste à mesurer la "température d'incertitude" directement dans les couches cachées du modèle (l'espace latent) avant même la fin de la phrase. Une méthode qui fait d'ailleurs écho aux récentes avancées majeures sur la détection des hallucinations par entropie sémantique (Nature, 2024).

Lorsque le prompt ne suffit plus, il faut modifier les poids du modèle par le Post-Training. Ziv Ilan (Nvidia) détaille la combinaison du Supervised Fine-Tuning (SFT) sur des jeux de données et du Reinforcement Learning (RL) où l'IA apprend par récompense dans des environnements de test (compilateurs, exécution de code). Mais pour les données structurées, les LLMs classiques échouent car ils lisent les tables mot à mot comme un roman. Kevin Scaman illustre ce problème avec la prédiction de la résiliation client (churn) : face à un tableau de milliers de colonnes désordonnées, un LLM s'emmêle les pinceaux, alors qu'un Large Tabular Model (LTM) regarde la table dans sa totalité (lignes et colonnes) pour extraire instantanément les signaux statistiques. 💡 Ce qu'il faut en retenir & Pour aller plus loin : Le Post-Training en pratique : Si vous souhaitez comprendre comment aligner un modèle avec du RL et du SFT, la documentation de la librairie TRL (Transformer Reinforcement Learning) est un excellent point de départ. Arrêtez d'utiliser des LLMs pour vos fichiers Excel/CSV : Les LLMs sont faits pour le langage naturel. Pour les données tabulaires, les LTMs sont la nouvelle norme. Testez par vous-même : Le dépôt GitHub de TabPFN (PriorLabs) propose des notebooks prêts à l'emploi pour tester la classification sur des données tabulaires en quelques lignes de code Python.

Au niveau du moteur d'exécution, Xuan-Son Nguyen présente les optimisations du projet open source llama.cpp. Pour éliminer la lenteur du "token par token", il s'appuie sur le speculative decoding. Initiée et popularisée notamment par DeepSeek avec des approches comme DFlash. Cette technique consiste à faire prédire plusieurs tokens futurs en parallèle par un petit modèle rapide avant de les valider en un seul passage, ce qui permet de plus que doubler la vitesse d'inférence en local.

Souveraineté, on-device et sobriété : Où et comment faire tourner ses agents ?

Joffrey Thomas et Henry Lagarde (Mistral AI) rappellent les risques stratégiques des API propriétaires SaaS : fuites de données internes, coûts cachés à chaque boucle d'agent et ruptures de production dès qu'un fournisseur modifie son API. L'écart entre modèles ouverts et propriétaires s'étant réduit à quelques mois, ils plaident pour le déploiement de stacks souveraines et auto-hébergées. Ils rappellent également un principe de sobriété essentiel : toutes les tâches ne nécessitent pas un agent LLM. Utiliser de l'OCR traditionnel ou de l'algorithmique classique pour extraire du texte est souvent 100 fois plus rapide, sobre et économique que de lancer un agent gourmand en tokens.

Cette quête de sobriété se retrouve sur les appareils mobiles et objets connectés avec Christian Keller (Meta). Un VLM (Vision-Language Model) est un modèle d'IA capable de comprendre et de raisonner simultanément sur du texte et sur des images. Sur un smartphone ou des lunettes connectées, la contrainte principale n'est pas seulement la mémoire, mais la batterie. Via le framework open source ExecuTorch, Christian Keller prône une architecture en pyramide : faire tourner de tout petits modèles de perception ultra-spécialisés (détection de contours, reconnaissance vocale) directement sur l'appareil, et ne faire appel au cloud ou à un gros LLM généraliste que si la tâche l'exige vraiment.

Faire tourner des modèles géants sur internet, c'est comme essayer de faire tenir un énorme dictionnaire dans la mémoire d'un petit serveur local. Pour y arriver sans faire ramer le réseau, Leo Arsenin (Cloudflare) explique qu'on compresse le dictionnaire (la quantification du cache KV) pour qu'il prenne deux fois moins de place sans perdre ses informations importantes. Et surtout, quand un utilisateur pose plusieurs questions d'affilée, le réseau s'assure de le renvoyer exactement vers le même serveur GPU qui se souvient déjà du début de la discussion, au lieu de tout réexpliquer à un nouveau serveur à chaque fois.

Au-delà du Chatbot : Nouvelles interfaces et cas d'usage métiers

Pour mesurer l'impact de l'IA sur des domaines critiques, Hélène Philippe présente le cas de la radiologie médicale. L'évaluation de l'évolution des tumeurs entre deux scanners nécessite une précision chirurgicale que les VLMs généralistes ne peuvent pas offrir en raison du risque d'hallucinations cliniques. Son équipe a conçu un pipeline d'agents autonomes pilotant des outils de mesure spécialisés, atteignant 67 % de rappel sur le benchmark RADMatch. Cela montre que dans les métiers complexes, l'IA ne remplace pas l'expertise mais orchestre des outils métiers sous un contrôle strict.

Côté web et développement, Patrick Brosset (Microsoft) s'attaque à la fragilité du scraping web. Aujourd'hui, lorsqu'un agent navigue sur un site avec des outils comme Playwright, il clique à l'aveugle et consomme énormément de tokens pour comprendre le DOM. Le nouveau standard W3C WebMCP permet aux développeurs d'exposer directement des fonctions JavaScript exécutables par l'agent. En quelques lignes de code côté client, le site devient nativement accessible aux agents :

// Exemple d'exposition d'un outil WebMCP en JS
document.modelContext.registerTool({
  name: "commander_pizza",
  description: "Commande directement une pizza pour l'utilisateur",
  parameters: { type: "object", properties: { taille: { type: "string" }}},
  execute: async (params) => { return await api.order(params); }
});

Cette approche divise par deux la consommation de tokens, élimine l'instabilité des sélecteurs CSS et accélère drastiquement l'exécution.

Enfin, comment tester un assistant virtuel comme Dr. Doctolib avant de le mettre entre les mains de vrais patients ? Gaëtan Brison (Doctolib) explique que poser des questions isolées ne suffit pas. Pour valider le système, Doctolib crée de faux patients virtuels (des simulateurs) dotés de profils psychologiques et d'historiques médicaux spécifiques. Ces patients virtuels discutent sur plusieurs sessions avec l'IA pour vérifier si elle se souvient bien des allergies mentionnées trois jours plus tôt, si elle réagit correctement en cas d'urgence et si elle maintient une sécurité médicale absolue à 100 % dans le temps.

Accompagner la révolution IA dans les agences tech

Au-delà des conférences, l'accélération de l'IA pose une question centrale à toutes les structures tech : comment accompagner cette transformation sans subir la vague ? L'IA n'est plus un sujet de R&D distant, mais une réalité qui réinvente les métiers du développement, du design et du conseil.

Face à ce changement brutal, la clé réside dans l'accompagnement des équipes. Cela implique de fournir des moyens techniques (crédits de jetons, accès aux modèles), d'aménager du temps effectif dédié à la veille et aux tests, et de renforcer les échanges collectifs (pair-programming augmenté, ateliers pratiques). Il s'agit également d'instaurer une gouvernance transparente avec les clients : définir des chartes d'usage claires sur la confidentialité et s'aligner dès le départ sur le comment et le pourquoi l'IA est intégrée aux projets.

Pour prolonger ces réflexions et suivre l'évolution des pratiques agentiques, la conférence en ligne All Day AI se tiendra le 22 octobre 2026.

Enfin même si l’IA solutionne beaucoup de problèmes, rappelez-vous que toutes les tâches ne nécessitent pas un agent LLM.

D'un ADE à un orchestrator : la construction de PABLO

2026-09-25T11:42:00+02:00

Mes agents sont devenus plus rapides. Mon cerveau, non.

Où nous en étions

Dans mon article précédent, je décrivais mon environnement de travail : un Agent Development Environment, non pas un IDE avec un panneau de conversation greffé, mais un outil construit autour de tâches, de worktrees et d'agents. Je prends une issue, l'ADE ouvre un worktree isolé avec un agent déjà en cours d'exécution, et je dirige cet agent au lieu de taper du code. Par-dessus se trouvent les agents que j'ai affinés pendant des mois, tous en lecture seule par construction ; build est le seul autorisé à modifier le code.

Les gains de ces agents se concentrent en un point : la compréhension. À mon travail, nous n'avons pas d'équipes spécialisées, donc n'importe qui peut se voir confier n'importe quelle tâche : un bug de synchronisation de stock le matin, une fonctionnalité dans une partie du code que je n'ai jamais ouvert l'après-midi, le prochain ticket dans l’application retail. Chaque tâche pourrait être un domaine différent avec ses propres règles métier, et je bascule entre elles trois ou quatre fois par jour. L'agent task-analyst lit le ticket, ses parents et le code associé, puis me livre l'ensemble en une seule lecture.

Comprendre un ticket est une chose, mais une fonctionnalité n'est pas terminée quand la branche est poussée. Entre le code et la production se trouve un second métier fait d'attente et de vérifications : le statut de la CI, les reviews, la QA. Tout cela vit dans GitHub et Jira, en dehors de mes worktrees. J'avais automatisé la réflexion et gardé l'attente.

Cet article porte sur l'outil que j'ai construit pour combler ce fossé : PABLO, une application Symfony. En son cœur se trouve une machine à états, quelque chose que les développeurs PHP livrent depuis une décennie sous un nom moins à la mode que celui qu'utilise l'écosystème IA aujourd'hui.

Les corvées que personne n'a automatisées

Voici à quoi ressemblait réellement mon matin : avant d'écrire la moindre ligne, je devais traiter une checklist mentale sur 5 ou 6 pull requests ouvertes et deux ou trois projets.

La CI est-elle verte ? L'ADE n'affiche le statut que pour la PR du worktree courant ; les autres vivent dans des onglets de navigateur.
Quelqu'un les a-t-il reviewées, et est-il temps de redemander sans devenir la personne qui demande toutes les 90 minutes ?
La QA les a-t-elle planifiées, ou cassées ?
Du feedback est-il arrivé sur le ticket ? Le trouver, recréer un worktree pour une branche supprimée la semaine dernière.
La CI est-elle rouge ? Alors tout ce que les agents font pour moi est inutile tant que je ne relance pas les choses moi-même : remarquer l'échec, créer un worktree, choisir l'agent, le lancer, attendre.

Rien de tout cela n'est difficile, et c'est exactement le problème : chaque point coûte un changement de contexte, la chose que j'avais passée un an à éliminer. Ce ne sont jamais les minutes qui faisaient mal ; ce qui faisait mal, c'était l'entrelacement : vérifier la CI, revenir à une tâche, se rappeler que personne n'a reviewé, revenir encore.

Mes agents avaient éliminé le bruit, rendant le travail facile à comprendre. Mais le coût du suivi de toutes ces tâches restait le mien. Une douzaine de pièces mobiles à travers trois outils, et dans ce système, quelque chose doit poller. C'était moi.

PABLO

Alors j'ai fait : PABLO, pour Personal Assistant for Boring Logic & Operations. L'acronyme est venu après le nom, mais « boring » (ennuyeux) est le mot honnête dedans. Rien de ce que fait PABLO n'est malin : il regarde les pull requests, lit les dates, les compare avec 10 minutes auparavant, et conclut que quelque chose a changé (ou pas).

L'ADE reste l'endroit où je travaille, et PABLO reste un niveau au-dessus, répondant en boucle à une seule question : étant donné l'état de cette pull request, y a-t-il quelque chose qu'un agent devrait faire, et si oui, lequel ? Quand la réponse est oui, PABLO lance automatiquement cet agent via le binaire de l'ADE, dans le bon worktree, exactement comme je l'aurais fait.

Sous le capot se trouve une application console Symfony avec trois points d'entrée :

un binaire pablo ;
la console Symfony ;
un petit dashboard.

Il y a une exception à ce tableau : /pablo-commit-and-pr est une commande OpenCode, pas une commande PABLO. L'agent écrit le message de commit et la description de la pull request (la seule partie du flux où un agent bat du simple code), puis rend la tâche à PABLO, qui déplace la tâche vers l'état draft et prend le relais.

Et enfin, un scheduler en arrière-plan (systemd sur Linux ou launchd sur macOS) met à jour les informations sur les pull requests toutes les cinq minutes.

Cette séparation compte plus qu'il n'y paraît. PABLO ne demande jamais qu'à lancer un agent dans un worktree et à être prévenu quand le run se termine, donc tout ce que PABLO sait de l'ADE tient derrière une seule interface : AgentLauncherInterface. L'interface rend l'ADE remplaçable : si un meilleur arrive le mois prochain, je réécris une classe. Le remplacement a déjà eu lieu une fois : je travaillais avec Orca avant, et je travaille avec OpenChamber aujourd'hui. Un couplage va plus loin : quand l'ADE refuse un worktree, la porte de secours est un opencode run headless. PABLO ne dépend vraiment que d'OpenCode.

Pourquoi PHP pour un daemon en arrière-plan en 2026 ? C'est le langage dans lequel je pense le plus vite, et le seul utilisateur, c'est moi.

Une dernière décision : PABLO ne stocke aucun token et ne parle à aucune API. Tout passe par des CLIs déjà authentifiés sur ma machine (gh, acli, linear, orca, openchamber), donc il n'y a rien à faire tourner ou à fuiter. Quand quelque chose manque, pablo system:doctor le dit, avant qu'un cron n'échoue silencieusement à 3 heures du matin.

L'intelligence a toujours été dans les agents. Ce qui manquait, c'était quelque chose d'assez bête pour tourner toutes les cinq minutes pour toujours sans s'ennuyer.

Graph engineering, ou : une machine à états avec un meilleur nom

Si vous avez lu sur les agents IA récemment, vous avez vu le terme « graph engineering » : modéliser le travail en nœuds et en arêtes au lieu d'un seul énorme prompt. Enlevez le vocabulaire à la mode, et ce n'est qu'une machine à états. Parce que le développement logiciel est brouillon, la machine à états de PABLO doit être flexible. Plusieurs états doivent facilement retomber sur draft, et une commande manuelle peut extraire une tâche d'un état à tout moment. Les frameworks de machines à états lourds exigent de déclarer à l'avance chaque transition autorisée et bloquent tout le reste. C'est trop rigide pour mon workflow, alors j'ai sauté les frameworks et construit un moteur simple : des états, des transitions, et une règle souple sur ce qui est autorisé depuis où.

Dans la plupart des frameworks d'agents, les nœuds sont des étapes de raisonnement (plan, search, summarize, critique), et le graphe vit à l'intérieur de la tâche. Dans PABLO, les nœuds sont les états qu'une pull request traverse dans une vraie équipe : drafted, CI en échec, attente de review, changes requested, attente de QA. Le graphe n'est pas l'agent : c'est le processus dans lequel je travaille déjà. C'est ce qui garde le graphe stable après la prochaine sortie de modèle, les prompts et les modèles vivant à l'intérieur des nœuds.

Donc la machine à états est une table. Littéralement une table, dans une classe :

State::Draft->value => ['emoji' => '📝', 'label' => 'draft',
                        'onEnter' => [self::class, 'enterDraft'], 'polled' => true],
State::CiRed->value => ['emoji' => '🔴', 'label' => 'ci-red',
                        'onEnter' => [self::class, 'enterCiRed'], 'polled' => true],

Chaque ligne de la table déclare comment afficher l'état, ce qui s'exécute à l'entrée, et si le poller le surveille. À côté de la première table, une seconde dit ce que chaque état peut vérifier :

public const POLL_CHECKS = [
    State::Draft->value         => ['checkCiRed', 'checkCiGreen'],
    State::CiRed->value         => ['checkCiGreen'],
    State::ReadyToReview->value => ['checkCiRed', 'checkReviews'],
    State::WaitingReview->value => ['checkCiRed', 'checkReviews'],
    State::NeedsTesting->value  => ['checkFailureSignal'],
];

C'est tout le moteur. Ajouter une étape est une ligne et une méthode, pas un refactoring. Le handler on-enter unique est partagé par le poller, les commandes et les overrides manuels, donc les transitions ne divergent jamais. Même idée pour les trackers : une interface de provider, et la machine à états n'a aucune idée de quel tracker elle parle.

Les états, et ce qui les réveille

Il y a neuf états. Pas de todo, pas d'init, exprès : une issue que je n'ai pas commencée n'a pas de tâche et apparaît simplement dans la liste de ce qui m'est assigné. Entrer dans in-progress crée la tâche, la branche, le worktree et le premier run d'agent ; un merge ferme la tâche depuis n'importe où et supprime le worktree.

État	Entré par	Ce qui se passe à l'entrée
🔨 `in-progress`	`pablo task:start <issue-url>`	crée la branche et le worktree, lance `task-analyst` une fois, plus le script de démarrage du projet s'il en a un
🥱 `waiting`	`pablo task:waiting`	rien, et le polling s'arrête. Revenir en arrière restaure l'état précédent
📝 `draft`	`/pablo-commit-and-pr`	commit, push, draft pull request ouverte
🔴 `ci-red`	poller : la CI échoue	lance `ci-analyst` sur les checks en échec et leurs logs
👀 `ready-to-review`	poller : la CI est verte	marque la pull request prête sur GitHub, puis bascule immédiatement vers l'état suivant
👀 `waiting-review`	atteint depuis le précédent	rien, c'est ici qu'une tâche attend des humains
🧪 `needs-testing`	poller : une review approbatrice est arrivée	enregistre le timestamp qui devient la baseline QA
🔁 `request-changes`	poller : changes requested	repasse la pull request en draft, lance `pr-feedback`
🚨 `testing-failed`	poller : le signal d'échec QA s'est déclenché	repasse la pull request en draft, lance `task-feedback`

La forme de la chose, en graphe :

Regardez les flèches, pas les boîtes : chaque flèche vers draft est une commande que j'ai tapée ; chaque autre flèche est le poller. Je décide quand le travail quitte mes mains ; la machine gère le reste.

Trois détails ont demandé bien plus d'itérations que prévu.

Le premier : ce qui compte comme une review. Mes propres reviews sont exclues : répondre à un commentaire sur ma propre pull request crée une review à mon nom, ce qui me renverrait sinon en draft juste pour avoir répondu à une question. Les reviews de bots sont ignorées sauf whitelist. Seules les reviews postérieures au dernier événement timeline ready_for_review de GitHub comptent (un vrai timestamp, contrairement au verdict du summary), donc une approbation périmée ne peut pas fuiter dans ce tour. La dernière review par reviewer gagne, et tout ce qui n'est pas une approbation bat toutes les approbations : si quelqu'un a pris la peine d'écrire, je lis le feedback avant que la QA ne le fasse.

Le deuxième : exactement un seul chemin de retour vers draft, et c'est une commande. Pas de détection de push : un git push brut ne déplace rien. Cela semble restrictif jusqu'à ce qu'on considère que je pousse des dizaines de fois par jour, souvent juste pour lancer la CI. Une commande explicite est un signal. Un push est du bruit.

Le troisième : ce que j'ai délibérément choisi de ne pas traiter comme des événements. CI pending ne déclenche rien. CI rouge dans needs-testing ne déclenche rien non plus : un build cassé apparaîtra au moment du merge, et interrompre la QA n'aide personne. La moitié de la conception d'une machine à états, c'est choisir ce qui n'est pas un événement, et cette moitié ne reçoit presque aucune attention.

Ce que « vert » veut réellement dire

Deux de ces transitions pendent à une question : la CI est-elle verte ? Cela ressemble à un fait qu'on vérifie. Ça n'en est pas un.

Ma première version : rouge en échec, vert quand tout passe, en attente sinon. Cette règle fonctionnait partout sauf sur le projet où j'avais le plus besoin de PABLO.

Ce projet tourne sous CircleCI, qui publie ses deployment gates sur GitHub comme status contexts : deploy-code-approval-ppr, deploy-code-approval-qlf. Ce sont des gates manuelles sur chaque pipeline, y compris les branches de feature où personne ne clique dessus (nous ne déployons pas en qualification à chaque commit). Elles restent à PENDING pour toujours, ou arrivent en ACTION_REQUIRED, que ma règle comptait comme échec, donc « La CI est-elle verte ? » n'était jamais oui.

Le correctif est une ligne de configuration dans PABLO :

ci:
  ignore_checks: ["approval"]

Tout check dont le nom, le workflow ou le status context contient cette sous-chaîne est retiré de la question entièrement : il ne peut ni rendre le verdict rouge, ni le retenir en attente pour toujours. Deux gates, un mot.

Cette unique clé de configuration m'a forcé à réaliser quelque chose : une CI verte est une règle, pas un fait. Ce que GitHub appelle un « CI check » est en réalité un tas bruyant de tests unitaires, de gates de déploiement manuelles et de bots bavards. Comme aucun outil ne peut deviner magiquement lesquels comptent réellement pour une branche donnée, PABLO pousse cette décision vers le fichier YAML du projet. Pour garder le moteur simple, j'ai ajouté deux autres règles brutales : un dépôt avec zéro check est considéré comme vert, et le matching par sous-chaîne reste volontairement bête.

La seule exception à mon propre dogme

Dans mon article précédent, j'ai fait un point sur le fait que mes agents sont en lecture seule, pas par instruction mais par construction : le frontmatter (voir mon article précédent pour comprendre ce qu'est un frontmatter) refuse edit et write. Les quatre analystes de PABLO suivent la même règle : modèle pas cher et rapide, interdit en écriture.

Mais il y a cinq agents. Le cinquième agent est rebase-conflict-resolver, le seul endroit où j'ai cassé ma propre règle exprès. Toutes les douze heures, un job de sync rebase chaque worktree de mes tâche sur la branche primaire. En cas de conflit, git abandonne et réinitialise le worktree, et un agent est lancé pour refaire le rebase et résoudre chaque conflit. Son frontmatter montre le coût : edit: allow, write: allow, git push*: allow.

Pourquoi le laisser entrer ? La sync est un dry run par défaut. Une clé de configuration transforme le rapport en action : auto_apply: true, posé seulement là où je suis sur que j’ai le moins de risques possibles.

Son rayon d'action est borné comme tout le reste. Il peut écrire du code et pousser, mais toute commande agissant sur le processus plutôt que sur le code (merging, approving, commenting) est refusée. Il peut réécrire ma branche ; il ne peut ni l'approuver, ni la merger, ni parler en mon nom. La permission dangereuse n'a jamais été edit ; c'était agir en tant que moi devant d'autres personnes. Deux garde-fous de plus : une branche sale (fichiers non commités restants) n'est jamais rebasée, et quand l'agent prend le relais d'un rebase, PABLO affiche une commande claire et copiable pour voir la session de l'agent dans OpenCode.

Git fait le travail de sécurité restant. Le push est toujours --force-with-lease, jamais un --force nu. Si j'ai poussé moi-même pendant que le cron tournait, la vérification de lease échoue, le worktree revient en arrière, et le job réessaie douze heures plus tard. Mon push gagne toujours. Quand un conflit nécessite vraiment un humain, l'agent affiche PABLO_CONFLICT_UNRESOLVABLE et ne pousse rien.

La partie honnête : cet agent peut faire des dégâts, contrairement aux quatre autres. J'accepte ce risque parce que tout ce qu'il écrit atterrit dans une pull request que je review avant le merge. C'est mon propre code. En échange, je n'ai pas eu de pull request en conflit depuis un moment.

Tout ne mérite pas un LLM

Dans mon article précédent, je décrivais deux de mes commandes d'agent préférées : des prompts quotidiens qui appelaient le CLI gh, lisaient mes pull requests ouvertes, et utilisaient un LLM pour écrire un message Slack demandant à l'équipe des reviews et de la QA. Ça ressemblait à de la magie à l'époque. Aucune des deux n'a survécu. Elles sont maintenant simplement pablo show:prs : un script PHP lisant depuis le cache du poller, affichant exactement le même markdown prêt pour Slack avec une file de review, un séparateur, et une file de QA. Aucun LLM impliqué.

Le même instinct a façonné le dashboard web, rendu depuis le cache du poller, et cela mène à quelque chose à quoi je ne m'attendais pas. Un outil construit pour orchestrer des agents IA s'avère être des timestamps, des file locks, du CLI parsé et une table de transitions autorisées. L'intelligence est dans cinq fichiers markdown ; tout le reste est de la plomberie sans éclat qui décide quand ouvrir le robinet.

Ce qui a réellement changé

La différence la plus claire : je n'ai pas vérifié moins, j'ai arrêté de vérifier moi-même.

Plus de tour de mes pull requests pour des pipelines rouges, plus de chasse aux reviews. Une liste, pablo tasks ou le dashboard web, me dit ce qui m'attend ; tout le reste est le tour de quelqu'un d'autre.

Le cas de la CI à lui seul a valu la construction de PABLO. La CI passe rouge à onze heures du soir, le poller le remarque en moins de dix minutes et lance ci-analyst dans le bon worktree ; au matin, le diagnostic attend. L'analyse était déjà automatisée par mes agents ; ce qui a changé, c'est que le fait de remarquer et l'attente sont automatisés aussi.

Une tâche complète se passe maintenant ainsi : pablo task:start sur un lien Jira, travailler avec l'agent, /pablo-commit-and-pr, et arrêter d'y penser.

pablo task:start https://acme.atlassian.net/browse/XXX-123

Le temps de cerveau est la ressource

Le coût caché du développement moderne, ce ne sont pas les trois minutes que prend la vérification d'un pipeline CI ; c'est la taxe cognitive de garder cet onglet ouvert à l'arrière de votre tête. Le deep work exige de longues périodes d'attention ininterrompues. Quand vous le fracturez avec un ping-pong administratif : rafraîchir GitHub, courir après des approbations, se demander si la QA a pris votre ticket. Vous ne perdez pas seulement du temps, vous brûlez l'énergie mentale exacte dont vous avez besoin pour résoudre des problèmes difficiles. Je n'ai pas construit PABLO juste pour taper moins de commandes bash, ni pour automatiser pour automatiser. Je l'ai construit pour qu'il serve de bouclier cognitif. En déléguant la bureaucratie de la mise en production à une boucle PHP bête et inlassable, j'ai cessé d'être un routeur humain pour mes propres tâches. Je peux de nouveau être simplement un ingénieur.

PABLO est public

PABLO est public : github.com/korbeil/pablo. Il est construit pour exactement un utilisateur, le workflow de mon équipe, mes CLIs, ma tolérance à l'attente ; rien de tout cela n'est universel. Le publier revient à tendre à quelqu'un un fichier de config bien tenu : quelque chose à lire, à emprunter et à casser. La machine à états est une table précisément pour que la vôtre remplace la mienne sans combat.

Si vous voulez l'essayer, la version courte :

git clone https://github.com/korbeil/pablo && cd pablo
./bin/install.sh        # deps, liens agents/commandes, démarre le scheduler,
                        # finit avec pablo system:doctor
pablo system:doctor     # quel CLI manque ou est déconnecté
pablo project:new       # ajouter un projet ; ou déposer un YAML dans ~/.pablo/projects/

Vous avez besoin de PHP 8.4+ et des CLIs (gh, acli, linear, opencode) chacun déjà authentifié. Puis pablo task:start <issue-url> sur quelque chose de petit, /pablo-commit-and-pr, et arrêtez d'y penser. Si vous préférez un dashboard web au CLI, pablo web le sert sur le port 8321.

Castor 1.8: Windows, self-update, et des binaires vérifiables

2026-09-22T10:41:00+02:00

La dernière fois que nous avons parlé de Castor sur ce blog, c'était pour annoncer la sortie de la 1.0, en octobre 2025. Depuis, notre rongeur préféré a pris un rythme mensuel : une version mineure toutes les quatre à cinq semaines, avec à chaque fois quelques helpers et quelques correctifs, parfois une dépréciation pour préparer la 2.0.

La 1.8 casse un peu ce rythme : 81 commits et 33 pull requests depuis la 1.7.0 de début août, et presque aucun n'ajoute de helper. Le travail est parti dans les recoins de Castor que vous ne regardez jamais : comment il arrive sur votre machine, comment il se met à jour, et ce qui prouve que le binaire que vous lancez est bien celui que notre CI a construit. Ah, et il tourne sous Windows maintenant 🪟.

Ce que vous avez peut-être raté depuis la 1.0.0

Sept versions mineures sont passées depuis l'article sur la 1.0, et certaines méritent mieux qu'une ligne dans le changelog. Au cas où vous en auriez sauté quelques-unes :

PHP 8.4 est le minimum depuis la 1.6, et les binaires statiques embarquent PHP 8.5 depuis la 1.3. Si vous êtes coincés en 8.2 ou 8.3, Castor vous le dit et vous oriente vers le binaire statique ;
#[AsArgsAfterOptionEnd] (1.2) donne à une tâche tout ce qui est tapé après --, tel quel. Pratique pour un castor phpunit -- --filter foobar qui transmet le reste à une autre CLI ;
Le contexte a appris deux choses en 1.4 : input, pour alimenter le stdin d'un process (un mot de passe, plutôt que de le mettre sur la ligne de commande), et supportsInteraction(), pour savoir si vous êtes dans un TTY ou dans une CI avant d'appeler toInteractive() ;
Un fichier .castor.context à la racine du projet définit le contexte par défaut, derrière --context et CASTOR_CONTEXT (1.6). Commitez-le, ou gitignorez-le pour un défaut personnel ;
L'autocomplétion des chemins est devenue plus maligne : #[AsPathArgument] et #[AsPathOption] acceptent un directory et un filter (1.4) ;
dispatch() et event_dispatcher() (1.7) laissent vos tâches dispatcher leurs propres événements, en plus de ceux que Castor émet déjà ;
Le repack n'a plus besoin de jolicode/castor dans votre composer.json (1.3), et --castor-file pointe Castor vers un fichier racine qui ne s'appelle pas castor.php (1.1) ;
Plus petits : terminal() pour la taille du terminal, slug() pour slugifier une chaîne, un lien vers la définition de la tâche dans castor help, et un en-tête silencieux quand Castor tourne dans un agent IA (moins de tokens gachés !).

Le changelog contient le reste. Passons à la 1.8.

Castor sous Windows

Castor fournit un phar Windows depuis les premières releases. Mais un phar a besoin de PHP, et « installer PHP sous Windows » n'est pas aussi fluide que sur les autres plateformes. Les binaires statiques, ceux qui embarquent PHP, n'existaient que pour Linux et macOS.

La 1.8 ajoute castor.windows-amd64.exe à chaque release : un fichier, PHP 8.5 dedans, rien à installer. Déposez-le dans un dossier de votre PATH et c'est terminé :

curl.exe "https://github.com/jolicode/castor/releases/latest/download/castor.windows-amd64.exe" -Lso C:\<un dossier de votre PATH>\castor.exe

Info

Sous WSL, gardez le binaire statique Linux : même si ça fonctionne, le .exe tournerait comme un process Windows via l'interop, ce qui n'est pas ce que vous attendez d'un shell Linux.

Si vous distribuez votre propre CLI construite sur Castor (repack, puis compile), castor:compile a gagné une option --os=windows : vos tâches peuvent devenir un exécutable Windows elles aussi.

La première tentative pour supporter les binaires Windows remonte à octobre 2025, juste après la 1.0, et il a fallu quelques impasses avant d'aboutir à une solution fonctionnelle. Nous construisons les binaires statiques avec static-php-cli, un super outil sous Linux et macOS, mais moins évident sous Windows. Dans le désordre : le runner windows-latest embarque un Visual Studio que static-php-cli ne reconnaît pas (il veut le 2019 ou le 2022), le tar de git bash réécrit les chemins Windows dans votre dos, et MSVC abandonne sur les chemins de sources de plus de 260 caractères. Chacun de ces soucis se corrige en cinq minutes. Chacun coûte aussi un run de CI complet pour être découvert 😅. Si vous aimez ce genre d'archéologie, toute l'histoire est dans la pull request.

Installer et mettre à jour Castor

`castor self-update`

Jusqu'ici, mettre à jour Castor voulait dire relancer l'installeur, ou aller chercher le nouveau phar à la main sur la page des releases. Castor se met maintenant à jour tout seul, comme le font Composer et PHPStan :

castor self-update

Il retrouve comment il a été installé, télécharge le phar ou le binaire statique qui correspond à votre plateforme, et se remplace lui-même. La version précédente est conservée à côté : un --rollback la remet en place si la nouvelle se comporte mal. Vous avez installé Castor globalement avec Composer ? La commande lance composer global update pour vous.

Castor vous disait « une nouvelle version est disponible » depuis deux ans. Il peut enfin y faire quelque chose.

Snapshots

Chaque push sur main publie maintenant une pre-release snapshot. C'est le chemin le plus court pour essayer un correctif avant sa sortie :

castor self-update --snapshot
# ou, en partant de zéro
curl "https://castor.jolicode.com/install" | bash -s -- --version=snapshot

Un snapshot affiche une version du type v1.7.0-14-g4531440 : la dernière release, le nombre de commits depuis, et le commit à partir duquel il a été construit. castor self-update sans l'option vous ramène sur la dernière stable.

Égoïstement, c'est aussi pour nous : « tu peux essayer le snapshot ? » se demande bien plus facilement dans une issue que « tu peux cloner le dépôt et construire le phar ? ».

Des binaires vérifiables

Un task runner tourne sur votre laptop et dans votre CI, et pour certains d'entre vous sur des serveurs de production. Un task runner qui se met à jour tout seul télécharge du code et l'exécute. Ça mérite mieux qu'un curl | bash et un acte de foi.

Chaque phar et chaque binaire statique est maintenant publié avec une attestation d'artefact GitHub : une déclaration signée que ce fichier précis a été construit par le workflow GitHub Actions de Castor, à partir de ce commit. Chaque release contient aussi un fichier SHA256SUMS, attesté lui aussi.

Ensuite, tout ce qui télécharge Castor les vérifie :

l'installeur et self-update comparent le checksum du binaire avec SHA256SUMS ;
si la CLI GitHub (2.49 ou plus) est installée et connectée, les deux lancent en plus gh attestation verify dessus ;
castor:repack refuse un phar Castor sans attestation (il existe un --allow-unattested pour les releases publiées avant les attestations) ;
castor:compile vérifie le checksum de l'archive static-php-cli qu'il télécharge.

Vous pouvez aussi le faire à la main, sur n'importe quel fichier d'une release :

gh attestation verify castor.linux-amd64 --repo jolicode/castor

Astuce

Le script d'installation a eu droit au même traitement : il télécharge dans un fichier temporaire privé, nettoie quoi qu'il arrive, et se lit en entier avant d'exécuter quoi que ce soit. Une connexion coupée en plein milieu ne peut plus lancer la moitié d'un script.

Dans vos tâches

Des helpers plus sûrs

Tant que nous étions dans un mood sécurité, nous sommes repassé sur les helpers avec une seule question : et si cette valeur venait d'une saisie utilisateur ? Une poignée de comportements ont changé. Aucun ne devrait casser une tâche existante, et ils sont tous dans le changelog, mais quelques-uns valent le coup d'être mis en avant :

http_download() ne garde que le dernier segment du nom de fichier envoyé par le serveur : un téléchargement atterrit toujours dans le dossier de votre projet, quoi qu'en dise le serveur ;
ssh_run() échappe le chemin distant, et refuse un hôte, un utilisateur ou un chemin de clé contenant un métacaractère shell ;
zip() avec un mot de passe préfère l'extension PHP zip au binaire zip : le binaire prend le mot de passe sur sa ligne de commande, lisible par tous les utilisateurs de la machine pendant la création de l'archive. zip_binary() le fait toujours, et prévient désormais ;
run_php() passe son script au process enfant en argument, au lieu d'une variable d'environnement que n'importe quel process Castor aurait ramassée sans se poser de question ;
le dossier de cache est créé en 0700, respecte XDG_CACHE_HOME, et le binaire du watcher derrière watch() y est extrait plutôt que dans un chemin fixe de /tmp partagé avec tous les utilisateurs de la machine ;
encrypt_with_password() dérive sa clé avec les limites « moderate » de libsodium (Argon2id, 3 passes, 256 Mio) au lieu des « interactive ». Ce qui a été chiffré par un Castor plus ancien se déchiffre toujours. Ce qui est chiffré par la 1.8 demande la 1.8 ou plus.

Intercepter les signaux

Retour au quotidien. Un classique : une tâche démarre un serveur, et vous aimeriez que CTRL+C arrête le serveur, pas la tâche. Jusqu'ici, le SIGINT arrêtait Castor lui-même, et ce que vous aviez prévu après le serveur ne s'exécutait jamais.

Le contexte a gagné withTrappedSignals(), qui transmet le signal au process en cours à la place :

use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\run;

#[AsTask()]
function serve(): void
{
    // A CTRL+C stops the server, but not the task
    run('./my-server', context: context()->withTrappedSignals()->withAllowFailure());

    run('echo "the server has been stopped"');
}

Sans argument, il intercepte SIGINT et SIGTERM. Passez votre propre liste si besoin, withTrappedSignals([\SIGINT, \SIGQUIT]) par exemple. Les détails sont dans la documentation des signaux.

Monter un paquet distant

Castor a deux façons d'amener des tâches externes dans un projet. import() ajoute des fonctions et des tâches dans votre application. mount() branche un sous-projet entier, avec son propre préfixe de namespace et son propre dossier de travail. Seul import() connaissait les paquets Composer, mount() ne fonctionnait qu'avec des dossiers locaux. Ils partagent maintenant la même résolution :

use function Castor\mount;

mount('composer://vendor/package', 'project:package');

Les tâches du paquet apparaissent sous project:package: et s'exécutent depuis le dossier du paquet installé, exactement comme un mount local. C'est le montage que nous voulions pour une boîte à outils qu'une équipe maintient dans son propre dépôt (un kit de déploiement, une stack Docker) et monte dans chaque projet.

Un correctif est tombé de ce chantier : un import() distant ne change plus le dossier de travail des tâches qu'il définit. Il n'aurait jamais dû. Seul un mount() explicite fait ça.

Une dépréciation pour préparer la 2.0

Celle-ci mérite une minute, parce que vous dépendez peut-être de l'ancien comportement sans le savoir.

Aujourd'hui, seul run() s'exécute dans le dossier de travail du contexte. Tout le reste, fs(), finder() et les fonctions PHP natives comme mkdir() ou file_get_contents(), résout les chemins relatifs depuis l'endroit où vous avez tapé castor. Lancez castor build depuis un sous-dossier : file_get_contents('composer.json') cherche au mauvais endroit alors que run('cat composer.json') non. Pas terrible.

Castor 2.0 changera son propre dossier courant pour le dossier de travail du contexte : un chemin relatif voudra dire la même chose partout. Il suit aussi les blocs with(workingDirectory: ...), et restaure le dossier précédent quand ils se terminent.

Vous pouvez l'activer dès aujourd'hui avec une ligne en haut de votre castor.php :

defined('CASTOR_USE_CHDIR') || define('CASTOR_USE_CHDIR', true);

Ledefined() n'est pas décoratif : un projet monté ou un paquet importé peut définir la constante lui aussi, et un second define() nu lève une erreur.

Ne pas définir la constante est déprécié en 1.8, et le nouveau comportement devient le défaut en 2.0. Pour garder l'ancien comportement encore un moment sans la dépréciation, définissez-la à false.

Avertissement

Une fois activée, un chemin relatif donné en ligne de commande (castor castor:compile foo.phar, un argument de tâche) se résout depuis la racine du projet, pas depuis le dossier où vous avez invoqué castor. Ça ne compte que si vous lancez Castor depuis un sous-dossier, mais vérifiez vos tâches avant de basculer.

Le mot de la fin

Si vous ne retenez qu'une chose de la 1.8 : le binaire que vous lancez est le nôtre, preuve à l'appui, et il se met à jour tout seul. Vos collègues sous Windows ont le même outil que tout le monde. En bonus, CTRL+C fait enfin ce que vous attendez devant un serveur.

La mise à jour tient désormais en une commande :

castor self-update

La liste complète des changements est dans le changelog. Et si l'histoire de static-php-cli vous a donné envie de savoir comment sont construits les binaires Linux, macOS et Windows, dites-le-nous : ça pourrait être le prochain article 🦫

Castor 1.8: Windows, self-update, and binaries you can verify

2026-09-22T10:41:00+02:00

The last time we talked about Castor on this blog was to announce the 1.0 release, in October 2025. Since then, our favorite rodent has settled into a monthly rhythm: a minor version every four to five weeks, with a few helpers and fixes each time, sometimes a deprecation to prepare 2.0.

1.8 breaks the rhythm a bit: 81 commits and 33 pull requests since 1.7.0 in early August, and almost none of them add a helper. The work went into the parts of Castor you never look at: how it lands on your machine, how it updates, and what proves that the binary you run is the one our CI built. Oh, and it runs on Windows now 🪟.

What you may have missed since 1.0.0

Seven minor versions went by since the 1.0 article, and a few of them deserve more than a line in the changelog. In case you skipped some:

PHP 8.4 is the minimum since 1.6, and the static binaries embed PHP 8.5 since 1.3. If you are stuck on 8.2 or 8.3, Castor tells you so and points you to the static binary;
#[AsArgsAfterOptionEnd] (1.2) gives a task everything typed after --, untouched. Handy for a castor phpunit -- --filter foobar that forwards the rest to another CLI;
The context learned two things in 1.4: input, to feed a process's stdin (a password, rather than putting it on the command line), and supportsInteraction(), to tell whether you are in a TTY or in a CI before calling toInteractive();
A .castor.context file at the root of the project sets the default context, below --context and CASTOR_CONTEXT (1.6). Commit it, or gitignore it for a personal default;
Path autocomplete got smarter: #[AsPathArgument] and #[AsPathOption] take a directory and a filter (1.4);
dispatch() and event_dispatcher() (1.7) let your tasks dispatch their own events, on top of the ones Castor already fires;
Repack no longer needs jolicode/castor in your composer.json (1.3), and --castor-file points Castor to a root file that is not named castor.php (1.1);
Smaller ones: terminal() for the terminal size, slug() to slugify a string, a link to the task definition in castor help, and a silent header when Castor runs inside an AI agent (fewer tokens wasted!).

The changelog has the rest. Now, 1.8.

Castor on Windows

Castor has shipped a Windows phar since the first releases. A phar needs PHP though, and "install PHP on Windows" is not something as smooth as other platforms. The static binaries, the ones with PHP baked in, only existed for Linux and macOS.

1.8 adds castor.windows-amd64.exe to every release: one file, PHP 8.5 inside, nothing to install. Drop it in a directory of your PATH and you are done:

curl.exe "https://github.com/jolicode/castor/releases/latest/download/castor.windows-amd64.exe" -Lso C:\<a directory in your PATH>\castor.exe

Info

Under WSL, keep the Linux static binary: even if it works, the .exe would run as a Windows process through interop, which is not what you want from a Linux shell.

If you ship your own CLI built on Castor (repack, then compile), castor:compile gained a --os=windows option, so your tasks can become a Windows executable as well.

The first attempt to add support for Windows binaries dates back to October 2025, right after 1.0, and it took a couple of dead ends before landing. We build the static binaries with static-php-cli, a great tool on Linux and macOS, and a bumpier ride on Windows. In no particular order: the windows-latest runner ships a Visual Studio that static-php-cli does not recognize (it wants 2019 or 2022), git bash's tar rewrites Windows paths behind your back, and MSVC gives up on source paths longer than 260 characters. Each one is a five-minute fix. Each one also costs a full CI run to find out 😅. If you enjoy that kind of archaeology, the whole story is in the pull request.

Installing and updating Castor

`castor self-update`

Until now, updating Castor meant running the installer again, or fetching the new phar by hand from the releases page. Castor now updates itself, like Composer and PHPStan do:

castor self-update

It finds out how it was installed, downloads the phar or static binary matching your platform, and swaps itself out. The previous version is kept next to it: a --rollback brings it back if the new one misbehaves. Installed globally with Composer? The command runs composer global update for you.

Castor had been telling you "a new version is available" for two years. It can finally do something about it.

Snapshots

Every push on main now publishes a snapshot pre-release. It is the shortest path to try a fix before it is released:

castor self-update --snapshot
# or, from scratch
curl "https://castor.jolicode.com/install" | bash -s -- --version=snapshot

A snapshot reports a version like v1.7.0-14-g4531440: the last release, the number of commits since, and the commit it was built from. castor self-update without the option puts you back on the latest stable.

Selfishly, this is also for us: "can you try the snapshot?" is a much easier thing to ask in an issue than "can you clone the repository and build the phar?".

Binaries you can verify

A task runner runs on your laptop and in your CI, and for some of you on production servers. A self-updating one downloads code and runs it. That deserves better than curl | bash and a leap of faith.

Every phar and static binary is now published with a GitHub artifact attestation: a signed statement that this exact file was built by Castor's own GitHub Actions workflow, from this commit. Each release also ships a SHA256SUMS file, attested as well.

Then everything that downloads Castor checks them:

the installer and self-update compare the binary's checksum with SHA256SUMS;
if the GitHub CLI (2.49 or later) is installed and logged in, both also run gh attestation verify on it;
castor:repack refuses a Castor phar without attestation (there is an --allow-unattested for releases published before attestations existed);
castor:compile checks the checksum of the static-php-cli archive it downloads.

You can do it by hand too, on any file of a release:

gh attestation verify castor.linux-amd64 --repo jolicode/castor

Astuce

The installer script got the same treatment: it downloads to a private temporary file, cleans up whatever happens, and reads itself entirely before executing anything. A connection dropped halfway through can no longer run half a script.

Inside your tasks

Safer helpers

While we were in a security mood, we went through the helpers with one question: what if this value comes from user input? A handful of behaviors changed. None should break an existing task, and they are all in the changelog, but a few are worth knowing:

http_download() only keeps the last segment of the file name sent by the server, so a download always lands in your project directory, whatever the server says;
ssh_run() quotes the remote path, and refuses a host, user or key path containing a shell metacharacter;
zip() with a password prefers the PHP zip extension to the zip binary: the binary takes the password on its command line, readable by every user of the machine while the archive is built. zip_binary() still does, and now warns about it;
run_php() passes its script to the child process as an argument, instead of an environment variable that any Castor process would have happily picked up;
the cache directory is created in 0700, honors XDG_CACHE_HOME, and the watcher binary behind watch() is extracted there rather than in a fixed path of /tmp shared with every user of the machine;
encrypt_with_password() derives its key with libsodium's "moderate" limits (Argon2id, 3 passes, 256 MiB) instead of the "interactive" ones. Anything encrypted by an older Castor still decrypts. Anything encrypted by 1.8 needs 1.8 or later.

Trapping signals

Back to daily life. A classic: a task starts a server, and you would like CTRL+C to stop the server, not the task. Until now, the SIGINT stopped Castor itself, and whatever you had planned after the server never ran.

The context gained withTrappedSignals(), which forwards the signal to the running process instead:

use Castor\Attribute\AsTask;

use function Castor\context;
use function Castor\run;

#[AsTask()]
function serve(): void
{
    // A CTRL+C stops the server, but not the task
    run('./my-server', context: context()->withTrappedSignals()->withAllowFailure());

    run('echo "the server has been stopped"');
}

Without arguments it traps SIGINT and SIGTERM. Pass your own list if you need to, withTrappedSignals([\SIGINT, \SIGQUIT]) for instance. The details are in the signals documentation.

Mounting a remote package

Castor has two ways to bring external tasks into a project. import() pulls functions and tasks into your application. mount() plugs in a whole sub-project, with its own namespace prefix and its own working directory. Only import() knew about Composer packages, mount() wanted a local directory. They now share the same resolution:

use function Castor\mount;

mount('composer://vendor/package', 'project:package');

The tasks of the package show up under project:package: and run from the directory of the installed package, exactly like a local mount. This is the setup we wanted for a toolkit a team maintains in its own repository (a deployment kit, a Docker stack) and mounts in every project.

One fix fell out of the rework: a remote import() no longer changes the working directory of the tasks it defines. It never should have. Only an explicit mount() does that.

One deprecation to prepare 2.0

This one deserves a minute, because you may depend on the old behavior without knowing it.

Today, only run() executes in the working directory of the context. Everything else, fs(), finder() and plain PHP functions such as mkdir() or file_get_contents(), resolves relative paths from wherever you typed castor. Run castor build from a subdirectory: file_get_contents('composer.json') looks in the wrong place while run('cat composer.json') does not. Not great.

Castor 2.0 will change its own current directory to the working directory of the context, so a relative path means the same thing everywhere. It follows with(workingDirectory: ...) blocks too, and restores the previous directory when they end.

You can opt in today with one line at the top of your castor.php:

defined('CASTOR_USE_CHDIR') || define('CASTOR_USE_CHDIR', true);

The defined() guard is not decorative: a mounted project or an imported package may define the constant too, and a second bare define() throws.

Not defining the constant is deprecated in 1.8, and the new behavior becomes the default in 2.0. To keep the old behavior a while longer without the deprecation, define it to false.

Avertissement

Once enabled, a relative path given on the command line (castor castor:compile foo.phar, a task argument) resolves from the project root, not from the directory you invoked castor in. It only matters when you run Castor from a subdirectory, but check your tasks before switching.

A final word

If you remember one thing from 1.8: the binary you run is provably ours, and it keeps itself up to date. Your Windows colleagues get the same tool as everyone else. As a bonus, CTRL+C finally does what you expect in front of a server.

Updating takes one command from now on:

castor self-update

The complete list of changes is in the changelog. And if the static-php-cli story made you curious about how the Linux, macOS and Windows binaries are built, tell us: it could be the next article 🦫

From an ADE to an Orchestrator: Building PABLO

2026-09-21T11:42:00+02:00

My agents got faster. My brain did not.

Where we left off

In my previous article, I described my working environment: an Agent Development Environment, not an IDE with a chat panel bolted on, but a tool built around tasks, worktrees, and agents. I pick an issue, the ADE opens an isolated worktree with an agent already running, and I direct that agent instead of typing code. On top sit the agents I refined over months, all read-only by construction; build is the only one allowed to touch code.

The gains from these agents are concentrated in one place: understanding. At my job we have no focus teams, so anyone can be handed any task: a stock synchronization bug in the morning, a feature in code I have never opened in the afternoon, the next ticket in retail. Each task could be a different domain with its own business rules, and I switch between them three or four times a day. The task-analyst agent reads the ticket, its parents and the related code, then hands me the whole picture in one read.

Understanding a ticket is one thing, but a feature is not finished when the branch is pushed. Between code and production sits a second job made of waiting and checking: CI status, reviews, QA. All of that lives in GitHub and Jira, outside my worktrees. I had automated the thinking and kept the waiting.

This article is about the tool I built to close that gap: PABLO, a Symfony application. At its heart sits a state machine, something PHP developers have shipped for a decade under a less fashionable name than the one the AI ecosystem uses today.

The chores nobody automated

Here is what my morning actually looked like: before writing a single line, I had to process a mental checklist across five or six open pull requests and two or three projects.

Is CI green? The ADE only shows the status for the current worktree's PR; the rest live in browser tabs.
Has anyone reviewed them, and is it time to ask again without becoming the person who asks every ninety minutes?
Has QA scheduled them, or broken them?
Has feedback landed on the ticket? Find it, recreate a worktree for a branch I deleted last week.
Is CI red? Then everything the agents do for me is useless until I get things moving myself: notice the failure, create a worktree, pick the agent, launch it, wait.

None of this is hard, and that is exactly the problem: each item costs a context switch, the thing I had spent a year eliminating. The minutes were never what hurt; what hurt was the interleaving: check CI, back to a task, remember no one has reviewed, back again.

My agents had stripped away the noise, making the work effortless to understand. But the cost of monitoring all those tasks was still mine. A dozen moving parts across three tools, and in that system, something has to poll. It was me.

Enter PABLO

So I made the poller: PABLO, for Personal Assistant for Boring Logic & Operations. The acronym came after the name, but boring is the honest word in it. Nothing PABLO does is clever: it looks at pull requests, reads timestamps, compares them with ten minutes ago, and concludes something changed.

The ADE is still where I work, and PABLO stays one level above it, answering a single question on a loop: given the state of this pull request, is there something an agent should be doing, and if so, which one? When the answer is yes, PABLO automatically launches that agent through the ADE CLI, in the right worktree, exactly as I would have.

Under the hood sits a Symfony console application with three entry points:

the pablo CLI;
the console;
a small read-only dashboard.

There is one exception to that picture: /pablo-commit-and-pr is an OpenCode command, not a PABLO one. The agent writes the commit message and the pull request description (the only part of the flow where an agent beats plain code), then hands the task back to PABLO, which moves the task to the draft state and takes over.

And finally, a background scheduler (systemd on Linux, launchd on macOS) wakes the whole thing up every five minutes. State polling runs every ten minutes by default, the worktree sync every twelve. Both cadences live in each project's YAML, and last-run stamps are written only on success, so failures simply retry on the next tick.

That separation matters more than it looks. PABLO only ever asks for an agent to be launched in a worktree and to be told when the run finishes, so everything PABLO knows about the ADE fits behind one interface: AgentLauncherInterface. The interface makes the ADE swappable: if a better one shows up next month, I rewrite one class. The swap already happened once: I was working with Orca before, and I work with OpenChamber nowadays. One coupling goes deeper: when the ADE refuses a worktree, the escape hatch is a headless opencode run. PABLO truly only depends on OpenCode.

Why PHP for a background daemon in 2026? It is the fastest language I think in, and the only user is me.

One last decision: PABLO stores no tokens and talks to no API. Everything comes through CLIs already authenticated on my machine (gh, acli, linear, orca, openchamber), so there is nothing to rotate or leak. When something is missing, pablo system:doctor says so, before a cron job fails quietly at 3 a.m.

The intelligence was always in the agents. What was missing was something dumb enough to run every five minutes forever without getting bored.

Graph engineering, or: a state machine with a better name

If you have read anything about AI agents lately, you have seen "graph engineering": modeling work as nodes and edges instead of one enormous prompt. Strip away the fashionable vocabulary, and it is just a state machine. Because software development is messy, PABLO’s state machine needs to be flexible. Several states need to easily fall back to draft, and a manual command might yank a task out of a state at any time. Heavy state machine frameworks require you to declare every single allowed transition upfront and block everything else. That is too rigid for my workflow, so I skipped the frameworks entirely and built a simple engine: states, transitions, and a loose rule about what is allowed from where. In most agent frameworks, the nodes are reasoning steps (plan, search, summarize, critique), and the graph lives inside the task. In PABLO, the nodes are the states a pull request goes through in a real team: drafted, CI failing, waiting for review, changes requested, waiting for QA. The graph is not the agent: it is the process I already work in. That is what keeps the graph stable after the next model release, with prompts and models living inside the nodes.

So the state machine is a table. Literally one table, in one class:

State::Draft->value => ['emoji' => '📝', 'label' => 'draft',
                        'onEnter' => [self::class, 'enterDraft'], 'polled' => true],
State::CiRed->value => ['emoji' => '🔴', 'label' => 'ci-red',
                        'onEnter' => [self::class, 'enterCiRed'], 'polled' => true],

Each row of the table declares how to display the state, what runs on entry, and whether the poller watches it. Next to the first table, a second table says what each polled state may check:

public const POLL_CHECKS = [
    State::Draft->value         => ['checkCiRed', 'checkCiGreen'],
    State::CiRed->value         => ['checkCiGreen'],
    State::ReadyToReview->value => ['checkCiRed', 'checkReviews'],
    State::WaitingReview->value => ['checkCiRed', 'checkReviews'],
    State::NeedsTesting->value  => ['checkFailureSignal'],
];

That is the whole engine. Adding a step is a row and a method, not a refactor. The single on-enter handler is shared by the poller, the commands and manual overrides, so transitions never drift apart. Same idea for the trackers: one provider interface, and the state machine has no idea which tracker it is talking to.

The states, and what wakes them up

There are nine states. No todo, no init, on purpose: an issue I have not started has no task and just shows up in the list of what is assigned to me. Entering in-progress creates the task, the branch, the worktree and the first agent run; a merge closes the task from anywhere and deletes the worktree.

State	Entered by	What happens on entry
🔨 `in-progress`	`pablo task:start <issue-url>`	creates the branch and the worktree, runs `task-analyst` once, plus the project's startup script if it has one
🥱 `waiting`	`pablo task:waiting`	nothing, and polling stops. Toggling the state back restores the previous state
📝 `draft`	`/pablo-commit-and-pr`	commit, push, draft pull request opened
🔴 `ci-red`	poller: CI is failing	runs `ci-analyst` on the failing checks and their logs
👀 `ready-to-review`	poller: CI is green	marks the pull request ready on GitHub, then settles immediately into the next state
👀 `waiting-review`	reached from the previous one	nothing, this is where a task waits for humans
🧪 `needs-testing`	poller: an approving review landed	records the timestamp that becomes the QA baseline
🔁 `request-changes`	poller: changes requested	flips the pull request back to draft, runs `pr-feedback`
🚨 `testing-failed`	poller: the QA failure signal fired	flips the pull request back to draft, runs `task-feedback`

The shape of the thing, as a graph:

Look at the arrows, not the boxes: every arrow into draft is a command I typed; every other arrow is the poller. I decide when work leaves my hands; the machine handles the rest.

Three details took far more iterations than I expected.

The first: what counts as a review. My own reviews are excluded: replying to a comment on my own pull request creates a review under my name, which would otherwise send me back to draft just for answering a question. Bot reviews are ignored unless whitelisted. Only reviews after GitHub's last ready_for_review timeline event count (a real timestamp, unlike the summary verdict), so a stale approval cannot leak into this round. The latest review per reviewer wins, and anything that is not an approval beats every approval: if someone took the trouble to write, I read the feedback before QA does.

The second: exactly one way back into draft, and it is a command. No push detection: a raw git push moves nothing. That sounds restrictive until you consider that I push dozens of times a day, often just to run CI. An explicit command is a signal. A push is noise.

The third: what I deliberately chose not to treat as events. CI pending triggers nothing. CI red in needs-testing triggers nothing either: a broken build will surface at merge time, and interrupting QA helps nobody. Half of designing a state machine is choosing what is not an event, and that half gets almost no attention.

What "green" actually means

Two of those transitions hang on one question: is CI green? It sounds like a fact you look up. It is not.

My first version: red on failure, green when everything passes, pending otherwise. That rule worked everywhere except the project where I needed PABLO most.

That project runs CircleCI, which publishes its deployment gates to GitHub as status contexts: deploy-code-approval-ppr, deploy-code-approval-qlf. These are manual gates on every pipeline, including feature branches where nobody clicks them (we do not deploy to qualification on every commit). They sit at PENDING forever, or arrive as ACTION_REQUIRED, which my rule counted as failure, so "Is CI green?" was never yes.

The fix is one line of configuration in PABLO:

ci:
  ignore_checks: ["approval"]

Any check whose name, workflow or status context contains that substring is dropped from the question entirely: it can neither turn the verdict red nor hold it at pending forever. Two gates, one word.

That single configuration key forced me to realize something: a green CI is a policy, not a fact. What GitHub calls a "CI check" is actually a noisy pile of unit tests, manual deployment gates, and chatty bots. Because no tool can magically guess which of those actually matter for a given branch, PABLO pushes that decision to the project's YAML file. To keep the engine simple, I added two more blunt rules: a repository with zero checks is considered green, and the substring matching is kept intentionally dumb.

The one exception to my own dogma

In my previous article I made a point of my agents being read-only, not by instruction but by construction: the frontmatter (see my previous article to understand what a frontmatter is) denies edit and write. PABLO's four analysts follow the same rule: cheap, fast model, forbidden from writing.

But there are five agents. The fifth is rebase-conflict-resolver, the only place where I broke my own rule on purpose. Every twelve hours, the sync job rebases each task worktree onto the primary branch. On a conflict, git aborts and resets the worktree, and an agent is launched to redo the rebase and resolve every conflict. Its frontmatter shows the cost: edit: allow, write: allow, git push*: allow.

Why let it in? The sync is a dry run by default. One configuration key turns the report into action: auto_apply: true, set only where I know the shape of the work.

Its blast radius is bounded like everything else. It may write code and push, but every command acting on the process rather than the code (merging, approving, commenting) is denied. It can rewrite my branch; it cannot approve it, merge it, or speak for me. The dangerous permission was never edit; it was acting as me in front of other people. Two more guard rails: a dirty branch (uncommitted files remaining) is never rebased, and when the agent takes over a rebase, PABLO prints a clear, copiable command to see the agent session in OpenCode.

Git does the remaining safety work. The push is always --force-with-lease, never a bare --force. If I pushed myself while the cron ran, the lease check fails, the worktree rolls back, and the job retries twelve hours later. My push always wins. When a conflict genuinely needs a human, the agent prints PABLO_CONFLICT_UNRESOLVABLE and pushes nothing.

The honest part: this agent can do damage, unlike the other four. I accept that risk because everything it writes lands in a pull request I review before merge. That is my own code. In exchange, I have not had a conflicting pull request in a while.

Not everything deserves an LLM

In my previous article, I described two of my favorite agent commands: daily prompts that would call the gh CLI, parse my open pull requests, and use an LLM to write a polite Slack message asking the team for reviews and QA. It felt like magic at the time. Neither survived. They are now simply pablo show:prs: an ordinary PHP script reading from the poller's cache, printing the exact same Slack-ready markdown with a review queue, a divider, and a QA queue. No LLM involved.

The same instinct shaped the web dashboard, rendered from the poller's cache, and it leads to something I did not expect. A tool built to orchestrate AI agents turns out to be timestamps, file locks, parsed CLI output and a table of allowed transitions. The intelligence is in five markdown files; everything else is unglamorous plumbing that decides when to open the tap.

What actually changed

The clearest difference: I did not check less, I stopped checking by myself.

No walking my pull requests for red pipelines, no chasing reviews. One list, pablo tasks or the web dashboard, tells me what is waiting on me; everything else is somebody else's turn.

The CI case alone made PABLO worth building. CI goes red at eleven at night, the poller notices within ten minutes and launches ci-analyst in the right worktree; by morning the diagnosis is waiting. The analysis was already automated by my agents; what changed is that the noticing and the waiting are automated too.

A full task now goes like this: pablo task:start on a Jira link, work with the agent, /pablo-commit-and-pr, and stop thinking about it.

pablo task:start https://acme.atlassian.net/browse/XXX-123

Brain time is the resource

The hidden cost of modern development isn't the three minutes it takes to check a CI pipeline; it's the cognitive tax of keeping that tab open in the back of your head. Deep work requires long, unbroken stretches of attention. When you fracture it with administrative ping-pong: refreshing GitHub, chasing approvals, wondering if QA picked up your ticket. You aren't just losing time, you are burning the exact mental energy you need to solve hard problems. I didn't build PABLO just to write fewer bash commands, or to automate for its own sake. I built it to act as a cognitive shield. By offloading the bureaucracy of shipping to a dumb, relentless PHP loop, I stopped acting as a human router for my own tasks. I get to just be an engineer again.

PABLO is public

PABLO is public: github.com/korbeil/pablo. It is built for exactly one user, my team's workflow, my CLIs, my tolerance for waiting; none of that is universal. Publishing it is like handing someone a well-kept config file: something to read, borrow from and break. The state machine is a table precisely so that yours can replace mine without a fight.

If you want to try it, the short version:

git clone https://github.com/korbeil/pablo && cd pablo
./bin/install.sh        # deps, agent/command links, starts the scheduler,
                        # finishes with pablo system:doctor
pablo system:doctor     # which CLI is missing or logged out
pablo project:new       # add a project; or drop a YAML in ~/.pablo/projects/

You need PHP 8.4+ and the CLIs (gh, acli, linear, opencode) each already authenticated. Then pablo task:start <issue-url> on something small, /pablo-commit-and-pr, and stop thinking about it. If you prefer a web dashboard over the CLI, pablo web serves it on port 8321.

Introducing beberlei/metrics v3.0.0

2026-09-09T13:42:00+02:00

Since 2012, beberlei/metrics has been doing one small job well: giving PHP applications a single, consistent API to send metrics (counters, timings, gauges...) without tying the calling code to a specific backend. Swap StatsD for Prometheus, or send to both at once, and the instrumented code never changes.

Version 3.0 is the biggest release in the project's history. It drops everything older than PHP 8.4, rewrites the core API around strict types, and - the part I'm most excited about - ships four brand-new collectors: Chain, OpenTelemetry, InfluxDB v2 and AWS CloudWatch.

Info

Every breaking change is documented in detail, with before/after examples, in the UPGRADE.md guide. The full list of changes lives in CHANGELOG.md.

What is beberlei/metrics, again?

It's a thin abstraction layer: you ask a Factory for a collector, and you call the same four methods no matter what's behind it.

$collector = \Beberlei\Metrics\Factory::create('statsd');

$collector->increment('foo.bar');
$collector->decrement('foo.bar');

$start = hrtime(true);
// ... do work ...
$milliseconds = (hrtime(true) - $start) / 1_000_000;
$collector->timing('foo.bar', $milliseconds);

$collector->flush();

Collectors that buffer their calls (most of them do) send everything on flush(), which the Symfony bundle wires automatically to kernel.terminate / console.terminate.

As of 3.0, the supported backends are: Chain, CloudWatch, Doctrine DBAL, DogStatsD, Graphite, InfluxDB v1, InfluxDB v2, Logger, Null, OpenTelemetry, Prometheus, StatsD, and Telegraf.

What's new in 3.0

Four new collectors

This is the headline change: four new backends, covering the tools most PHP shops actually run in production today.

OpenTelemetry: records measurements on a MeterProviderInterface, mapping each call to the instrument that matches its semantics: UpDownCounter for measure()/increment()/decrement(), Histogram for timing(), Gauge for gauge().

$collector = \Beberlei\Metrics\Factory::create('opentelemetry', [
    'meter_provider' => $meterProvider,
    'tags' => ['dc' => 'west'], // optional
]);

$collector->increment('foo.bar');
$collector->flush(); // forwards to $meterProvider->forceFlush()

InfluxDbV2: writes points to an InfluxDB 2.x/3.x bucket through the official influxdata/influxdb-client-php client (v3 servers accept the same write API in compatibility mode):

$collector = \Beberlei\Metrics\Factory::create('influxdb_v2', [
    'write_api' => $client->createWriteApi(),
    'tags' => ['dc' => 'west'],
]);

CloudWatch: publishes data points through the PutMetricData API via the official AWS SDK:

$collector = \Beberlei\Metrics\Factory::create('cloudwatch', [
    'client' => $client, // Aws\CloudWatch\CloudWatchClient
    'namespace' => 'my_app',
    'tags' => ['dc' => 'west'], // turned into CloudWatch dimensions
]);

Chain: dispatches every call to a list of other collectors, so the same metric can go to StatsD and a logger without touching the calling code:

$collector = new \Beberlei\Metrics\Collector\Chain(
    \Beberlei\Metrics\Factory::create('statsd'),
    \Beberlei\Metrics\Factory::create('logger', ['logger' => $logger]),
);

$collector->increment('foo.bar');
$collector->flush();

Chain also implements GaugeableCollectorInterface: gauge() calls are silently skipped on the collectors that don't support gauges instead of erroring out.

A stricter, tag-native API

CollectorInterface moves to native type declarations across the board: every method now returns void, and every metric method accepts an array $tags = [] argument directly:

interface CollectorInterface
{
    public function measure(string $variable, int $value, array $tags = []): void;
    public function increment(string $variable, array $tags = []): void;
    public function decrement(string $variable, array $tags = []): void;
    public function timing(string $variable, int|float $time, array $tags = []): void;
    public function flush(): void;
}

timing() now accepts integer or floating-point milliseconds, and every collector preserves the fractional part instead of truncating it on the way to the backend.

TaggableCollector::setTags() is gone: it required collectors to be mutable, which no longer fits a final, strictly-typed API. Tags are now either passed per call, or fixed once in the constructor:

// Before (2.x)
$collector = \Beberlei\Metrics\Factory::create('null_inlinetaggable');
$collector->setTags(['dc' => 'west']);
$collector->increment('foo.bar');

// After (3.0)
$collector = \Beberlei\Metrics\Factory::create('null');
$collector->increment('foo.bar', ['dc' => 'west']);

On top of that, every collector is now guaranteed to never let an error or exception from the underlying client reach the instrumented application: a metrics call should never be the thing that crashes your request.

The Symfony bundle grew up

Every configured collector now gets an autowiring alias, so you inject a specific one without touching the container configuration:

use Beberlei\Metrics\Collector\CollectorInterface;
use Symfony\Component\DependencyInjection\Attribute\Target;

final readonly class MyService
{
    public function __construct(
        private CollectorInterface $collector,              // the default collector
        #[Target('prom')] private CollectorInterface $prom, // a named one
    ) {
    }
}

The beberlei_metrics.collector service alias is gone in favour of injecting CollectorInterface directly, every collector is now tagged kernel.reset (so long-running workers get a clean state on container reset), and the bundle no longer loads an XML services file: collector prototypes are registered programmatically instead.

A full demo application

The examples/ folder now ships a Symfony application wired to every collector, backed by a Docker stack (jolicode/docker-starter + Castor) that provisions Grafana dashboards out of the box for Prometheus, Graphite/StatsD/DogStatsD, InfluxDB v1 and v2, PostgreSQL, and CloudWatch (via LocalStack). One castor start, and every backend already has a dashboard waiting for it.

Housekeeping

The dependencies moved on too: the abandoned corley/influxdb-sdk is replaced by InfluxData's own v1 client, influxdb/influxdb-php, and jimdo/prometheus_client_php by its actively maintained fork, promphp/prometheus_client_php. Every collector class, plus Factory itself, is now final. The test suite runs on native PHPUnit instead of the Symfony bridge, PHPStan and PHP-CS-Fixer are part of CI, and Travis has been replaced by GitHub Actions.

Breaking changes at a glance

Requirement	2.x	3.0
PHP	>= 5.6	>= 8.4
Symfony (bundle)	any (best effort)	>= 6.4
psr/log	`^1.0 \|\| ^2.0 \|\| ^3.0`	`^3.0`

The rest, in short:

The Zabbix and Librato collectors are removed with no replacement: relay through Telegraf or DogStatsD if you still need those backends.
Collector\Collector → Collector\CollectorInterface, Collector\GaugeableCollector → Collector\GaugeableCollectorInterface.
InfluxDB is renamed InfluxDbV1 (it only ever spoke the v1 API), with a new inner client.
DoctrineDBAL now stores a full datetime instead of a date-only column.

This list is not exhaustive: see UPGRADE.md for every change with a before/after snippet.

Migrating from 2.x

For most projects, migration is a matter of renaming a handful of interfaces, moving setTags() calls into constructor arguments or per-call $tags, updating the type of any influxdb entry in your bundle configuration, and removing the zabbix/librato ones. The UPGRADE.md guide walks through each case with real code.

beberlei/metrics 3.0 is on GitHub and Packagist. Try the demo application to see every collector reporting to a live Grafana dashboard in a few minutes.

Special thanks to Benjamin Eberlei for his initial work on this library and for trusting me as a core maintainer. Anyone who knows me knows I'm obsessed with metrics, dashboards, and performance, so working on 3.0 was a real privilege. Fun fact: I actually started this refactoring back in 2024... time flies!

Migrating from Webpack Encore to Vite with Reprise

2026-08-27T13:42:00+02:00

We maintain a high-traffic project for one of our clients: 5 websites served by a single Symfony application, 800 Twig templates, and a React + Tailwind front end that has been built by Webpack Encore for years. A front-end build that was starting to weigh on us: over a minute of Webpack, a NODE_OPTIONS=--max_old_space_size=4096 to keep the heap from blowing up, a 200-line webpack.config.js driving two separate builds, and no hot reload for developers.

Webpack Encore is reaching the end of its life, and Symfony has released its official successor for Vite and Rsbuild: Reprise. The bundle was still marked experimental when we migrated (in 0.7, then 0.8), but it was clearly the direction the framework is taking. So we took the plunge — and since then, 1.0 has been released, with the same backward compatibility promise as Symfony.

In this article, I'm going to tell you how that migration went. We'll first look at what Reprise does and what the mechanical migration involves, then at the real topics that kept us busy: the implicit contract our code base had with Webpack, a collection of "webpack-isms" that only show up at runtime, and finally setting up hot reload in our Docker stack. To make you want to read all the way through: the build went from 75-100 seconds to about fifteen seconds, and we removed 583 npm packages along the way 🎉.

Did you say Reprise?

Unlike Encore, which reimplemented the whole build chain on top of Webpack, Reprise only provides the Symfony glue: generating entrypoints.json and manifest.json, the reprise_entry_* Twig functions, and dev server support. Everything else (Sass, TypeScript, React, code splitting, minification) is handled natively by Vite.

The mechanical migration is quickly done:

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

One vite.config.ts per build, encore_entry_script_tags becoming reprise_entry_script_tags in the templates, and that's pretty much it. On paper, a few hours of work.

The contrast between the two configs illustrates the philosophy nicely. Before, we had 200 lines of Encore's chained API, where every bundler capability has to be declared explicitly:

// webpack.config.js (excerpt)
Encore.setOutputPath('web/build/')
    .setPublicPath('/build')
    .addEntry('js/app', './assets/scripts/main.tsx')
    .addStyleEntry('css/app', './assets/styles/main.css')
    // … 6 more entries
    .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]', /* … */ });

And after? About fifty lines, where Vite does the heavy lifting natively. TypeScript and React no longer need a loader, and the ESLint/Stylelint plugins are replaced by the lint scripts already present in the CI:

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

Did you notice the copyStable on the last line? It isn't provided by Reprise, and that's precisely the subject of the next chapter. Because as we're about to see, the real topic of a bundler migration isn't the bundler config itself.

The implicit contract with Webpack

Vite hashes file names by default, that's its cache-busting model: app.js becomes app-B7fAYn0O.js, and manifest.json maps between the two. Except that our project had exactly the opposite contract, invisible as long as you don't go looking for it:

more than 300 templates reference images with hardcoded paths, along the lines of asset('/build/images/logo.svg'), never going through a manifest;
close to 250 templates use a home-made |inline Twig filter that reads SVGs straight from disk to inline them in the HTML;
cache-busting is global, through a query string, based on a REVISION file produced at deploy time.

In other words, the physical paths of the copied files have to stay stable, and have done so for years. Rewriting 300 templates was obviously out of the question. On top of that, the emails sent by the application also use some of these assets (the fonts in particular), so they have to remain available at the same URLs.

Reprise did offer (in 0.7) a copy option to replace Encore's copyFiles(), but it systematically hashed the names of the copied files, with no opt-out. Encore let you choose your pattern (images/[path][name].[ext]?[hash:8] in our case: stable path on disk, hash in a query string). Our initial answer fit in a forty-line Vite plugin that reproduced Encore's contract:

// vite-plugin-copy-stable.ts (excerpt)
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);
        // The file keeps its logical path…
        this.emitFile({ type: 'asset', fileName: logicalName, source });
        // … and the hash goes into the manifest value, as a query string
        manifestEntries[keyPrefix + logicalName] = `${publicPath}${logicalName}?${hash}`;
    }
    // then merge manifestEntries into the manifest.json emitted by Reprise
}

The result: not a single template modified (apart from the 4 base layouts), the JS and CSS benefit from Vite's native hashing through entrypoints.json, and everything else keeps its stable paths.

This need felt universal enough to propose it upstream: symfony/reprise#81 adds a per-entry hash: false option to copy, which reproduces exactly that contract. It was merged and released in Reprise 0.8 a few days later: our forty lines of plugin gave way to a single line of config, with strictly identical output trees and manifests.

Astuce

Before estimating a bundler migration, take an inventory of who consumes your assets and through which channel (manifest, hardcoded paths, disk reads, CDN). That's where the real workload hides, not in the config.

The webpack-isms that only show up at runtime

Once the build was green, we thought we were in the clear. But the CI was waiting for us, with a lot of failing Behat scenarios. All the problems I'm about to list share the same trait: the build passes, the typecheck passes, and yet the site no longer works at runtime.

`global` doesn't exist

global.Translator = Translator;

Webpack silently aliases global to window. Vite doesn't:

Uncaught ReferenceError: global is not defined

The error happens at the module top level, so the whole bundle dies: not a single line of JS runs on the site any more. The nastiest part: since @types/node is installed, global is perfectly typed and tsc doesn't flinch. The fix is trivial (window.Translator = …), but you still need to know those assignments exist.

Astuce

Search for global. in your code before migrating, it will save you from discovering the problem in the CI like we did.

Dynamic `require()` calls

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

This pattern relies on Webpack's context modules, which embedded the whole icons/ folder to resolve the expression at runtime. Vite doesn't implement them:

Uncaught ReferenceError: require is not defined

The exception blows up on the first render of a component with an icon, and React reacts by unmounting the entire tree: completely blank result pages, without a single message for the user. Since our icons were already copied at stable paths (see above), a direct URL was enough: src={/build/images/icons/${path}}.

The CSS `url()`s that don't follow

With @tailwindcss/postcss, CSS @imports are inlined without rebasing relative paths. A url('../../fonts/brand-400.woff2') written in an imported file ends up as-is in the final CSS, resolves from the root and returns a 404: webfonts and background images gone.

The official @tailwindcss/vite plugin rewrites those same URLs to the emitted asset (url(/build/brand-400-Dm0XPNJo.woff2)), on top of being faster. That's the integration Tailwind recommends when you build with Vite. URL rebasing on the PostCSS side has indeed been fixed several times upstream (see issue #16636, closed since), but a file imported from our own code still replayed the problem for us in 4.3.3. I can only recommend that you stop going through PostCSS if you're using Tailwind v4 with Vite.

The CommonJS vendor file

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

This one is devious: it works in build mode (Rollup's commonjs plugin handles the interop), but crashes in dev only:

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

Vite only prebundles node_modules, so it serves the CJS file from vendor/ as-is to a browser expecting an ES module. The solution is the fos-router npm package, which is exactly the same as the one shipped in the Symfony bundle. As a bonus, the npm package is written in TypeScript: tsc immediately flushed out a dozen window.location = url that had been lying dormant for years (since the vendor module was any, everything coming out of it escaped typing).

Astuce

These four failures share one trait: they leave no trace on the server side. The page returns a 200, the Symfony logs are empty, and the symptom only exists in the browser console: a pageerror, a console.error, or a failed asset request. If you have e2e tests, hook Playwright's pageerror, console and requestfailed listeners into them, if only for the duration of the migration: that's the net that turns those silent bugs into red tests, instead of making you discover them by eye, page by page.

When the site depends on a bundler bug

Here's my favourite anecdote from this migration. After the switch to Vite, a visual regression test stubbornly refused to pass: on one variant of the site, the logo was displayed 60% too big.

We checked everything: the copied SVG file, identical; the CSS rules, identical and in the same order; the HTML, identical. As a last resort, the production Webpack manifest, which told a funny story:

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

A hash in the file name, where all the other copied entries used a query string. And the content of that hashed file was not the requested file: it was another SVG with the same name, located in an icons/ subfolder, with a different CSS class, hence a different size.

The explanation: the images emitted by file-loader (including the entire icons/ folder, pulled in by the dynamic require() seen above) were overwriting the manifest keys of copied files bearing the same name. For years, the site had been serving the wrong file in that spot, and that accidental rendering had become the reference, all the way into our screenshot baselines. Our cleaner Vite build was finally serving the right file… and therefore breaking the test.

We audited the project's 31 name collisions (only one other was visible) and pointed the templates at the right file, explicitly. What I take away from this story is that a bundler is above all a resolution system: changing it reveals every accidental resolution your site depends on without you knowing.

One pixel of difference

Still on the visual regression side: three baselines moved by exactly 1 pixel after the migration. A centred button whose total width (icon sized in em + text) falls half a pixel differently. The cause is the change of CSS minifier: cssnano (configured with calc: false precisely to avoid that kind of rounding) gave way to esbuild.

0.01% of the pixels, invisible to the eye, but perfectly reproducible. Vite's rendering is deterministic down to the pixel from one run to the next: we compared captures taken two days apart, zero pixel of difference.

A corollary that applies to everyone doing screenshot tests: never regenerate your baselines on the dev server. Unminified CSS produces the same rounding discrepancies there, compared to the built rendering your CI compares against, and you'll spend a long time wondering why "it passes locally". On our side, the screenshot update task rebuilds automatically before capturing.

Wiring HMR into the Docker stack

HMR (Hot Module Replacement) is the most visible gain of the migration for developers, and it deserves some attention. A small confession first: with Encore, our "watch" merely wrote files to disk, and the real dev server was designed to run inside Docker for Linux PCs, and on the host machine (so outside Docker) for Macs (because the ones from that era suffered too much). With Vite, we wanted HMR inside the stack, like everything else, and for everyone.

The problems we ran into

We had three problems to solve.

Reaching the server from the browser. We first over-engineered it: a dedicated Traefik route, TLS, service discovery. Then we settled on a far simpler solution, already adopted on another one of our projects: publish the container port on the host and serve at http://localhost:5173. Browsers treat localhost as a secure origin, so no mixed content from an HTTPS page and no certificate to manage.

The lifecycle. Our first setup ran Vite in an ephemeral compose run container. Bad idea: a killed watch leaves behind a zombie that squats port 5173 and keeps overwriting files on the sly. So we defined a dedicated Compose service instead: up always reuses or recreates the same container, which makes the zombie impossible.

# docker-compose.dev.yml (excerpt)
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"

The until node_modules isn't decorative: on the stack's first start, Docker starts the service before yarn install has run, and you don't want a service in a crash loop.

The container pitfalls. Two classics worth knowing. Vite's watcher crawls the whole project by default: with a vendor/ holding 100,000 files, the inotify limit blows up. So you have to exclude it explicitly. And beware of your exclusion patterns: our **/var/**, meant for the Symfony cache, matched /var/www, the container's working directory. The whole project was ignored by the watcher, so HMR was inoperative: the server runs, the page loads, and nothing updates. Anchor your patterns to the project directory:

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

One last refinement, consistency between modes: our build tasks stop the dev server if it's running (otherwise the pages go back to the built assets while an orphan server keeps running for nothing), and the watch task starts it. That way you can't end up in an in-between state without knowing.

What about worktrees?

With AI gradually becoming unavoidable when it comes to gaining efficiency, we work more and more with git worktrees, each with its own complete, isolated Docker stack. That's a native feature of our docker-starter template: the Compose project name is suffixed with the worktree, and all host ports are shifted automatically, which lets several stacks run in parallel.

The Vite server port simply joins that mechanism: each worktree has its own, and two developments running in parallel each have their own HMR.

One detail was left to sort out: Symfony generates absolute asset URLs from the configured base_urls, which know nothing about the shifted port. Inside a worktree, pages were therefore fetching their assets from the main checkout's stack, and it took us a while to figure out why. Our solution: a configurable port suffix in the base_urls, empty by default (and in production):

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

And rather than asking every developer to fill it in by hand, the Castor 🦫 task that starts the stack detects the worktree and syncs the value into a local parameters_override.yaml file (gitignored, meant for personal config):

Info

Our project still uses parameters.yaml files, we haven't migrated to environment variables and the associated .env files.

// Excerpt from the task, called by `castor up`
$line = \sprintf("http.public_port_suffix: ':%d'", get_worktree_ports(get_worktree_name())['https']);
// … created or updated in parameters_override.yaml, without touching the other keys

A new worktree is thus usable with a single command, HMR included.

What we lost along the way

For the sake of completeness, here's what the migration cost us:

svgo minification of the copied images was dropped, to be redone at the source if the weight becomes an issue;
ts-loader ran a static code analysis on every build, but Vite doesn't. So we added a new step in the CI that runs a yarn tsc --noEmit to fill the gap (don't forget it, it's a real safety net that disappears otherwise);
Reprise was experimental at the time of the migration, with an API liable to move from one version to the next. That point has sorted itself out since: 1.0 has been released and adopts Symfony's backward compatibility promise. Our upgrade from 0.8 boiled down to changing the version constraint, without a single line of code to touch.

A migration largely delegated to AI

One last point that may interest you: we let an AI do the bulk of this migration. Not the decision to migrate, nor the structuring choices (the asset contract, the way HMR was wired), but most of the mechanical work and, above all, the iteration on the problems we ran into.

What made that possible isn't the AI itself, it's the safety net that already existed around the project: a complete CI with Behat, PHPUnit and our e2e Playwright tests with screenshots. Every webpack-ism from the previous chapter was caught by a test, not by a human: the 19 red Behat scenarios for the phantom global, the screenshots for the oversized logo or the one-pixel difference, the font 404s in the captures. Every time, the AI could read the report, reproduce the problem locally, fix it, and restart the CI, without us having to step in other than to validate the choices.

Without that test coverage, the same migration would have required a visual review of dozens of pages on every iteration, and we probably wouldn't have dared to delegate that much. It's a good argument, if you were short of one, for investing in visual regression tests before taking on this kind of undertaking.

Conclusion

We've seen in this article that the mechanical migration from Encore to Reprise takes a few hours, and that the real work happens elsewhere: in the implicit contract your code base has with its bundler, and in the handful of webpack-isms that only reveal themselves at runtime. That's where you should look if you have to estimate such a migration.

The result is worth it: our build is five to six times faster, we're back on node's default config with 1 GB of heap (instead of the 4 GB previously required), we removed 583 npm packages, the config has been divided by three, and developers finally have hot reload with React fast refresh. As a bonus, it also means deployment is more than a minute faster, which is appreciable!

Being an early adopter of an experimental bundle also has its upsides: the main point of friction we ran into ended up as an upstream contribution, merged and released within a few days. The next team migrating a site with frozen asset paths will have a config option where we initially wrote a local plugin.

Migrer de Webpack Encore vers Vite avec Reprise

2026-08-27T13:42:00+02:00

Nous maintenons, pour un de nos clients, un projet à fort trafic : 5 sites servis par une même application Symfony, 800 templates Twig, et un front React + Tailwind buildé depuis des années par Webpack Encore. Un build front qui commençait sérieusement à peser : plus d'une minute de Webpack, un NODE_OPTIONS=--max_old_space_size=4096 pour ne pas exploser la heap, un webpack.config.js de 200 lignes pilotant deux builds distincts, et aucun hot reload pour les développeurs.

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.

Astuce

Avant d'estimer une migration de bundler, inventoriez qui consomme vos assets et par quel canal (manifest, chemins en dur, lecture disque, CDN). C'est là que se cache la vraie charge de travail, pas dans la config.

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.

Astuce

Cherchez global. dans votre code avant de migrer, cela vous évitera de découvrir le problème en CI comme nous.

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

Astuce

Ces quatre pannes ont un point commun : elles ne laissent aucune trace côté serveur. La page répond 200, les logs Symfony sont vides, et le symptôme n'existe que dans la console du navigateur : un pageerror, un console.error, ou une requête d'asset en échec. Si vous avez des tests e2e, branchez-y les listeners pageerror, console et requestfailed de Playwright, ne serait-ce que le temps de la migration : c'est le filet qui transforme ces bugs silencieux en tests rouges, au lieu de vous les faire découvrir à l'œil nu, page par page.

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

Info

Notre projet utilise encore des fichiers parameters.yaml, nous n'avons pas migré vers des variables d'environnement et les .env associés.

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

SimHash : trouver les pages qui se ressemblent

2026-08-18T09:42:00+02:00

Il y a quelques semaines, j'ai eu besoin de détecter du contenu dupliqué dans le crawler de redirection.io. Pas du dupliqué à la virgule près, ça c'est facile, mais du dupliqué « en gros, c'est la même page ». J'aurais pu utiliser des embeddings avec un LLM, mais il me fallait quelque chose de rapide et de gratuit. J'ai finalement utilisé SimHash, un algorithme qui date de 2002 et qui tient en trente lignes de PHP.

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 :

Implémentation	Temps
Boucle naïve	0,752 s
Kernighan	0,378 s
`substr_count(decbin(...))`	0,084 s

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 :

	base	promo	ville	femme	autre
base	0	5	2	5	27
promo	5	0	5	10	22
ville	2	5	0	7	27
femme	5	10	7	0	28
autre	27	27	28	28	0

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 :

Distance (sur 63 bits)	Interprétation
0	Même contenu, ou différences infimes
1 à 3	Quasi-doublon
4 à 10	Documents apparentés
~31	Aucun rapport

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 :

Longueur du document	Distance après un mot changé
20 mots	8
50 mots	3
100 mots	5
200 mots	4
500 mots	1
1 000 mots	1
2 000 mots	0

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 ?

Quand le cache de Symfony ralentit votre application...

2026-08-12T10:42:00+02:00

Mettre une valeur en cache, c'est toujours plus rapide, non ? Et bien, pas forcément ! Cet article partage l'analyse d'un problème de performance causé par la protection "anti-stampede" du composant Cache de Symfony, et sur la manière dont nous l'avons diagnostiqué puis corrigé.

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:

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 ;
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!

JoliCode blog - les derniers articles

dotAI 2026 : De l’illusion d’autonomie à la réalité du terrain, reprendre le contrôle sur nos agents

L'IA dans le workflow dev : Reprendre le contrôle sur la boucle de revue

Sous le capot : interprétabilité, espace latent, post-training et optimisation

Souveraineté, on-device et sobriété : Où et comment faire tourner ses agents ?

Au-delà du Chatbot : Nouvelles interfaces et cas d'usage métiers

Accompagner la révolution IA dans les agences tech

D'un ADE à un orchestrator : la construction de PABLO

Où nous en étions

Les corvées que personne n'a automatisées

PABLO

Graph engineering, ou : une machine à états avec un meilleur nom

Les états, et ce qui les réveille

Ce que « vert » veut réellement dire

La seule exception à mon propre dogme

Tout ne mérite pas un LLM

Ce qui a réellement changé

Le temps de cerveau est la ressource

PABLO est public

Castor 1.8: Windows, self-update, et des binaires vérifiables

Ce que vous avez peut-être raté depuis la 1.0.0

Castor sous Windows

Installer et mettre à jour Castor

castor self-update

Snapshots

Des binaires vérifiables

Dans vos tâches

Des helpers plus sûrs

Intercepter les signaux

Monter un paquet distant

Une dépréciation pour préparer la 2.0

Le mot de la fin

Castor 1.8: Windows, self-update, and binaries you can verify

What you may have missed since 1.0.0

Castor on Windows

Installing and updating Castor

castor self-update

Snapshots

Binaries you can verify

Inside your tasks

Safer helpers

Trapping signals

Mounting a remote package

One deprecation to prepare 2.0

A final word

From an ADE to an Orchestrator: Building PABLO

Where we left off

The chores nobody automated

Enter PABLO

Graph engineering, or: a state machine with a better name

The states, and what wakes them up

What "green" actually means

The one exception to my own dogma

Not everything deserves an LLM

What actually changed

Brain time is the resource

PABLO is public

Introducing beberlei/metrics v3.0.0

What is beberlei/metrics, again?

What's new in 3.0

Four new collectors

A stricter, tag-native API

The Symfony bundle grew up

A full demo application

Housekeeping

Breaking changes at a glance

Migrating from 2.x

Migrating from Webpack Encore to Vite with Reprise

Did you say Reprise?

The implicit contract with Webpack

The webpack-isms that only show up at runtime

global doesn't exist

Dynamic require() calls

The CSS url()s that don't follow

The CommonJS vendor file

When the site depends on a bundler bug

One pixel of difference

Wiring HMR into the Docker stack

The problems we ran into

What about worktrees?

`castor self-update`

`castor self-update`

`global` doesn't exist

Dynamic `require()` calls

The CSS `url()`s that don't follow

`global` n'existe pas

Les `require()` dynamiques

Les `url()` CSS qui ne suivent pas

Pourquoi pas `hexdec()` ?

`LockRegistry`, la protection anti-stampede de Symfony

Oui, les workers CLI utilisent `LockRegistry`