Résoudre les problèmes de cache Drupal : guide sur les tags, les contextes et le débogage

La bonne nouvelle, c'est qu'une fois que vous comprenez les mécanismes sous-jacents, la plupart des bogues liés au cache deviennent prévisibles et corrigeables. Cet article explique comment le cache de Drupal fonctionne réellement, pourquoi les utilisateurs anonymes observent un comportement différent des utilisateurs authentifiés, et quoi faire quand vos blocs personnalisés refusent de se mettre à jour. Si vous avez déjà constaté que le cache Drupal ne fonctionne pas comme prévu, vous êtes au bon endroit.

Les trois piliers de la mise en cache Drupal

Le système de cache de Drupal repose sur trois types de métadonnées qui travaillent ensemble pour déterminer ce qui est mis en cache, combien de temps ça reste en cache, et quand c'est invalidé. Comprendre les métadonnées de mise en cache de Drupal est essentiel pour résoudre les problèmes de cache courants.

Les cache tags

Les cache tags identifient de quelles données dépend un élément mis en cache. Quand ces données changent, Drupal sait quels éléments en cache doivent être vidés.

Exemples :

• node:5 - invalidé quand le nœud 5 est mis à jour
• user:12 - invalidé quand l'utilisateur 12 est modifié
• config:system.site - invalidé quand la configuration du site change
• node_list - invalidé quand n'importe quel nœud est créé ou supprimé

Quand les cache tags Drupal ne s'invalident pas correctement, c'est généralement parce que les bons tags n'ont pas été déclarés sur le render array.

Les cache contexts

Les cache contexts définissent les variations d'un même contenu. Si un bloc doit s'afficher différemment selon le rôle de l'utilisateur ou l'URL actuelle, vous le déclarez avec des contexts.

Contexts courants :

• user - varie par utilisateur individuel
• user.roles - varie selon le rôle de l'utilisateur
• url.path - varie selon le chemin de la page actuelle
• url.query_args - varie selon les paramètres de la chaîne de requête

Le cache max-age

Le max-age définit l'expiration basée sur le temps en secondes :

• 3600 - expire après une heure
• 0 - pas mis en cache du tout
• -1 (ou Cache::PERMANENT) - mis en cache jusqu'à invalidation par les tags

Comment fonctionne le cache bubbling

C'est ici que ça se complique. Drupal utilise le « cache bubbling » pour propager les métadonnées de mise en cache vers le haut de l'arbre de rendu. Quand un élément enfant a des exigences de cache spécifiques, ces exigences remontent vers les éléments parents et affectent ultimement la page entière. Le cache bubbling de Drupal a un impact direct sur le comportement du render cache à travers toute votre page.

Imaginez-le comme ceci :

Page (inherits all child cacheability)
  └── Region
        └── Block (cache contexts: user.roles)
              └── View (cache tags: node_list)
                    └── Node teaser (cache tags: node:123)

Chaque cache tag, context, et le max-age le plus restrictif des éléments enfants remonte jusqu'au niveau de la page. C'est généralement utile. Ça signifie que la page sait automatiquement quand s'invalider en fonction de son contenu. Mais ça veut aussi dire qu'un seul élément mal configuré peut rendre une page entière impossible à mettre en cache.

Un piège courant : si n'importe quel élément imbriqué définit max-age: 0, ça peut remonter et empêcher la mise en cache de toute la page. En travaillant avec différentes équipes, on a constaté que ce seul problème est responsable d'un grand pourcentage des plaintes du type « mon site est lent ».

Le problème des utilisateurs anonymes

Le problème du cache pour les utilisateurs anonymes dans Drupal est l'un des enjeux les plus fréquemment rencontrés dans le développement de sites.

Drupal possède deux systèmes de mise en cache de pages distincts, et comprendre la différence explique la plupart des problèmes de cache des utilisateurs anonymes. Comprendre la différence entre le Page Cache et le Dynamic Page Cache de Drupal est la clé pour résoudre ces problèmes.

Internal Page Cache

Le module Page Cache stocke les pages HTML complètes pour les utilisateurs anonymes. Il fonctionne selon une hypothèse clé : les pages anonymes sont identiques pour tous les visiteurs.

Cette hypothèse cause des problèmes quand votre site doit afficher du contenu différent aux visiteurs anonymes : paniers d'achat, contenu basé sur la localisation, ou affichages sensibles au temps. Même si votre bloc définit correctement les métadonnées de cache, le Page Cache peut quand même servir une version de page complète mise en cache.

Si votre site a besoin de contenu personnalisé pour les utilisateurs anonymes, vous avez deux options :

• Désactiver l'Internal Page Cache et gérer la mise en cache différemment
• Livrer le contenu personnalisé via JavaScript ou AJAX après le chargement de la page

Dynamic Page Cache

Le Dynamic Page Cache fonctionne différemment. Il met en cache les pages avec des placeholders, puis remplit les parties dynamiques à chaque requête. Ça gère les utilisateurs authentifiés et les pages avec du contenu spécifique à l'utilisateur.

Le système détecte automatiquement les éléments difficiles à mettre en cache (comme ceux avec max-age: 0 ou des contexts à haute cardinalité comme user ou session) et les remplace par des placeholders. Ça empêche ces éléments de rendre la page entière impossible à mettre en cache.

Cache des blocs personnalisés : bien faire les choses

Une bonne configuration du cache des blocs personnalisés Drupal est essentielle tant pour la performance que pour l'exactitude du contenu.

La plupart des problèmes de cache des blocs personnalisés viennent d'une déclaration inadéquate des métadonnées de mise en cache. Voici à quoi ressemble un bloc personnalisé bien configuré :

public function build() {
  $build = [
    '#markup' => $this->t('Dynamic content here'),
    '#cache' => [
      'tags' => ['node_list', 'custom_block:example'],
      'contexts' => ['url.path', 'user.roles'],
      'max-age' => 3600,
    ],
  ];
  return $build;
}

public function getCacheTags() {
  return Cache::mergeTags(parent::getCacheTags(), ['node_list']);
}

public function getCacheContexts() {
  return Cache::mergeContexts(parent::getCacheContexts(), ['url.path']);
}

Points clés :

• Déclarez les cache tags pour chaque donnée dont votre bloc dépend
• Ajoutez des contexts pour toute condition qui devrait produire une sortie différente
• Définissez le max-age seulement si une expiration basée sur le temps a du sens pour votre cas d'utilisation

Quand utiliser les lazy builders

Pour du contenu véritablement dynamique qui ne devrait pas affecter la mise en cache de la page, utilisez les lazy builders :

$build['dynamic_part'] = [
  '#lazy_builder' => ['my_module.lazy_builder:build', [$arg1, $arg2]],
  '#create_placeholder' => TRUE,
];

L'exemple de lazy builder Drupal ci-dessus démontre le pattern pour isoler le contenu non cacheable du reste de la page.

Cette approche fonctionne bien pour :

• Le contenu spécifique à l'utilisateur sur des pages autrement cacheables
• Les données en temps réel comme les cours boursiers ou les scores en direct
• Le contenu dépendant de la session

Options de cache des Views

Configurer correctement les paramètres de cache des Views Drupal peut avoir un impact significatif sur l'optimisation des performances de votre site.

Views offre trois approches de mise en cache :

• Aucun - Pour le développement seulement, ou les données qui changent constamment
• Basé sur les tags - La plupart des cas d'utilisation en production s'invalide quand le contenu affiché change
• Basé sur le temps - Sources de données externes, ou quand vous avez besoin d'intervalles de rafraîchissement prévisibles

On a constaté que la mise en cache basée sur les tags fonctionne le mieux pour la plupart des sites. Ça garde le contenu à jour sans vidages de cache inutiles, et ça s'intègre naturellement avec le système d'entités de Drupal.

Pièges courants du cache des Views

Les filtres exposés ne varient pas : Ajoutez le cache context url.query_args à votre View si vous utilisez des filtres exposés.

Les données des relations ne s'invalident pas : Les cache tags des entités liées ne remontent pas toujours correctement. Vous devrez peut-être les ajouter manuellement.

Filtres relatifs au temps : Les Views avec des filtres « événements à venir » ou « articles de la dernière semaine » n'expirent pas automatiquement au bon moment. C'est une limitation connue (Core Issue #2352009) qui fait l'objet de discussions depuis des années. Vous aurez peut-être besoin d'une approche personnalisée pour forcer un comportement TTL approprié.

Déboguer les problèmes de cache

Un débogage efficace du cache Drupal nécessite de comprendre les outils disponibles et ce qu'ils révèlent.

Quand quelque chose ne se met pas en cache correctement, commencez par ces étapes :

Activer les en-têtes de débogage

Ajoutez ceci à votre development.services.yml :

parameters:
  http.response.debug_cacheability_headers: true

Puis vérifiez les en-têtes de réponse dans les outils de développement de votre navigateur. Les en-têtes X-Drupal-Cache offrent une visibilité immédiate sur le comportement du cache :

• X-Drupal-Cache - HIT ou MISS pour le Page Cache
• X-Drupal-Dynamic-Cache - HIT, MISS, ou UNCACHEABLE
• X-Drupal-Cache-Tags - Tous les cache tags affectant la réponse
• X-Drupal-Cache-Contexts - Tous les cache contexts en jeu

Commandes Drush utiles

drush cr                      # Rebuild all caches
drush cache:get [cid] [bin]   # Inspect specific cache entries

Outils de débogage contribués

• WebProfiler - Barre d'outils de profilage style Symfony affichant les informations de cache
• Cache Review - Audite les problèmes de mise en cache à travers votre site
• Renderviz - Visualise les limites du render cache

On recommande de commencer avec WebProfiler pendant le développement. Il fait ressortir des informations de cache qui autrement nécessiteraient l'inspection des en-têtes et l'analyse des journaux.

HTMX : une nouvelle option pour le contenu dynamique

Drupal 11.2 a ajouté HTMX comme dépendance du cœur, avec une intégration complète arrivée dans la version 11.3. Ça vous donne une autre option pour gérer le contenu dynamique sans compromettre la mise en cache des pages. L'intégration du contenu dynamique HTMX dans Drupal offre une approche moderne à ce défi.

L'approche est simple : mettez la page complète en cache, puis utilisez HTMX pour récupérer de petits fragments dynamiques via des requêtes HTTP. Ça réduit le besoin de lazy builders dans certains cas et simplifie le modèle mental pour gérer le contenu dynamique sur les pages en cache.

Pour les sites où vous avez eu de la difficulté avec la complexité des lazy builders ou la configuration de BigPipe dans Drupal, HTMX offre une alternative simple qui vaut la peine d'être explorée.

Guide de décision rapide

Utilisez le Page Cache quand :

• Vous servez du trafic anonyme
• Les pages sont identiques pour tous les visiteurs anonymes
• Vous avez besoin de performance maximale

Désactivez le Page Cache quand :

• Les visiteurs anonymes voient du contenu personnalisé
• Vous dépendez de variations par session ou basées sur la géolocalisation

Utilisez le cache Views basé sur les tags quand :

• Vous affichez des entités Drupal
• Le contenu change de façon imprévisible
• La fraîcheur compte plus qu'un timing prévisible

Utilisez les lazy builders quand :

• De petites parties d'une page ont besoin de données spécifiques à l'utilisateur
• Vous voulez que le reste de la page reste cacheable
• L'affichage de données en temps réel est requis

Considérez HTMX quand :

• Vous voulez éviter la complexité du JavaScript
• L'amélioration progressive est importante
• Les fragments dynamiques sont distincts du contenu principal de la page

Conclusion

Le système de cache de Drupal nécessite de comprendre ses mécanismes pour être utilisé correctement. La combinaison des cache tags, contexts, max-age et du comportement de bubbling vous donne un contrôle fin, mais aussi beaucoup d'occasions de mauvaise configuration.

La plupart des problèmes courants remontent à des métadonnées de cache manquantes dans le code personnalisé ou à une incompréhension de la façon dont le Page Cache traite les utilisateurs anonymes différemment des utilisateurs authentifiés. Commencez le débogage avec les en-têtes de réponse, ajoutez les déclarations de mise en cache appropriées à vos render arrays, et considérez les lazy builders ou HTMX quand vous avez besoin de contenu dynamique sur des pages autrement cacheables.

Si votre site Drupal a des problèmes de cache persistants qui affectent la performance ou la fraîcheur du contenu, diagnostiquer la cause racine nécessite souvent d'examiner les métadonnées de cache à travers plusieurs couches. Nous pouvons vous aider à auditer la configuration de mise en cache de votre site et identifier exactement où la chaîne de cache se brise.