JoliCode blog - les derniers articles

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!

L'Agent Development Environment : une nouvelle unité de travail

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

Régulièrement, quelque chose arrive et change ce que « écrire du code » veut dire. Cette fois, il se pourrait que ça ne veuille plus dire écrire du tout.

D'où je viens

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

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

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

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

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

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

La vague des LLM

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

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

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

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

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

Entrée en scène de l'ADE

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

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

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

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

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

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

Mon setup au quotidien

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

Orca lui-même

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

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

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

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

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

Mes agents

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

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

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

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

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

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

### Investigating the codebase

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

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

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

Les permissions dans OpenCode

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

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

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

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

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

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

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

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

Quand Orca et les agents s'emboîtent

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

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

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

Mes commandes

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

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

Mes skills

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

La philosophie des permissions

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

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

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

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

Pourquoi ça me rend productif

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

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

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

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

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

Conclusion

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

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

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

The Agent Development Environment: A New Unit of Work

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

The Agent Development Environment: A New Unit of Work

Every few years, something comes along that changes what "writing code" means. This time, it might stop meaning writing at all.

Where we come from

What follows is my own path, not a history of PHP. Other people lived those same years very differently. My story starts in 2013, when PHP was not the obvious choice it would later become, so I learned C: pointers, manual memory management, segfaults. Then I moved to Objective-C for iPad development, with a bit of Smalltalk on the side, maintaining a legacy internal website. During that time, I fell in love with the web. I joined a company doing PHP, a language that was completely new to me. The stack there was PHP 5.x, no autoloading, barely any libraries, and no framework. Composer and Symfony already existed, we just did not use them. Every project started from scratch, and we reinvented a lot of wheels. It was harder, sure, but it was just how things were for us. Then I moved to Paris, and that is where I discovered frameworks. Laravel and Symfony were both making waves, and I started with Laravel. Suddenly, an entire community had already solved the problems I used to solve alone. For me, frameworks were not just tools; they were a multiplier. Eventually I moved on and adopted Symfony, which I still use and love today. Everything you need can be done with it, and even more. Looking back, one pattern holds: I followed where the tech led me. Each era changed the unit of my work: from lines of C, to libraries, to frameworks. This article is about what I think is the next step, the one we are living in right now.

The LLM wave

For years, frameworks felt like the end of that road. Then a new kind of tooling appeared.

The first spark came in 2021, with GitHub Copilot: auto-completion on steroids. You would start a line, and the machine would finish it. It felt like magic. In 2023, Cursor raised the bar: still auto-completing our code, but with far more built in, like chatting with your codebase, inline edits, and whole chunks of code written from a simple instruction. And since 2025, Claude Code has taken the lead on AI agents, with models capable of delivering full features on their own.

The progression is clear: first a tool that completed our code faster, then a tool that wrote some of it for us, and now agents that build entire features. The unit of work changed again: from frameworks to features.

This wave did not stay in the hands of a few big players. Competition exploded, and open-weight models joined the race: DeepSeek, in particular, shook the AI world by delivering frontier-level performance at a fraction of the cost, and it was far from alone. For us developers, this changed the question of access: powerful models are no longer locked behind a single provider. You can pick the model that fits each task, mix providers in the same workflow, or run smaller models on your own hardware with tools like Ollama.

Each of these waves redefined a piece of our job. But in my opinion, this was only the opening act: the real change is not the agent itself, it is the environment we run it in.

Enter the ADE

The first hint came from Cursor itself. With Cursor 2.0, it started hiding the things we thought were essential: the file tree, the git panel, the editor front and center. What remained was a conversation with an agent. Without naming it, that is what an ADE is: an Agent Development Environment. Where an IDE is built around you editing files, an ADE is built around you directing agents, and chatting with them to build products.

The name is new and not broadly used yet, but I like it, precisely because it draws a clear line between how we develop today with IDEs and what is coming next.

After Cursor, Jean went deep into the ADE paradigm. The reasoning is simple: if agents are busy working for you, you should be able to run several tasks at once. So Jean ships native git worktree management: each task lives in its own isolated copy of the repository. Combined with GitHub pull request and issue integration, you can pick an issue, get a fresh worktree, and have an agent working on it in seconds.

Then a coworker mentioned Orca to me. It does everything Jean does, with even more integrations: Jira and Linear are supported natively, so while working on something I can grab an issue and immediately spin up a worktree to start on it. Each task gets its own terminal, browser, and context, and it is bring-your-own-subscription: Claude Code, Codex, OpenCode and others, side by side.

Nothing from the agent wave is lost along the way, either. Agents, commands, skills: everything we built carries over. An ADE does not replace that toolbox, it stands on top of it, and that only makes it stronger.

This is why an ADE is not "an IDE with an AI panel bolted on". The primitives are different: not files and buffers, but tasks, worktrees, and agents. The IDE assumed one developer, one working copy, one thread of work. The ADE assumes you are orchestrating several at once.

My daily setup

One disclaimer before we dive in: my main CLI agent nowadays is OpenCode, so every example in this section is focused on it. But nothing here is OpenCode-specific: most of these tips translate directly to Claude Code, Codex, or whatever agent you prefer.

Orca itself

Orca ships with many features designed to make your life better, and the first one is issue-tracking integration: GitHub issues, Jira, and Linear are all supported. From there, you can pick a new issue or check the ones you are already working on, read every detail, and create a worktree straight from it. When you do, the default prompt is the issue link (this will help us a lot later on, stay tuned).

When you juggle several features or issues at once, each in its own worktree, it quickly gets hard to remember what you have to do on which one. That is why Orca gives you a kanban board. Every column is fully customizable; in my case I have four:

"Todo" holds the features and issues to tackle;
"Waiting" is for blocked tasks where I need feedback from whoever is linked to the issue;
"In progress" is what I am actively working on;
"Draft" is for tasks where I opened a draft pull request on GitHub. Since I work on many features at once, I rarely run the full test suite locally, so I let the CI do it on the draft PR and come back to check the results (when there are too many failures, I do run the tests locally). Once everything is green, I open the PR for review and remove the local worktree.

Following on my "Draft" state, another thing I like about Orca is the right dock. It contains a project file explorer where you can edit files directly, like you would in an IDE. A second tab lists all agent sessions for the current worktree: when I switched to Orca, it immediately found all my OpenCode sessions running at that time, so I could catch up without losing anything. A third tab covers git: modified and staged files, and you can commit from there (or ask your agent to do it). And the last tab shows the GitHub Actions runs for your pull request, so when I have a draft PR, I can check how the CI is doing without ever leaving Orca.

Those are the three features I use the most, but there are plenty of others. Quick commands let you prepare full scripts to run on a worktree: I have an "Install deps" command that installs everything required when I need tooling like PHP CS Fixer or PHPStan. There is also the mobile integration, which opens a local network tunnel so you can reach your Orca agents from your phone (add a VPN and it works from anywhere; I have used it from time to time at the gym). And this is only a fraction of what Orca offers, there is a lot more to discover.

My agents

Agents are where I invested the most. One more disclaimer: I mainly work with Jira, so some agents below are Jira-flavored, but they can easily be swapped to GitHub issues or Linear if required. Here is the full breakdown of what my agent picker looks like:

build is the built-in agent that makes changes. It is the only agent in this list allowed to touch the code.
plan is the other built-in one, used to simply plan things.
heavy-plan is the same as plan, but backed by a more performant model: if plan runs on a Sonnet-class model, this one runs on an Opus equivalent. I keep it for large or risky work.
jira-analyst takes a Jira link, looks at all the issue details, its parents, and the opened PRs about these issues, then sums up what is asked, what was already done, and what could be done in the code. This is my number one starting point, 95% of the time.
jira-feedback covers the next round: QA tested one of my pull requests and found an error. This agent rechecks the Jira ticket from its link, finds the related PR, checks out the branch locally, and tries to understand the feedback and make first guesses.
pr-review-planner steps in when a PR is open for review and someone left comments: it reads them all and proposes how I could fix them. Addressing a review stops being an archeology session and becomes executing a checklist.
pr-reviewer is for the other side of reviews: when I have a big PR to review, I always review it myself, and in parallel I run this agent so an AI review can catch things I could, maybe, have missed.

You may notice a pattern: apart from build, these are all analysis agents. They read, summarize, and plan, but they do not touch the code. That constraint is baked into the agent definition itself. Here is an abridged extract of jira-analyst:

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

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

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

### Investigating the codebase

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

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

The read-only rule is not just a promise in the prompt: the same file carries a permission block that makes edits impossible in the first place.

Permissions in OpenCode

OpenCode resolves every tool call to one of three actions: allow runs it without asking, ask prompts me first, and deny blocks it outright. What matters here is that it starts from permissive defaults, most permissions are allow out of the box, so an analysis agent is only read-only if you say so explicitly. In the agent frontmatter, that looks like this:

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

The permission key is keyed by tool name: read, glob, grep, list, bash, task, skill, webfetch, websearch. You go through them one by one and decide what each is allowed to do, and a "*" entry sets the default for everything you did not name. Note that edit is the one exception to the one-key-one-tool rule: it covers everything that writes to disk, so edit, write, patch and multiedit all sit behind that single deny. The rest stay open, so the agent can still read, grep, glob and run the commands it needs to investigate, and that is all it will ever do.

The bash block is where it gets interesting. Rules are matched by pattern and the last matching rule wins, so the catch-all goes first and the specific rules come after it:

bash:
  "*": deny           # default: nothing runs
  "git *": allow      # ...except git
  "git push *": deny  # ...but never push

Read top to bottom, each line narrows or reopens the one above. Flip the order and the catch-all silently swallows everything else. One last gotcha: patterns match the parsed command, arguments included, so "git" alone only matches a bare git, anything with arguments needs the wildcard.

That block is what turns "please only analyze" into something the agent cannot get around, even if the prompt drifts or the ticket tries to talk it into something else.

And since these agents only analyze, they do not need the most expensive model with high creativity: a cheap, fast model at low temperature does the job, deterministically. If you want the full prompts, all my agents are available in this gist.

When Orca and the agents click together

Remember the Orca detail I told you to keep in mind: when you create a worktree from an issue, the default prompt is the issue link. This is where it pays off. Since jira-analyst and jira-feedback both take an issue link as their input, I have almost nothing to do. I select my issue in the Jira integration of Orca, it opens a new worktree, starts my agent, and copies the link. All that is left for me is to switch to the right agent and run it. From "I will take this ticket" to "an agent is analyzing it in an isolated worktree", there are a couple of clicks and zero copy-paste.

The same trick works from the other side, once the worktree is already gone. When a PR comes back to life, because QA found an error or a reviewer left comments, I create a new worktree from the PR itself, in the GitHub integration of Orca this time. The agent opens with the PR link as its prompt, I run jira-feedback or pr-review-planner on it, and everything else is done automatically.

To give you an idea of the rhythm this all creates: at the start of the day, I check whether my current draft PRs have any errors. If they do not, I take up to three or four Jira issues and start my jira-analyst agent on all of them, then usually do some code review while they run. When an agent is done analyzing, a big read awaits me: the idea is to focus the most on the first task to finish, send it off to execution, then take the second one while the first is busy, and so on, until I have no more tasks to do and pick up new issues.

My commands

Where agents carry a full role, commands are closer to recipes: small, repeatable prompts I run on demand. Two of mine are general purpose:

/commit-and-pr is kind of straightforward: it generates a commit message and a pull request description. If the current repository has a GitHub template available, it uses it as the base for the PR description.
/activity fetches all my activity from Jira and GitHub over the last 24 hours, to help me not forget stuff during my daily stand-ups.

The other commands are heavily related to my projects, and to understand them you need to know one thing about our workflow: a PR is opened, the PR is reviewed, then it is put in a milestone so it gets deployed to a qualification environment for testing purposes. That is how I came up with these commands:

/github-awaiting-review fetches all pull requests that are open and waiting for a review, as a list ready for me to copy into Slack.
/github-milestone-triage fetches all pull requests that have their review and need to be tested, and outputs a nice list I can copy into Slack too.
/milestone-build takes a milestone link as argument, gathers all the PRs from that milestone, and creates a release branch so we can deploy every change in it. It also handles the merge conflicts along the way.

My skills

For skills, I have no custom-made ones. I use a catalogue instead: most of mine come from superpowers-symfony, a collection of Symfony-focused skills, completed by a few project-related ones describing, for example, how a commit message or a pull request description should be written on each project. This is also what keeps the commit-and-pr command simple: the command does not explain how to write anything, it just does the work, and the conventions come from these skills. That is not much, and it is on purpose: I always felt we reach for skills too often, when what we really want is a command or an agent.

The permission philosophy

You may have guessed it from the agent breakdown: all my AI tooling is read-only by default, and build is the only agent allowed to write code. That is not an accident, it is the rule everything else follows from. Agents propose, the human decides. Consider it my counterpoint to the "YOLO agents" trend of letting an agent run wild with every permission granted.

Behind that rule sits a conviction: all code generated with any AI is owned by you. The model wrote it, but your name is on the commit. Being AI-generated does not exempt a single line from review: you still have to check what it does, and how it does it, exactly like code you would have written yourself.

The best way to keep that review bearable is to invest before the code exists. I read the plan outputs entirely, every time. I discuss the details with the AI, push back on the parts that do not match what I had in mind, and sometimes adjust my agents' prompts along the way, so the execution lands as close as possible to what I actually asked for. Then I read the code. All of it, diff by diff, the same way I would review a colleague's PR: does it do what the plan said, does it do it the way I would have, and is there anything in there I would not be able to explain in six months? Investing in the plan means very few issues are left at that point, but that is the whole point. The review stays short because the work happened upstream, not because I skipped it.

Why this makes me productive

Time to back all of this with something more concrete than enthusiasm. The gains are not uniform: some are spectacular, some are marginal, and it is worth being honest about which is which.

The core of it all is jira-analyst and jira-feedback, the two agents that made me love this workflow. Where I work, we have a "focus" team: everyone can work on anything, from stocks to retail to customer management. The context switch between issues is huge, and that is exactly what jira-analyst absorbs: it explains everything I need to know before I dive in. Depending on the issue, that saves me up to half a day, sometimes a full day. It is also the agent I have invested the most in: its prompt was improved iteration after iteration to get to the current point.

pr-review-planner is a blessing of the same kind. Review feedback used to take me a lot of time, because each comment demands its context: what code it points at, what the reviewer meant, what the options are. Now I run the agent, read the output, and I have everything I need to decide what to do, comment by comment.

On the command side, github-awaiting-review and github-milestone-triage replaced a chore: going through all the PRs, checking who created each issue and who is reviewing it, building the Slack message, sending it. Depending on how many PRs are open, that could cost me up to 20 minutes. Now I run the command, come back later, and it is done. And the minutes are not even the real win: the real win is that I no longer break my focus for it. Stuff that simple belongs to a prompt, and my attention stays on my tasks. And I will be honest about milestone-build: the raw time saving is small, since before it I would simply git merge each branch into a release branch and push. What it removes is everything around the merges: I no longer handle the conflicts, nor check which PRs should be in, all of that is automated.

Then there is Orca itself. Most of my daily routine now lives in it: I only open Jira to assign tickets to myself, GitHub to review other developers' PRs, and Slack to share the lists my commands prepare (and if one day I can do all of that from Orca, I will be happy). Fewer tools means less stuff to think about, and everything goes faster. And worktree management deserves a final word: I tried creating worktrees manually, then asking an agent to create them for me. Having tools like Jean and Orca handle it natively is an amazing step forward for this ADE philosophy.

Conclusion

Looking back at the whole journey, the pattern from the beginning still holds: I followed where the tech led me, one more time. From lines of C to libraries, from libraries to frameworks, from frameworks to features. Except this time, the tech is not a language or a framework: it is a coworker. It reads the tickets, analyzes the code, proposes plans; I direct, review, and decide.

And to be honest until the end: not everything is smooth yet. Worktrees are a blessing, but there are still holes, and the biggest one for me is local infrastructure. Running several copies of the same website means Docker conflicts, so when I work in a worktree, I avoid running Docker as much as possible. We worked on tooling to soften this: our containers are now prefixed with the worktree name, for example. But some pieces resist: we use Traefik as our HTTP router, and you cannot run more than one of these, so it will take more work on tooling before all of this runs well side by side.

Rough edges like these are the sign of a young ecosystem, not of a wrong direction. IDEs took decades to become what they are; ADEs are barely getting started, and they already changed my daily work more than any tool since frameworks. I do not know which ADE will win, or if the ones I use today will still be here in five years. But I know I am not going back to an environment built for me alone: agents have joined the team now, and they deserve a good office too.

Writing the PHP Virtual Machine in Rust (with a lot of help from AI)

2026-07-29T15:42:00+02:00

A few years ago, if someone had told me to rewrite the PHP engine in Rust, I would probably have laughed 😆. Not because it is technically impossible, but because such a project traditionally requires years of reading C code, reverse engineering decades of optimizations, and an intimidating amount of perseverance.

Today, Large Language Models have changed how we approach ambitious engineering projects. They do not magically produce production-ready software, but they dramatically reduce the cost of understanding unfamiliar codebases, exploring implementation strategies, and validating ideas.

Projects like Bun and the React Compiler show that revisiting mature ecosystems has become more realistic, not because AI replaces engineers, but because it multiplies their capacity.

This is the story of building a new PHP Virtual Machine in Rust, what worked, what failed, and why the goal was never to create yet another PHP interpreter.

The first prototype: surprisingly easy and terribly slow

Like many AI-assisted projects, the first version began with an intentionally naive approach. Without studying the PHP source code in depth, we asked the model to generate a VM from its own knowledge, then guided it with examples and corrections whenever something failed.

Before long, we had a functional prototype capable of executing a meaningful subset of PHP, but it was incredibly slow. That was hardly surprising: the generated implementation favored correctness over performance.

Furthermore it generated a stack vm where PHP is a registry vm

I believe that this difference would have been very painful at some point. Those kinds of differences can make some behavior don’t work the same way, like destruction orders of values, or timing of errors emission. Given the current PHP ecosystem, I'm pretty sure that some existing libraries rely on those orders. Since the goal is to mimic a real migration of PHP, I believe that we should respect that.

The prototype (done in one day) only proved that the idea was viable, but it was clearly not the final architecture.

Copying PHP exactly was not the goal

At that point, one option was to follow the path Bun took with its rewrite and reproduce the original implementation as closely as possible. This has obvious advantages: PHP's engine contains more than twenty years of knowledge and optimization from hundreds of contributors, and reproducing its architecture often means reproducing its performance.

Such rewrite generally breaks the target language way of doing things, look at the Bun rewrite pull request. It is full of unsafe, which, in my opinion, completely defeats the purpose of using Rust and makes this PR a complete nonsense.

The purpose of the project was not simply to rewrite Zend Engine in another language, but to understand how PHP works and explore what its VM might look like if designed from the beginning around Rust's philosophy.

That meant embracing ownership, avoiding global mutable state, minimizing unsafe code, and taking advantage of the language rather than constantly fighting it. Otherwise, there would be little point in choosing Rust.

Learning from PHP instead of copying it

Not copying PHP does not mean ignoring it. A significant part of the project involved reading Zend Engine code, asking AI why particular mechanisms existed, tracing historical decisions, and discussing alternative implementations.

I learned a lot on how PHP works, why it works that way, and how to implement similar behavior in Rust.

Those conversations often revealed that an optimization reflected older CPU behavior, that strange-looking code avoided an allocation on a critical path, or that Rust offered a more natural implementation. Just as often, they showed that PHP had already found the best solution years ago.

The objective gradually shifted from rewriting PHP to understanding why it became what it is today.

Building the VM I always wanted

Studying the engine also gave me an opportunity to experiment with ideas I had wanted to see in PHP for years.

Respecting ownership and avoiding global state

One of the first constraints was to follow the Rust way of doing things: avoid global mutable state. Instead, the VM is designed to be a self-contained object that can be instantiated multiple times, each with its own state.

This makes the architecture easier to reason about while allowing multiple independent VMs to run within the same thread. It also simplifies testing and embedding, and fits much more naturally with Rust's programming model. A global mutable state in Rust is problematic since it either forces a RefCell around it to make it safe (slower) or does unsafe code (a nogo).

A fork model for requests

Instead of rebuilding a fresh runtime for every request, the VM can be paused and cloned using copy-on-write semantics. The clone executes the request and is then discarded, while the untouched original is immediately ready to serve as the base for the next one.

In the code it works like this:

<?php

require 'vendor/autoload.php';

// initialize a preloaded state
$kernel = new Symfony\Kernel('prod', false);
$kernel->boot();

// cache some data
$data = do_some_expensive_work();

// pause and wait for a request
rphp_request_pause();

// execution will start from here for every request, with the preloaded state and cached data available
$request = Request::createFromGlobals();
$kernel->handle($request);

$newData = something();

// newData / request / static cache created after the pause will be dropped at the end of the request, but $data will remain available for the next one

This mode sits between the classic PHP model, where each request starts from scratch, and a long-running process, like FrankenPHP worker mode, where state is preserved across requests. It allows the VM to avoid the repeated reconstruction of application state while still preserving the isolation between requests.

AI as a discussion partner

The most unexpected part of the project was not code generation, but the depth of the technical discussions. We could explore why PHP laid out an object in a particular way, whether an optimization existed because of CPU caches, or whether Rust's type system could eliminate a runtime check.

I also learned a lot about how a compiler works, how to design a VM, and the inside of the Zend Engine.

The AI was rarely right on its first attempt, but it was almost always useful. It became less a code generator than a technical sparring partner, able to summarize thousands of lines of C, suggest alternative designs, and help turn questions into experiments.

But it still writes sloppy code, even after passing a lot of times trying to fix some structures, and telling the AI to follow specific rules. The current code is far from perfect.

In the end, the project was not written by AI; it was accelerated by it. That may be the most important change these tools bring to ambitious software projects.

For people that are afraid that AI will code everything for them, I can tell you that it is not the case. If you do not understand the code and the underlying concepts, you will fail miserably. AI is a tool, a partner, not a replacement for knowledge and experience. But it is also dangerous, the number of times I believe it has done something amazing, only to find out that it was wrong, is countless. It is a tool that can help you, but it can also mislead you. You need to be careful and always verify the results.

Why Rust? Why not [insert your own language here]?

This experimentation could have been done in C (and just make a fork on PHP), or we could have used Zig, or even PHP.

There is mainly 2 reasons that I have chosen this :

I know the language well, meaning I don't need to think about language when I read code, I only think about logic which saves a lot of time reviewing it.
I do think that Rust is actually the best language to work with AI, simply because it has so many constraints: which can be painful as a developer, but makes it safer when it’s AI writing it. AI is not perfect, and I don’t think it will ever be one day, simply because perfection is a moving state, and it is subjective. Also making errors is part of the process of learning. So in my point of view AI needs deterministic tools to be good, and the more deterministic constraints the more it’s powerful, since AI can have automatic feedback on those constraints and can adapt what it does. It also adds a lot of confidence on what is built for the end user.

Where the project stands today

You can see the project on GitHub at https://github.com/jolicode/rphp.

Although there is still a long way to go, roughly 80% of the basic compatibility tests now pass. Many features and edge cases remain, but the VM can already execute a significant amount of real-world PHP code.

For pure PHP code without external or native function calls, it is currently between 5 and 15 times slower than PHP. This is unsurprising given Zend Engine's two decades of profiling and optimization, but raw interpreter speed is only part of the picture.

However, fork mode is around 30 times faster than the VM's classic execution mode on the same application. This is the most encouraging result so far because it suggests that interpreter performance is not the only available lever. On the Symfony Demo application, avoiding the repeated reconstruction of application state is enough to make the VM faster than PHP / FrankendPHP in classic mode despite its slower interpreter.

If we can progressively close the gap in pure code execution while preserving the fork model's architectural advantages, the result could be a genuinely fast engine for real-world applications.

It was written in about one month, with daily adjustment / reading / refocus on what was important. There was also a lot of autonomous work, where the AI was iterating over tests fixing, closing the gap between the current implementation and the expected / existing behavior. For this occasion I used a Max 20x Claude plan (about 200€, only take it for a month) and mostly used Opus 4.8 / Sonnet 4.6 and even Fable when it was available at some points. We could feel a difference between those 3 models, but I could feel, given how we constantly adjust it, that any of those 3 models would have rendered the same results.

What's next?

I'm not sure what to do next. The project has already been a success in terms of learning and experimentation, but it is still far from being a production-ready PHP engine. I may continue to improve the VM, or I may start a new project with the knowledge gained from this one.

Some of those ideas may turn out to be mistakes, while others may prove surprisingly effective. Either way, the journey has already been worth it.

Détecter les régressions visuelles dans la CI avec Playwright et Docker

2026-07-23T09:41:00+02:00

Mise à jour 25/08/2026 : ajout d'une explication quand il est préférable d'utiliser du CSS custom au lieu d'appliquer un masque Playwright.

Sur un gros site public, le front bouge tout le temps : une migration Tailwind par-ci, un composant React par-là, un bloc CMS qui change de gabarit. Et comme toujours avec le CSS, la modification d’une classe qui semblait anodine peut très bien décaler un bloc trois pages plus loin, sans que personne ne s’en rende compte avant la mise en production.

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

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

Le principe : `toHaveScreenshot()`

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

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

Un test ressemble à ça :

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

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

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

Attendre que la page soit vraiment stable

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

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

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

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

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

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

Masquer ce qui est volontairement aléatoire

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

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

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

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

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

Info

Parfois, appliquer un masque sur un élément de cette manière peut également masquer d'autres éléments. Vous pourriez alors aussi choisir de masquer vous-même certains éléments, en incluant une feuille de style dédiée aux tests et qui ferait un display: none !important; visibility: hidden !important; sur les éléments ciblés par exemple.

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

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

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

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

Un rendu stable grâce à Docker

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

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

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

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

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

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

Info

Sur ce projet, nos tests ne tournent volontairement que sur Chrome. Donc nous évitons de télécharger Firefox et WebKit pour rien. Pour cela, on ajoute la config suivante dans le fichier playwright.config.ts :

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

Puis on demande à Playwright d'installer uniquement Chromium :

yarn playwright install chromium'

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

Piloter les tests avec Castor

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

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

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

    $command = 'yarn playwright test';

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

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

    docker_compose_run($command);
}

Pour résumer, cette task va :

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

Le workflow au quotidien tient alors en trois commandes :

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

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

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

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

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

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

        return;
    }

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

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

Poster les diffs dans la pull request

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

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

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

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

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

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

Info

Mettre la logique dans une task Castor plutôt que dans le YAML de GitHub Actions a un avantage non négligeable : on peut la lancer en local avec une option --dry-run qui construit et affiche le commentaire sans rien envoyer. Débugger un rendu Markdown sans avoir à pousser un commit pour chaque essai, c’est appréciable.

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

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

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

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

Info

Nous utilisons des runners GitHub qui sont self-hostés et tournent sur une machine située sur l'infra du client et qui a donc accès à l'instance de préproduction. Dans la plupart des situations, ce n'est pas le cas, il vous faudra donc trouver comment rendre accessible publiquement ces images (hébergement S3-like, service dédié, etc).

Le commentaire est ensuite construit à la main en Markdown :

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

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

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

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

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

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

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

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

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

    return null;
}

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

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

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

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

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

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

Dédoublonner les retries

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

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

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

Purger les vieilles images

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

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

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

Le cas des fixtures aléatoires

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

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

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

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

when@test: *dev

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

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

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

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

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

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

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

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

En résumé

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

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

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

JoliDay 2026 avec du malt, des aiguilles, de la 3D et des copeaux

2026-07-21T15:42:00+02:00

Comme tous les ans, nous avons profité d’un jour férié (en application de la journée de solidarité avec les personnes âgées) pour nous retrouver tous ensemble et faire des projets ni Web ni Mobile, mais toujours de qualité 👌. Nous avons un gros faible pour le DIY et retrouvons la même gratification à résoudre des problèmes dans « le monde réel » que dans nos projets du quotidien !

Dans cet article, nous vous présentons les différents projets réalisés en une journée par les JoliCodeuses et JoliCodeurs ! Cette année a été particulièrement riche en projets qui améliorent nos bureaux 😯

Conception et réalisation de tables basses

Après avoir cassé le plateau en verre de la table basse pour la cinquième fois 💥, nous avons fini par nous rendre à l’évidence : mieux vaut éviter les meubles fragiles dans les locaux (surtout après l’apéro).

Nous avons alors réfléchi à comment remplacer le plateau par quelque chose de plus résistant, mais toujours esthétique, et comme on adore mettre les mains dans le cambouis, nous avons décidé de le faire nous-même.

En lieu et place de cambouis, c’est dans la sciure que Greg, Suzanne, Ariel, Han et Caro ont décidé de se plonger, en réalisant deux plateaux de table en bois. C’était l’occasion ou jamais de manier scie cloche, affleureuse, défonceuse et autres outils bruyants aux noms exotiques.

Nos pieds de table actuels sont des boîtes de Lego en forme de Lego géants (non, cet article n’est pas sponsorisé). Nous avons donc imaginé des plateaux avec des trous à la bonne taille pour que les tenons (c’est le terme consacré) de nos boîtes de Lego viennent s’insérer précisément dans le bois, maintenant les plateaux en place tout en dépassant un peu pour leur donner un style unique.

Après la découpe de notre grande planche et le perçage des trous, un joli arrondi autour des trous et des bords des plateaux avec une fraise quart-de-rond et un peu de polissage à la main (le tout en plein soleil sur la terrasse 🥵), il était temps de d’appliquer un petit coup de peinture pour fignoler. Notre équipe a terminé la journée de la sciure plein les cheveux mais très heureuse du travail accompli et déjà pleine d’idées d’améliorations pour le prochain JoliDay.

De la couture, de la peinture et de la broderie pour embellir nos locaux

Une fois n’est pas coutume, nous avons troqué nos ordinateurs contre des aiguilles et des machines à coudre pour un atelier couture 🪡.

Les jolies lettres brodées, enfin terminées, ont été découpées et cousues sur le rideau de notre château. Celui-ci arbore désormais fièrement, dans un style médiéval, les lettres “JC” et “PO” en clin d’oeil aux structures occupant les locaux.

Cet atelier attire de plus en plus de petits curieux. Ainsi Paul a pu confectionner une housse de coussin sur les conseils avisés de Lucie. Lucie et Han y ont ensuite brodé de petits motifs. Et voilà de beaux coussins pour nos locaux !

Enfin, pour égayer nos événements internes, nous avons décidé de confectionner une nappe sur mesure. Lucie et Sophie se sont chargées de la découpe du tissu aux bonnes dimensions, puis de la couture. Pour la décoration, l’idée de la broder a vite été abandonnée, au risque d’y passer les dix prochains JoliDay…

Armées de pinceaux et de peinture textile, Sophie, Laureen, Aga et Katia ont laissé libre cours à leurs créations. Il reste encore quelques motifs à ajouter afin que la nappe puisse trouver sa place lors de nos soirées.

Un établi tout bien rangé

Comme vous vous en doutez, tous ces travaux manuels nécessitent des outils. Et à JoliCode, depuis longtemps, il y a un établi qui regroupe plusieurs spécialités. Nous avons des outils pour le travail du bois, l'impression 3D, une grosse partie électronique, et tout un tas de petites choses inclassables aussi (poignées de porte, plomberie, paillettes et pots de peinture par exemple).

Le plan était simple : tout vider, tout trier, tout nettoyer, et enfin réorganiser. Car avec le temps, nous en avons accumulé des choses !

D’une part, nous voulions que tout le monde s’y retrouve, mais aussi que ce soit Joli (code).

Des tiroirs, il y en a sur cet établi : tout vider et nettoyer, ça nous a pris la matinée. Ensuite, le plus difficile : réorganiser (et nommer les choses). Un tiroir pour la visserie, un pour la plomberie, un pour l’électricité, l’électronique, enfin, vous avez compris. Et malheureusement, nous n’avons pas pu échapper au tiroir "divers".

Puis, après avoir fixé au mur une plaque SKÅDIS de nos amis suédois, nous avons pu rendre disponible ce qui est le plus souvent utilisé : cutter, WD40, scotch, tournevis divers et bien sûr le kit de réparation iFixit 💛

Visuellement, pour que ça claque, nous avons mis notre logo LED et des petites plantes, bien sûr !

Petit jeu bonus : sauras-tu retrouver l’éléphant qui se cache sur l’établi ?

Enfin saviez-vous qu'il était possible de retourner les clés allen qui servent à monter les meubles à IKEA ? Nous en avons retrouvé des centaines !

3 types de bières pour cette cuvée 2026

Depuis la première édition du JoliDay, nous brassons notre propre bière. En sirop ou en tout grain, version simple, avec du houblon maison ou une touche de miel… nous avons tout testé !

Pour cette année, nous avons choisi de concocter trois petits brassins différents : une blonde classique, une IPA et une blanche.

Comme tous les ans, nous avons ressorti la marmite, le thermomètre et le serpentin et avons fait chauffer et refroidir nos moûts, embaumant les locaux d'une bonne odeur de céréales.

Bientôt la mise en bouteille ! 🍻

Des bureaux en 3D et des micro-voitures : notre JoliKart maison

Grande amatrice de jeux vidéo, notre équipe a décidé de délaisser le Web le temps d’une journée pour se frotter au développement sur Godot. L’objectif ? Créer un jeu de course multijoueur façon Mario Kart, au beau milieu de nos bureaux.

Pour planter le décor, nous avons commencé par scanner l’open space en 3D à l’aide de l’application Polycam et du capteur LiDAR de l’iPhone (une technologie de détection laser qui permet de mesurer les distances et de modéliser des volumes réels). Une fois cette base récupérée, nous nous sommes divisés en deux binômes : le premier sur Blender pour nettoyer l’export 3D Polycam et ajouter des « props », ces éléments de décor (plantes vertes, bornes d’arcade et logo JoliCode) ; et le second sur le moteur Godot Engine pour coder la physique et le gameplay.

En fin de journée, le pari était à moitié réussi : nous avions une voiture contrôlable qui slalomait entre les pieds de chaises, gérait les collisions avec le mobilier et validait des checkpoints !

Nous avons perdu pas mal de temps l’après-midi sur la resynchronisation de la carte 3D entre Blender et Godot. Ne sachant pas trop dans quel logiciel il valait mieux l’éditer, chaque import avait tendance à faire sauter nos collisions et nos modifications de scripts. Après coup, on nous a conseillé de concevoir uniquement les volumes de base dans Blender, puis de gérer les caméras, les lumières et les décors directement dans Godot.

Mais notre plus gros blocage est venu d'un problème d'échelle. La carte et le modèle de la voiture étant initialement importés en taille réelle (1:1), la voiture s’est retrouvée géante dans un environnement bien trop petit pour elle. Nous avons donc tenté de réduire sa taille pour obtenir un effet à la Micro Machines. Et c’est là que le moteur physique de Godot a montré ses limites : la gestion de nombres aussi petits a provoqué des erreurs d’arrondi, rendant le véhicule totalement incontrôlable. À l’inverse, nous avons essayé d’agrandir l’échelle globale de la scène, mais ce sont alors les éclairages qui ne fonctionnaient plus. C’était le dilemme d’avant notre démo : soit une physique stable mais une voiture géante, soit un format miniature au prix d’une scène aux lumières chaotiques.

Peu importe, nous nous sommes bien amusés à découvrir Godot en développant ce mini jeu. Et pour la prochaine fois, nous savons déjà ce qu’il reste à faire : réparer les lumières, améliorer l’interface et enfin ajouter des bonus thématiques (goûter, raclette party ou downtime réseau général) ainsi que le fameux mode multijoueur.

Pour conclure

Cette journée fait partie des nombreux side-projects que l’équipe poursuit tout au long de l’année, et cette édition a été une nouvelle fois riche en apprentissages. Envie de jouer avec nous ? Changez de boulot !

JoliMediaSyliusBundle, a New Bridge for Your Sylius Projects

2026-07-20T14:42:00+02:00

Does the excellent Sylius E-commerce framework even need an introduction?

If Sylius has established itself in the e-commerce ecosystem, it's largely thanks to its ability to adapt to a wide variety of business needs without imposing a rigid architecture. Its extension system allows for gradual feature evolution while preserving the framework's core mechanisms.

Late last year, we launched JoliMediaBundle, a Symfony bundle dedicated to managing media libraries.

It already came with two bridges for SonataAdmin and EasyAdmin.

The Bridge's Origin

Having recently joined JoliCode as a Sylius expert, I quickly started discussions around integrating the MediaBundle into this ecosystem. That's how the idea for this new bridge was born, aiming to seamlessly connect media management with Sylius.

Media Management in Sylius

Before introducing this new bridge, it's useful to take stock of how media management works in Sylius today.

By default, Sylius provides a simple but effective system for associating images with the main catalog resources, such as products or taxons. This management relies on image entities directly linked to resources, with some basic metadata (type, position, etc.).

This approach perfectly meets the typical needs of an e-commerce site: illustrating a product, displaying category visuals, or managing simple galleries.

However, certain limitations emerge as needs become more cross-cutting. Specifically:

the difficulty of easily reusing the same media in multiple places without duplication;
the lack of centralized file organization (folders, tags, search…);
scattered media management, specific to each resource.

In practice, each entity embeds its own files, which works well at small scale but quickly becomes cumbersome when media volume increases or multiple teams are involved.

The Sylius and JoliMediaBundle Bridge

It is precisely this observation that motivated the reflection around a more centralized and reusable media management within the Sylius ecosystem, leveraging the JoliMediaBundle developed at JoliCode. To address these limitations, we developed the Sylius bridge for this bundle. The goal is not to modify how Sylius works or to rewrite its media management, but to add a clean integration layer based on its extension mechanisms.

In a Sylius project, media are used in product images, taxon images, and administrator avatars. These uses are well integrated into the native model but remain isolated from one another. The bridge enhances this by introducing a centralized media library.

It is also designed to be compatible with the broader Sylius Stack, not just an e-commerce context. It can thus be integrated into Sylius back-offices used as application bases, where media management is a cross-cutting need across multiple functional domains. This allows using the same centralized media library approach in more general projects built with Sylius.

Concretely, the approach relies on simple and targeted extensions:

extending Sylius entities when necessary;
replacing back-office form fields to use the JoliMediaBundle media selector;
progressive integration via the extension points provided by Sylius.

This strategy preserves current business usage while introducing a more coherent and reusable media management. Each image (product, taxon, administrator) keeps its role, but now fits within a common media library logic.

The integration remains deliberately unobtrusive: the bridge acts as an overlay that plugs into the Sylius ecosystem without modifying its foundations.

It is this progressive approach that makes adoption possible in an existing project, without data model overhaul or functional disruption.

The question then becomes more concrete: how does this bridge technically fit into Sylius, and what mechanisms are used to cleanly connect the media library to the existing model?

Simple Integration into Sylius

Once you have installed the Media bundle, you need to enable the Sylius bridge:

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

Then, you enable the routes for the back-office:

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

And finally, you import the package configuration:

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

The idea is to leverage the classic extension mechanisms of Symfony and Sylius to remain as non-intrusive as possible.

A Reusable Trait for Media

The first building block consists of using a trait that adds media management to any business entity:

You can associate a media with a Sylius Doctrine entity while keeping a simple domain logic. This will synchronize the existing path field in Sylius.

Extending Sylius Entities

This approach integrates naturally with existing entities. For example, for product images:

namespace App\Entity\Product;

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

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

This way we extend a Sylius entity without modifying its core, only adding the ability to handle a media via the bundle.

Back-office Integration

Finally, on the administration side, the integration happens through a Sylius form extension. The native file field is replaced by a dedicated component from the JoliMediaBundle:

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

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

This allows plugging the media library directly into the Sylius administration interface without breaking existing forms.

These form extensions are directly provided by the bridge, you just need to declare them in Symfony:

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

The File input is replaced by the one from the Media bundle.

For the more observant, you may notice that we modified the template to remove the preview provided natively by Sylius.

The Media Library is the standout feature of the Media bundle. It allows you to view and organize your file hierarchy.

A "Grid" view is also available to display images in a larger format.

A media details page provides additional information as well as integration options.

A "Variations" tab is available to view the different variants of your media, with their respective sizes, formats, and dimensions.

This makes it possible to use the JoliMediaBundle compression system instead of the native Sylius system (which uses LiipImagine).

Let's replace the images in the product list:

<?php

namespace App\Grid\Mutator;

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

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

This way we replace the image field using our own Twig template.

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


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

The result looks identical at first glance, but you can see that the image has been processed by the JoliMediaBundle upon closer inspection:

Usage in the Shop

Since Sylius's core mechanism is not modified, images continue to work as before on the front end. They can therefore be processed directly by LiipImagine by default, without requiring any specific adaptation. In a first step, it is not mandatory to go further than this administration-side integration. It is then possible to gradually improve image rendering quality by making the necessary adjustments on the front end, as described in the bundle documentation.

Reorganizing Your Media Library

A change propagation mechanism in your entities allows you to freely move or rename your media without breaking existing references in your application. This approach not only makes it easier to search for and identify media in the back-office, but also facilitates the gradual reorganization of the media library over time, whether for restructuring a file hierarchy, standardizing file names, or grouping certain media by functional domain.

Conclusion

Sylius already provides a solid foundation for media management in an e-commerce context. The JoliMediaBundle brings a more cross-cutting and structured vision of file management. The bridge between the two does not seek to oppose these approaches, but to make them coexist cleanly. In practice, this combination allows preserving the simplicity of the Sylius model while introducing a centralized, reusable media library better suited to projects that grow or become more complex. It is also a way to extend Sylius's very philosophy: remain extensible, without imposing rigidity, while leaving the freedom to adapt the architecture to the project's actual needs.

JoliMediaSyliusBundle, un nouveau bridge pour vos projets Sylius

2026-07-20T14:42:00+02:00

Est-il encore nécessaire de présenter l’excellent framework E-commerce Sylius ?

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

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

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

La Genèse du bridge

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

La gestion des médias dans Sylius

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

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

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

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

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

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

Le bridge Sylius et JoliMediaBundle

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

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

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

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

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

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

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

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

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

Une intégration simple dans Sylius

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

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

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

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

Et enfin, on importe la configuration du package :

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

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

Un trait réutilisable pour les médias

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

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

Extension des entités Sylius

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

namespace App\Entity\Product;

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

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

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

Intégration dans le back-office

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

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

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

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

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

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

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

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

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

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

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

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

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

Remplaçons les images dans la liste des produits :

<?php

namespace App\Grid\Mutator;

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

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

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

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


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

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

Utilisation dans le shop

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

Réorganiser votre médiathèque

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

Conclusion

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

Accélérer votre CI : mettre en cache l’état de la base de données

2026-07-17T10:41:00+02:00

Il y a quelques années, j’écrivais Accélérer votre intégration continue. L’article passait en revue tout un tas de techniques pour rendre une CI plus rapide : cache Composer, cache Yarn, layers Docker, parallélisation, tmpDir de PHPStan… et, tout en bas de la liste, une idée un peu à part : plutôt que de rejouer les fixtures à chaque build, charger un dump SQL pré-généré.

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

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

Petites précision avant de commencer :

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

Le coût qu’on veut éviter

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

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

Info

Une autre solution pour rendre nos migrations plus rapides serait de les fusionner. Nous en avions déjà parlé dans un précédent article.

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

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

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

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

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

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

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

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

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


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

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

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

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

    return hash_final($hash);
}

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

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

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

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

Info

Ce cache introduit un piège subtil sur les dates de fixtures. Comme le dump est généré une fois puis rejoué pendant un maximum de 24 h, le « maintenant » vu par les fixtures est celui de la génération, pas celui du test. Une fenêtre large ne pose aucun problème : une entité « publiée il y a 2 jours » le restera, à quelques heures près, pour tous les tests qui repartent du dump. Mais une fenêtre serrée devient un piège : une fixture « expire dans 1 heure » ou « créée il y a 5 minutes » aura déjà franchi son seuil au moment où un test restaure un dump vieux de trois heures. Pour ces cas-là, mieux vaut des marges larges, ou une donnée créée à la volée dans le test plutôt que dans les fixtures partagées.

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

Restaurer ou reconstruire

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

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

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

    return;
}

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

Deux remarques sur ce bout de code.

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

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

Le résultat

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

Étape	Sans cache (reconstruction)	Avec cache (restauration)
Provisionnement de la base	~53 s	~6 s
Tâche `fixtures` complète (base + Redis + indexation ES)	~79 s	~14 s

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

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

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

JoliCode blog - les derniers articles

SimHash : trouver les pages qui se ressemblent

Le problème

Pourquoi les fonctions de hachage habituelles ne nous aident pas

Le principe : faire voter les morceaux du texte

Étape 1 : découper le texte en shingles

Étape 2 : hacher chaque shingle

Pourquoi pas hexdec() ?

Étape 3 : compter les votes

Étape 4 : construire l'empreinte

La classe complète

Comparer deux empreintes : la distance de Hamming

Trois façons de compter des bits en PHP

Est-ce que ça marche ?

Bien choisir ses paramètres

La taille des shingles

La longueur minimale du document

Le seuil de décision

63 bits, pas 64

Comparer à l'échelle

Chaque base a sa fonction

Ce que nous faisons en production

Le garde-fou

Aller plus loin : le principe des tiroirs

Ce que SimHash ne sait pas faire

Conclusion

Quand le cache de Symfony ralentit votre application...

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

Les fausses pistes

Profiler plutôt que supposer

LockRegistry, la protection anti-stampede de Symfony

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

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

Oui, les workers CLI utilisent LockRegistry

Isoler les callbacks lents tout en conservant des locks

Un pool dédié

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

Une compiler pass pour installer ce wrapper

Une autre approche : agrandir le pool de verrous

En conclusion

L'Agent Development Environment : une nouvelle unité de travail

D'où je viens

La vague des LLM

Entrée en scène de l'ADE

Mon setup au quotidien

Orca lui-même

Mes agents

Les permissions dans OpenCode

Quand Orca et les agents s'emboîtent

Mes commandes

Mes skills

La philosophie des permissions

Pourquoi ça me rend productif

Conclusion

The Agent Development Environment: A New Unit of Work

The Agent Development Environment: A New Unit of Work

Where we come from

The LLM wave

Enter the ADE

My daily setup

Orca itself

My agents

Permissions in OpenCode

When Orca and the agents click together

My commands

My skills

The permission philosophy

Why this makes me productive

Conclusion

Writing the PHP Virtual Machine in Rust (with a lot of help from AI)

The first prototype: surprisingly easy and terribly slow

Copying PHP exactly was not the goal

Learning from PHP instead of copying it

Building the VM I always wanted

Respecting ownership and avoiding global state

A fork model for requests

AI as a discussion partner

Why Rust? Why not [insert your own language here]?

Where the project stands today

What's next?

Pourquoi pas `hexdec()` ?

`LockRegistry`, la protection anti-stampede de Symfony

Oui, les workers CLI utilisent `LockRegistry`

Le principe : `toHaveScreenshot()`