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

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

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

Le déplacement vers l’entrypoint

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

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

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

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

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

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

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

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

Ce que ça ne résout pas

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

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

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

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

Ce que feraient les alternatives

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

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

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

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

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

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

La fin honnête

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

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

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

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

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

Le type que Doctrine n’a jamais vu

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Garder la colonne à jour

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

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

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

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

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

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

Étendre DQL avec les opérateurs FTS

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

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

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

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

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

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

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

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

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

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

Le filtre API Platform et l’index GIN

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

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

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

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

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

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

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

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

Ce que la répartition ressemblait vraiment

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

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

Les supprimer naïvement n’était pas une option. “Garder les 50 dernières” perd tout contexte historique pour les articles qui n’ont pas été touchés depuis un an. “Garder une par jour” perd tous les détails pour le contenu qui est activement édité. Ce dont on avait besoin, c’était une distribution qui correspondait à la façon dont les révisions sont réellement utilisées : couverture dense pour l’historique récent, couverture clairsemée pour l’ancien.

C’est une distribution logarithmique. Et la construire nécessitait du SQL brut.

Pourquoi les stratégies simples échouent

L’attrait d’une fenêtre fixe est évident : garder les N révisions les plus récentes et supprimer le reste. C’est une ligne de SQL et zéro maths. Le problème, c’est qu’elle traite une révision d’hier et une révision d’il y a trois ans comme également précieuses, ce qu’elles ne sont pas. Un éditeur qui ouvre un article de 2017 n’a pas besoin de ses 50 dernières versions ; il pourrait avoir besoin d’une par trimestre. Un article qui a été publié ce matin pourrait avoir besoin de chaque sauvegarde de la dernière heure.

Une stratégie temporelle (une révision par jour calendaire) a le problème inverse : elle est trop agressive pour le contenu actif. Si un article reçoit 30 sauvegardes entre 09h00 et 10h00, toutes sauf une disparaissent. Ce n’est pas de l’histoire, c’est de l’effacement.

Ni l’une ni l’autre ne peut exprimer “garder plus de détails pour le contenu récent, moins pour le vieux”. Cette relation est logarithmique.

L’idée de score

L’algorithme assigne à chaque révision un score basé sur son âge, puis garde seulement une révision par bucket de score. La formule de score produit des valeurs hautes et bien espacées pour les révisions récentes, et des valeurs petites et regroupées pour les anciennes.

L’expression centrale, simplifiée, ressemble à ça :

(
  ln( EXTRACT(epoch FROM (now() - created_at)) )
  /
  ( EXTRACT(epoch FROM (now() - created_at)) / 6000 )
)
* ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
* 1000

Soit s l’âge en secondes. La formule est grossièrement ln(s) / s * C, où le logarithme au numérateur et s au dénominateur font diminuer le résultat rapidement à mesure que s augmente.

Converti en entier, l’effet est le suivant : une révision sauvegardée il y a 10 minutes pourrait scorer 8432, une sauvegardée il y a 11 minutes score 8431. Elles sont dans des buckets différents. Une révision d’il y a six mois score 2, une d’il y a huit mois score aussi 2. Même bucket. La window function choisit ensuite la révision la plus récente de chaque bucket et supprime le reste.

Le résultat est automatique : les sauvegardes récentes sont toutes gardées parce que chacune a un score distinct ; les anciennes sont élagées parce que beaucoup partagent le même score.

La tentative DQL qui n’a pas abouti

Les window functions ne font pas partie de DQL. Le langage de requête de Doctrine n’a pas de syntaxe pour OVER, PARTITION BY ou ROW_NUMBER(). Avant de passer au SQL brut, l’équipe a essayé de les ajouter.

L’approche FunctionNode fonctionne pour les fonctions SQL simples, comme on l’avait déjà vu avec la FTS. Un nœud RowNumber émettant ROW_NUMBER() est trivial :

class RowNumber extends FunctionNode
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ROW_NUMBER()';
    }
}

La partie plus difficile est OVER(PARTITION BY ... ORDER BY ...). Un nœud de fonction Over a été ébauché, avec un nœud AST PartitionByClause personnalisé pour gérer la clause PARTITION BY :

class Over extends FunctionNode
{
    protected ?PartitionByClause $partitionByClause = null;
    protected ?OrderByClause $orderByClause = null;

    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'OVER('
            .($this->partitionByClause
                ? $this->partitionByClause->dispatch($sqlWalker)
                : ($this->orderByClause
                    ? $this->orderByClause->dispatch($sqlWalker)
                    : ''))
            .')';
    }
}

Ça n’a jamais été terminé. Les classes ont été livrées marquées @deprecated et “NOT TESTED YET”. Le problème est la composabilité : FunctionNode de DQL fonctionne bien pour les fonctions qui apparaissent dans les clauses WHERE ou les expressions SELECT. Une window function comme ROW_NUMBER() OVER (PARTITION BY ...) est une structure différente : elle apparaît dans une position SELECT, modifie la sémantique de la requête englobante, et exige que le parseur gère PARTITION BY comme une extension de la grammaire DQL. Rendre ça suffisamment robuste pour être fiable en production est un investissement significatif. Passer à DBAL et écrire le SQL directement a pris un après-midi.

La requête, couche par couche

L’implémentation finale est trois requêtes imbriquées :

DELETE FROM revision
WHERE iri = ?
AND id NOT IN (
    SELECT id FROM (
        SELECT
            row_number() OVER (
                PARTITION BY num, iri
                ORDER BY num DESC, created_at DESC
            ) AS lines,
            *
        FROM (
            SELECT
                (
                    ( ln( EXTRACT(epoch FROM (now() - created_at)) )
                      / ( EXTRACT(epoch FROM (now() - created_at)) / 6000 ) )
                    * ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
                    * 1000
                )::numeric::integer AS num,
                *
            FROM revision
            WHERE iri = ?
            ORDER BY created_at DESC
        ) AS lst
    ) AS rst
    WHERE lines = 1
);

Requête intérieure : calcule num, le score entier, pour chaque révision de l’IRI donnée. Les lignes sont triées par created_at DESC à ce stade.

Requête intermédiaire : exécute ROW_NUMBER() OVER (PARTITION BY num, iri ORDER BY num DESC, created_at DESC). Dans chaque bucket de score (num), les révisions sont numérotées à partir de 1 dans l’ordre décroissant d’âge. La révision la plus récente de chaque bucket obtient lines = 1.

Filtre extérieur : ne garde que les lignes lines = 1, une révision par bucket de score.

DELETE : supprime chaque révision pour cet IRI qui n’est pas dans l’ensemble gardé.

Le PARTITION BY num, iri est redondant sur l’IRI (toute la requête est déjà filtrée sur un IRI), mais rend l’intention explicite et garde la logique correcte si la requête est un jour réutilisée dans un contexte plus large.

La méthode est appelée depuis une requête complémentaire qui identifie quels IRIs ont accumulé plus qu’un seuil de révisions :

public function getIrisWithMoreRevisionThan(int $maxRevisionsCount, int $limit = 0, ?int $retencyDay = null): array
{
    $queryBuilder = $this
        ->createQueryBuilder('revision')
        ->select('revision.iri')
        ->groupBy('revision.iri')
        ->having('COUNT(1) > :maxRevisions')
        ->orderBy('COUNT(1)', Order::Descending->value)
        ->setParameter('maxRevisions', $maxRevisionsCount);

    // ...

    return array_column($queryBuilder->getQuery()->getResult(), 'iri');
}

Les deux méthodes tournent ensemble dans un nettoyage planifié : trouver les IRIs au-dessus du seuil, élaguer chacun.

Le câbler à une commande planifiée

La requête d’élagage ne s’exécute pas dans une requête HTTP. Elle tourne derrière une commande Symfony, appelée sur un planning.

La commande prend quelques options pour contrôler son agressivité :

#[AsCommand('app:purge:revision', 'Remove useless revisions')]
final class PurgeRevisionCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->addOption('max-revisions', 'm', InputOption::VALUE_REQUIRED,
                'Seuil de révisions au-dessus duquel un IRI est élaguée', 30)
            ->addOption('limit', 'l', InputOption::VALUE_REQUIRED,
                'Nombre max d\'IRIs à traiter par exécution')
            ->addOption('delay', 'w', InputOption::VALUE_REQUIRED,
                'Délai en secondes entre chaque IRI')
            ->addOption('retencyDay', 'r', InputOption::VALUE_OPTIONAL,
                'Ne traiter que les IRIs dont la dernière révision est plus vieille que N jours');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $iris = $this->revisionRepository->getIrisWithMoreRevisionThan(
            (int) $input->getOption('max-revisions'),
            (int) $input->getOption('limit'),
            (int) $input->getOption('retencyDay'),
        );

        foreach ($iris as $iri) {
            $totalDeleted += $this->revisionRepository->deleteOldRevisionForIri($iri);
            usleep((int) $input->getOption('delay') * 1_000_000);
        }

        return Command::SUCCESS;
    }
}

L’option --delay mérite attention : sur une base de données chargée, marteler une centaine d’instructions DELETE dos à dos peut provoquer de la contention de verrous. Un petit sleep entre les itérations empêche l’élagage d’entrer en concurrence avec le trafic de production.

La commande tourne derrière deux entrées crontab avec des seuils différents :

# Horaire : garder 30 révisions par IRI, traiter 100 IRIs par exécution
0 * * * * php bin/console app:purge:revision --max-revisions 30 --limit 100

# Nocturne : pour le contenu non touché depuis un an, garder seulement 3
0 0 * * * php bin/console app:purge:revision --max-revisions 3 --limit 100 --retencyDay 365

La stratégie à deux niveaux est importante. Le job horaire garde 30 révisions par IRI, ce qui est un plafond raisonnable pour le contenu activement édité. Le job nocturne cible seulement les IRIs non mis à jour depuis plus d’un an et n’en garde que 3. Un article qui n’a pas bougé depuis douze mois n’a pas besoin de trente versions dans son historique.

Ce que ça donne en pratique

Un article sauvegardé 200 fois gardera typiquement 20 à 30 révisions après élagage : la plupart des sauvegardes récentes, quelques-unes du mois dernier, une ou deux de chaque trimestre de l’année précédente. Le décompte exact dépend de la distribution d’âge des sauvegardes, pas d’un plafond arbitraire.

Un article mis à jour pour la dernière fois il y a deux ans pourrait se retrouver avec 5 ou 6 révisions. Les modifications récentes sont toutes là ; l’ancien historique est compressé mais pas effacé.

Ce n’est pas un historique parfait. C’est un historique utile.

La frontière entre DQL et SQL brut

La tentative window function n’est pas un échec à cacher. C’est une donnée utile : FunctionNode fonctionne bien pour les fonctions scalaires dans les positions WHERE et SELECT, mais composer une expression complète ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...) en DQL est plus difficile qu’il n’y paraît. L’extension de grammaire, les nœuds AST, l’intégration du SQL walker : c’est une quantité non triviale de code pour quelque chose que le SQL natif gère en trois lignes.

La frontière pratique est grossièrement celle-ci : si une fonctionnalité PostgreSQL correspond à un appel de fonction d’arité fixe, le DQL personnalisé convient. Si elle nécessite une nouvelle syntaxe de clause (frames de fenêtre, CTEs, lateral joins), le DBAL natif est généralement le meilleur compromis.

Le problème n’est pas dans la logique métier. Il est dans ce que Doctrine fait discrètement avec les dates.

Ce que Doctrine fait par défaut

Quand on déclare un champ datetime dans une entité Doctrine, la conversion entre PHP et la base de données passe par DateTimeType. Cette classe appelle format() sur l’objet DateTime pour écrire en base, et DateTime::createFromFormat() pour le relire. Aucune mention de timezone nulle part.

Si l’objet PHP est en Europe/Paris, Doctrine formate 2017-01-15 11:30:00 et l’écrit tel quel. Si le serveur qui lit ce champ est en UTC, il obtient 2017-01-15 11:30:00 et l’interprète comme UTC. Une heure s’est évaporée dans l’aller-retour, sans le moindre message d’erreur.

La doc Doctrine couvre ce sujet et suggère des types personnalisés comme solution. Ce qu’elle mentionne en passant, c’est qu’on peut donner à ces types personnalisés le même nom que les types natifs. Ce détail change tout.

Remplacer, pas ajouter

La plupart des exemples de types Doctrine personnalisés introduisent un nouveau nom : utc_datetime, app_date, et ainsi de suite. On annote ensuite chaque champ avec type: 'utc_datetime' dans les entités. Ça fonctionne, mais c’est fastidieux et ça ne protège pas contre un type: 'datetime' oublié.

L’autre option : enregistrer le type personnalisé sous le nom datetime. Doctrine remplace sa propre implémentation par la nôtre, partout, sans exception. Chaque champ datetime de toutes les entités passe par notre logique, sans changer une seule annotation.

C’est ce qu’on vient de déployer sur notre plateforme de microservices PHP. Voici à quoi ça ressemble.

Le trait partagé

Les deux types (date et datetime) partagent la même logique de conversion via un trait :

trait UTCDate
{
    private \DateTimeZone $utc;

    public function convertToPHPValue($value, AbstractPlatform $platform): ?\DateTime
    {
        if (null === $value || $value instanceof \DateTime) {
            return $value;
        }

        $format = $this->getFormat($platform);
        $converted = \DateTime::createFromFormat($format, $value, $this->getUtc());

        if (!$converted) {
            throw new \RuntimeException(
                sprintf('Could not convert database value "%s" to DateTime using format "%s".', $value, $format)
            );
        }

        $this->postConvert($converted);

        return $converted;
    }

    abstract protected function getFormat(AbstractPlatform $platform): string;

    private function getUtc(): \DateTimeZone
    {
        if (empty($this->utc)) {
            $this->utc = new \DateTimeZone('UTC');
        }

        return $this->utc;
    }
}

Le point clé : \DateTime::createFromFormat() reçoit une timezone UTC explicite. La valeur brute issue de la base est interprétée comme UTC, peu importe la timezone configurée sur le serveur PHP.

UTCDateTimeType

Pour les champs datetime, le chemin d’écriture doit aussi imposer l’UTC :

class UTCDateTimeType extends DateTimeType
{
    use UTCDate;

    #[\Override]
    public function convertToPHPValue($value, AbstractPlatform $platform): ?\DateTime
    {
        if (null === $value || $value instanceof \DateTimeInterface) {
            return parent::convertToPHPValue($value, $platform);
        }

        return parent::convertToPHPValue("$value+0000", $platform);
    }

    #[\Override]
    public function convertToDatabaseValue($value, AbstractPlatform $platform): ?string
    {
        if ($value instanceof \DateTime) {
            $value->setTimezone($this->getUtc());
        }

        return parent::convertToDatabaseValue($value, $platform);
    }

    #[\Override]
    protected function getFormat(AbstractPlatform $platform): string
    {
        return $platform->getDateTimeFormatString();
    }

    protected function postConvert(\DateTime $converted): void {}
}

En lecture (convertToPHPValue), si la valeur est une chaîne brute, on y ajoute +0000 avant de déléguer au parent. Le parent utilise ensuite ce suffixe de timezone pour créer correctement l’objet PHP.

En écriture (convertToDatabaseValue), on force le DateTime en UTC avant de le formater. Ce qui va en base est toujours en UTC.

UTCDateType

Pour les colonnes date (sans composante horaire), même approche avec une étape supplémentaire :

class UTCDateType extends DateType
{
    use UTCDate;

    #[\Override]
    protected function getFormat(AbstractPlatform $platform): string
    {
        return $platform->getDateFormatString();
    }

    protected function postConvert(\DateTime $converted): void
    {
        $converted->setTime(0, 0, 0);
    }
}

La méthode postConvert() remet l’heure à 00:00:00 après le parsing. Sans elle, un champ date pourrait revenir avec 23:59:59 ou 00:00:00+02:00 selon la timezone du serveur, ce qui casse les comparaisons et le tri.

Enregistrement dans Symfony

La partie décisive : déclarer les types sous leurs noms natifs dans config/packages/doctrine.yaml.

doctrine:
    dbal:
        types:
            date:
                class: App\Doctrine\DBAL\Types\UTCDateType
            datetime:
                class: App\Doctrine\DBAL\Types\UTCDateTimeType

C’est tout. Doctrine échange ses propres implémentations contre les nôtres. Les entités existantes ne changent pas, les migrations ne bougent pas, les annotations restent type: Types::DATETIME_MUTABLE. Le comportement change globalement, sans friction.

12 microservices, 89 colonnes, un bloc de config

Ces deux types tournent maintenant sur 12 microservices indépendants, chacun avec sa propre config Doctrine, couvrant 89 colonnes de production. Les serveurs CI tournent en UTC, les machines de dev en Europe/Paris, les données voyagent entre eux sans dériver. Ce n’est pas spectaculaire. C’est juste fiable.

La vraie leçon n’est pas technique : un problème de timezone non résolu est un problème d’intégrité des données. Les décalages s’accumulent silencieusement, les comparaisons se trompent, les exports deviennent inexacts. Deux lignes de config et trois classes peuvent prévenir ça définitivement.