
Vous avez configuré le cache, activé Dynamic Page Cache, et pourtant vos pages pour les utilisateurs connectés restent lentes. En inspectant les en-têtes, vous tombez sur X-Drupal-Dynamic-Cache: UNCACHEABLE. Le coupable est presque toujours le même : un petit élément personnalisé (« Bonjour Akram », le compteur du panier, un lien « Mon compte ») qui a fait remonter le contexte de cache user jusqu’à la page entière.
Cet article fait suite à l’article sur la Cache API et explique comment Drupal isole ces fragments grâce aux lazy builders et aux placeholders, et comment diagnostiquer ce qui casse votre cache.
Le problème : la remontée (bubbling) de la cacheabilité
Dans Drupal, chaque render array porte ses métadonnées de cache (#cache : contexts, tags, max-age). Au rendu, ces métadonnées remontent vers les parents : si un élément varie par utilisateur, son conteneur varie aussi par utilisateur, et ainsi de suite jusqu’à la réponse.
Prenons un hook_preprocess_page() tout à fait classique :
function my_theme_preprocess_page(array &$variables) {
$account = \Drupal::currentUser();
$variables['greeting'] = [
'#markup' => t('Bonjour @name', ['@name' => $account->getDisplayName()]),
'#cache' => ['contexts' => ['user']],
];
}
Les métadonnées sont correctes, et c’est justement le problème : le contexte user remonte jusqu’à la page. Or Dynamic Page Cache refuse de mettre en cache une réponse dont la cacheabilité correspond aux conditions d’auto-placeholdering (on y revient plus bas) : la page entière devient UNCACHEABLE pour une ligne de texte.
La solution : rendre le fragment différé
Un lazy builder est un callback qui construit un render array plus tard, au moment où Drupal remplace les placeholders. Au lieu de donner le contenu, on donne la recette :
$variables['greeting'] = [
'#lazy_builder' => ['my_module.user_greeting:build', []],
'#create_placeholder' => TRUE,
];
Drupal met alors en cache la page avec un placeholder à la place du fragment, puis exécute le lazy builder à chaque requête pour remplir ce trou. Le reste de la page est servi depuis le cache.
Le service
# my_module.services.yml
services:
my_module.user_greeting:
class: Drupal\my_module\UserGreeting
arguments: ['@current_user']
<?php
namespace Drupal\my_module;
use Drupal\Core\Security\TrustedCallbackInterface;
use Drupal\Core\Session\AccountProxyInterface;
use Drupal\Core\StringTranslation\StringTranslationTrait;
final class UserGreeting implements TrustedCallbackInterface {
use StringTranslationTrait;
public function __construct(
private readonly AccountProxyInterface $currentUser,
) {}
public static function trustedCallbacks(): array {
return ['build'];
}
public function build(): array {
return [
'#markup' => $this->t('Bonjour @name', [
'@name' => $this->currentUser->getDisplayName(),
]),
'#cache' => [
'contexts' => ['user'],
'tags' => ['user:' . $this->currentUser->id()],
],
];
}
}
Les règles à connaître
- Trusted callbacks : depuis Drupal 9, un callback de rendu doit être déclaré de confiance. Avec Drupal 10, un callback non déclaré dans
trustedCallbacks()lève une exception. ImplémentezTrustedCallbackInterfacesur la classe du service. - Arguments scalaires uniquement : le tableau d’arguments ne peut contenir que des
string,int,float,boolouNULL. Passez un ID, jamais une entité :['my_module.cart:build', [$cart_id]]. Ces arguments font partie de la clé du placeholder, ils doivent être sérialisables et stables. - Propriétés autorisées : un élément avec
#lazy_builderne peut porter que des propriétés « méta » (#cache,#create_placeholder,#weight…). Un#markupou des enfants à côté du#lazy_buildersont refusés par le renderer : tout doit être construit dans le callback. - Le callback ne voit pas le contexte de la page : il reçoit seulement ses arguments. Tout ce dont il a besoin doit venir des arguments ou des services injectés.
L’auto-placeholdering : le placeholder sans le demander
On n’a pas toujours besoin de #create_placeholder => TRUE. Drupal peut décider seul de placeholderiser un élément #lazy_builder si sa cacheabilité est « mauvaise ». Les seuils sont définis dans services.yml :
parameters:
renderer.config:
auto_placeholder_conditions:
max-age: 0
contexts: ['session', 'user']
tags: []
Un élément qui a un max-age de 0, ou un contexte session ou user, est automatiquement mis de côté. Point clé : la décision se fait sur le #cache déclaré sur l’élément lazy builder lui-même, avant l’exécution du callback. Si les contextes ne sont connus qu’à l’intérieur du callback, Drupal ne peut pas les deviner :
// Auto-placeholderisé : Drupal sait d'avance que le fragment varie par utilisateur.
$build['cart'] = [
'#lazy_builder' => ['my_module.cart:build', [$cart_id]],
'#cache' => ['contexts' => ['user']],
];
Ces mêmes conditions servent à Dynamic Page Cache pour décider si une réponse est cacheable. C’est pour cela qu’un contexte user qui fuit jusqu’à la page la rend UNCACHEABLE.
Bonne nouvelle : les blocs sont déjà rendus via lazy builder par
BlockViewBuilder. Un bloc qui déclare correctement ses contextes dansgetCacheContexts()est placeholderisé tout seul. Les fuites viennent surtout des preprocess, des contrôleurs et des formatters écrits à la main.
Les stratégies de remplacement : SingleFlush et BigPipe
Une fois la page en cache, il reste à remplacer les placeholders. Deux stratégies sont fournies par le cœur :
| Stratégie | Fonctionnement | Quand |
|---|---|---|
| SingleFlush | Les placeholders sont rendus côté serveur avant l’envoi de la réponse | Par défaut, et pour les visiteurs sans session |
| BigPipe | La page est envoyée immédiatement, les fragments arrivent ensuite en streaming | Module big_pipe activé et utilisateur avec une session |
BigPipe ne s’applique pas aux anonymes sans session : pour eux, c’est Internal Page Cache qui sert la page complète, placeholders déjà remplacés.
Le piège des anonymes : Internal Page Cache ignore le max-age
Internal Page Cache (module page_cache) met en cache la réponse complète pour les anonymes et ne tient pas compte du max-age remonté par vos render arrays. Un bloc anonyme avec max-age: 0 (une météo, un compteur de stock) sera figé pour tous les visiteurs.
Deux options :
// Option 1 : exclure la page du cache anonyme (à réserver aux pages vraiment dynamiques).
\Drupal::service('page_cache_kill_switch')->trigger();
Option 2, plus propre : charger le fragment côté client (une route JSON ou un #attached JavaScript) et laisser la page HTML entièrement cacheable, y compris par un reverse proxy ou un CDN.
Diagnostiquer : les en-têtes de cacheabilité
Activez les en-têtes de debug dans development.services.yml :
parameters:
http.response.debug_cacheability_headers: true
Puis inspectez la réponse avec le cookie de session d’un utilisateur connecté :
curl -sI https://example.com/node/1 -H "Cookie: SESS...=..." | grep -i x-drupal
X-Drupal-Dynamic-Cache: UNCACHEABLE
X-Drupal-Cache-Contexts: languages:language_interface route theme timezone url.path user user.permissions
X-Drupal-Cache-Tags: config:system.site node:1 node_view rendered user:12
X-Drupal-Cache-Max-Age: -1 (Permanent)
Le contexte user dans X-Drupal-Cache-Contexts explique le UNCACHEABLE. Il reste à trouver qui l’a introduit : désactivez les blocs un par un, ou cherchez les 'contexts' => ['user'] et les appels à currentUser() dans vos preprocess et contrôleurs. Une fois le fragment converti en lazy builder, vous devez voir X-Drupal-Dynamic-Cache: HIT au second chargement.
Checklist
- Tout contenu qui varie par utilisateur ou par session passe par un
#lazy_builder(ou un bloc). - Les contextes sont déclarés sur l’élément lazy builder pour permettre l’auto-placeholdering, et sur le résultat du callback.
- Les arguments sont des scalaires (des IDs, pas des objets).
- Le service implémente
TrustedCallbackInterface. - Pour les anonymes, pas de
max-age: 0en espérant qu’il soit respecté : kill switch ou chargement côté client. - Vérification systématique avec les en-têtes
X-Drupal-*.
Conclusion
La plupart des problèmes de performance des utilisateurs connectés ne viennent pas d’une requête SQL lente, mais d’un fragment personnalisé qui empoisonne le cache de la page entière. Les lazy builders permettent de garder 95 % de la page en cache et de ne calculer que ce qui varie vraiment. C’est l’un des mécanismes les plus puissants du système de rendu de Drupal, et l’un des moins connus.
