Lazy builders and auto-placeholdering: caching personalised pages

· 5 min read

You configured caching, enabled Dynamic Page Cache, and yet pages for logged-in users are still slow. Looking at the headers, you find X-Drupal-Dynamic-Cache: UNCACHEABLE. The culprit is almost always the same: one small personalised element (“Hello Akram”, the cart counter, a “My account” link) that bubbled the user cache context all the way up to the whole page.

This article follows up on the Cache API article and explains how Drupal isolates those fragments with lazy builders and placeholders, and how to find out what is breaking your cache.

The problem: cacheability bubbling

In Drupal, every render array carries its cache metadata (#cache: contexts, tags, max-age). During rendering, that metadata bubbles up to the parents: if an element varies per user, its container varies per user too, and so on up to the response.

Take a perfectly ordinary hook_preprocess_page():

function my_theme_preprocess_page(array &$variables) {
  $account = \Drupal::currentUser();
  $variables['greeting'] = [
    '#markup' => t('Hello @name', ['@name' => $account->getDisplayName()]),
    '#cache' => ['contexts' => ['user']],
  ];
}

The metadata is correct, and that is exactly the problem: the user context bubbles up to the page. Dynamic Page Cache refuses to cache a response whose cacheability matches the auto-placeholdering conditions (more on that below), so the whole page becomes UNCACHEABLE because of one line of text.

The fix: defer the fragment

A lazy builder is a callback that builds a render array later, when Drupal replaces placeholders. Instead of handing over the content, you hand over the recipe:

$variables['greeting'] = [
  '#lazy_builder' => ['my_module.user_greeting:build', []],
  '#create_placeholder' => TRUE,
];

Drupal then caches the page with a placeholder where the fragment belongs, and runs the lazy builder on every request to fill the hole. The rest of the page is served from cache.

The 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('Hello @name', [
        '@name' => $this->currentUser->getDisplayName(),
      ]),
      '#cache' => [
        'contexts' => ['user'],
        'tags' => ['user:' . $this->currentUser->id()],
      ],
    ];
  }

}

Rules to know

  • Trusted callbacks: since Drupal 9, render callbacks must be declared trusted. In Drupal 10, a callback missing from trustedCallbacks() throws an exception. Implement TrustedCallbackInterface on the service class.
  • Scalar arguments only: the arguments array may only contain string, int, float, bool or NULL. Pass an ID, never an entity: ['my_module.cart:build', [$cart_id]]. These arguments are part of the placeholder key, so they must be serialisable and stable.
  • Allowed properties: an element with #lazy_builder may only carry “meta” properties (#cache, #create_placeholder, #weight…). A #markup or children next to the #lazy_builder are rejected by the renderer: everything must be built in the callback.
  • The callback does not see the page context: it only gets its arguments. Everything it needs must come from those arguments or from injected services.

Auto-placeholdering: placeholders without asking

You don’t always need #create_placeholder => TRUE. Drupal can decide on its own to placeholder a #lazy_builder element when its cacheability is “poor”. The thresholds live in services.yml:

parameters:
  renderer.config:
    auto_placeholder_conditions:
      max-age: 0
      contexts: ['session', 'user']
      tags: []

An element with a max-age of 0, or a session or user context, is set aside automatically. Key point: the decision is made on the #cache declared on the lazy builder element itself, before the callback runs. If the contexts are only known inside the callback, Drupal cannot guess them:

// Auto-placeholdered: Drupal knows up front that the fragment varies per user.
$build['cart'] = [
  '#lazy_builder' => ['my_module.cart:build', [$cart_id]],
  '#cache' => ['contexts' => ['user']],
];

Dynamic Page Cache uses these same conditions to decide whether a response is cacheable. That is why a user context leaking up to the page makes it UNCACHEABLE.

Good news: blocks are already rendered through a lazy builder by BlockViewBuilder. A block that declares its contexts correctly in getCacheContexts() is placeholdered on its own. Leaks mostly come from preprocess functions, controllers and hand-written formatters.

Replacement strategies: SingleFlush and BigPipe

Once the page is cached, the placeholders still have to be replaced. Core ships two strategies:

Strategy How it works When
SingleFlush Placeholders are rendered server-side before the response is sent By default, and for visitors without a session
BigPipe The page is sent immediately, fragments are streamed afterwards big_pipe module enabled and a user with a session

BigPipe does not apply to anonymous visitors without a session: for them, Internal Page Cache serves the complete page with placeholders already replaced.

The anonymous trap: Internal Page Cache ignores max-age

Internal Page Cache (the page_cache module) caches the full response for anonymous users and ignores the max-age bubbled up by your render arrays. An anonymous block with max-age: 0 (weather, a stock counter) will be frozen for every visitor.

Two options:

// Option 1: exclude the page from the anonymous cache (keep this for truly dynamic pages).
\Drupal::service('page_cache_kill_switch')->trigger();

Option 2, cleaner: load the fragment client-side (a JSON route or #attached JavaScript) and keep the HTML page fully cacheable, including by a reverse proxy or a CDN.

Diagnosing: cacheability headers

Enable the debug headers in development.services.yml:

parameters:
  http.response.debug_cacheability_headers: true

Then inspect the response with a logged-in user’s session cookie:

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)

The user context in X-Drupal-Cache-Contexts explains the UNCACHEABLE. You still need to find who introduced it: disable blocks one by one, or search for 'contexts' => ['user'] and currentUser() calls in your preprocess functions and controllers. Once the fragment is converted to a lazy builder, you should see X-Drupal-Dynamic-Cache: HIT on the second load.

Checklist

  1. Anything that varies per user or per session goes through a #lazy_builder (or a block).
  2. Contexts are declared on the lazy builder element to allow auto-placeholdering, and on the callback’s result.
  3. Arguments are scalars (IDs, not objects).
  4. The service implements TrustedCallbackInterface.
  5. For anonymous users, don’t rely on max-age: 0 being honoured: use the kill switch or client-side loading.
  6. Always verify with the X-Drupal-* headers.

Conclusion

Most performance problems for logged-in users don’t come from a slow SQL query, but from one personalised fragment that poisons the cache of the whole page. Lazy builders let you keep 95% of the page cached and compute only what actually varies. It is one of the most powerful mechanisms in Drupal’s render system, and one of the least known.

Next in this series →Advanced access control: access checkers, AccessResult and cacheability