Score d’accessibilité resté périmé faute d’invalider le bon transient

Un outil interne d’audit calcule un score d’accessibilité par thème et le stocke le temps d’une journée dans un transient, pour éviter de relancer une batterie de vérifications à chaque chargement du tableau de bord. Le principe est simple, sauf qu’un vendredi après-midi, le score reste bloqué à 62 sur 100 alors que trois anomalies ARIA viennent d’être corrigées dans le thème.

Ce billet documente le bug tel qu’il a été trouvé et corrigé, pour les développeurs qui maintiennent ce genre d’outillage interne. Il ne traite pas du cache objet persistant fourni par un plugin externe : le problème vient ici uniquement de la logique de transients WordPress standard, mal câblée avec les événements qui devraient l’invalider.

Symptôme

Le tableau de bord affiche le score calculé la veille, même après un rechargement forcé du navigateur et un vidage du cache HTTP. La fonction responsable ressemble à ceci :

function wpm_get_score_accessibilite( $theme_slug ) {
    $cle = 'wpm_score_a11y_' . $theme_slug;
    $score = get_transient( $cle );

    if ( false === $score ) {
        $score = wpm_calculer_score( $theme_slug );
        set_transient( $cle, $score, DAY_IN_SECONDS );
    }

    return $score;
}

La clé de transient ne dépend que du slug du thème, pas de son contenu. Tant que la journée n’est pas écoulée, la fonction renvoie systématiquement la valeur mise en cache, quelle que soit l’évolution des fichiers du thème entre-temps.

Diagnostic

La correction du thème modifie des fichiers sur le disque, mais rien dans ce flux ne prévient WordPress qu’un événement méritant d’invalider le cache vient de se produire. L’équipe avait bien ajouté un appel à delete_transient(), mais accroché au mauvais hook :

add_action( 'switch_theme', function () {
    delete_transient( 'wpm_score_a11y_' . get_stylesheet() );
} );

Le hook switch_theme se déclenche quand un site change de thème actif, pas quand le thème actuellement actif est modifié sur le disque par un déploiement Git ou une mise à jour manuelle. Dans le contexte visé — un développeur qui corrige le thème en place, sans jamais en activer un autre — cet hook ne se déclenche donc jamais.

Correctif

Deux options existent. La première consiste à inclure un identifiant de version dans la clé de transient, dérivé par exemple d’un hash des fichiers surveillés ou d’une constante de build incrémentée à chaque déploiement :

function wpm_get_score_accessibilite( $theme_slug ) {
    $theme    = wp_get_theme( $theme_slug );
    $version  = $theme->get( 'Version' );
    $cle      = 'wpm_score_a11y_' . $theme_slug . '_' . md5( $version );

    $score = get_transient( $cle );

    if ( false === $score ) {
        $score = wpm_calculer_score( $theme_slug );
        set_transient( $cle, $score, DAY_IN_SECONDS );
    }

    return $score;
}

Ainsi, dès que le champ Version de l’en-tête style.css du thème change lors d’une correction, une nouvelle clé de cache est générée automatiquement et l’ancien score expire naturellement au bout de vingt-quatre heures, sans jamais être relu.

La seconde option, retenue en complément, ajoute un bouton « Recalculer maintenant » dans l’interface de l’outil, qui appelle explicitement delete_transient() sur la clé courante avant de relancer le calcul :

if ( isset( $_POST['wpm_recalculer_nonce'] ) && wp_verify_nonce( $_POST['wpm_recalculer_nonce'], 'wpm_recalculer_score' ) ) {
    delete_transient( $cle_courante );
}

Prévention

Pour éviter qu’un cas similaire ne se reproduise sur un autre outil interne, trois réflexes ont été formalisés dans le petit référentiel d’équipe :

• Ne jamais construire une clé de transient uniquement à partir d’un identifiant stable comme un slug ; toujours y inclure un élément qui reflète l’état réel de la donnée source (version, hash, date de modification).
• Vérifier, avant d’accrocher une invalidation à un hook WordPress, que ce hook se déclenche bien dans le scénario visé — switch_theme pour un changement de thème actif, pas pour une modification de fichiers.
• Prévoir systématiquement une voie de secours manuelle pour vider un cache, utile en développement comme pour un utilisateur bloqué en production.

Une variante plus robuste : la clé composite

Pour un outil qui audite plusieurs thèmes en parallèle, une clé composite incluant à la fois le slug, la version et un identifiant de la dernière anomalie corrigée offre une granularité plus fine. Elle demande un peu plus de code, mais elle évite tout recalcul inutile pour un thème qui n’a pas bougé, tout en garantissant l’actualisation immédiate de celui qui vient d’être modifié.

$empreinte = md5( $theme->get( 'Version' ) . filemtime( $theme->get_stylesheet_directory() . '/style.css' ) );
$cle       = "wpm_score_a11y_{$theme_slug}_{$empreinte}";

En résumé

Un transient qui ne reflète plus la réalité n’est presque jamais un problème de cache en soi : c’est un problème de clé de cache mal choisie ou d’événement d’invalidation mal ciblé. Pour un outil de suivi d’accessibilité, où l’équipe se fie au score affiché pour savoir si une correction a porté ses fruits, ce genre de décalage silencieux coûte du temps et, pire, de la confiance dans l’outil lui-même. Inclure un élément variable et représentatif dans la clé reste la parade la plus fiable, bien avant de multiplier les hooks d’invalidation.