Drupal Lazy Builders

Lazy builders defer rendering of dynamic/personalized content, enabling page caching while preserving dynamic elements.

When to Use

• Displaying user-specific data (name, cart, notifications)
• Content with session or user cache context
• Fixing UNCACHEABLE pages caused by max-age:0
• Improving authenticated user performance

How It Works

Page renders → Placeholder inserted → Page cached → 
Request → Cached page served → Placeholder replaced with fresh content

Argument Restrictions

Only scalar types allowed: string, int, float, bool, NULL Not allowed: Objects, arrays, closures

Examples

Example 1: Basic User Greeting

Input: "I want to show 'Hello [username]' without breaking page cache"

Output:

// In your render array:
$build['greeting'] = [
  '#lazy_builder' => [
    'my_module.lazy_builders:userGreeting',
    [\Drupal::currentUser()->id()],  // Pass user ID, not user object!
  ],
  '#create_placeholder' => TRUE,
];

# my_module.services.yml
services:
  my_module.lazy_builders:
    class: Drupal\my_module\LazyBuilders
    arguments: ['@entity_type.manager']

<?php
// src/LazyBuilders.php
namespace Drupal\my_module;

use Drupal\Core\Security\TrustedCallbackInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;

class LazyBuilders implements TrustedCallbackInterface {

  protected EntityTypeManagerInterface $entityTypeManager;

  public function __construct(EntityTypeManagerInterface $entity_type_manager) {
    $this->entityTypeManager = $entity_type_manager;
  }

  public static function trustedCallbacks() {
    return ['userGreeting'];  // MUST list all lazy builder methods
  }

  public function userGreeting(int $uid): array {
    $user = $this->entityTypeManager->getStorage('user')->load($uid);
    
    return [
      '#markup' => t('Hello @name!', ['@name' => $user->getDisplayName()]),
      '#cache' => [
        'contexts' => ['user'],
        'tags' => ['user:' . $uid],
      ],
    ];
  }
}

Example 2: Shopping Cart Count

Input: "Show cart item count in header without breaking cache"

Output:

$build['cart'] = [
  '#lazy_builder' => [
    'my_module.lazy_builders:cartCount',
    [session_id()],  // Session-based, will be placeholdered
  ],
  '#create_placeholder' => TRUE,
];

public static function trustedCallbacks() {
  return ['cartCount'];
}

public function cartCount(string $session_id): array {
  $count = $this->cartService->getItemCount($session_id);
  
  return [
    '#markup' => t('@count items', ['@count' => $count]),
    '#cache' => [
      'contexts' => ['session'],
      'max-age' => 0,  // OK here - isolated to placeholder only
    ],
  ];
}

Example 3: Fix UNCACHEABLE Page

Input: "My page is UNCACHEABLE because of a timestamp, how do I fix it?"

Output:

// BEFORE - breaks page cache:
$build['timestamp'] = [
  '#markup' => 'Generated: ' . date('Y-m-d H:i:s'),
  '#cache' => ['max-age' => 0],  // Makes entire page UNCACHEABLE!
];

// AFTER - isolate with lazy builder:
$build['timestamp'] = [
  '#lazy_builder' => ['my_module.lazy_builders:timestamp', []],
  '#create_placeholder' => TRUE,
];

public function timestamp(): array {
  return [
    '#markup' => 'Generated: ' . date('Y-m-d H:i:s'),
    '#cache' => ['max-age' => 0],  // Now only affects this placeholder
  ];
}

Example 4: Pass Multiple Arguments

Input: "I need to pass node ID and view mode to my lazy builder"

Output:

$build['related'] = [
  '#lazy_builder' => [
    'my_module.lazy_builders:relatedContent',
    [$node->id(), 'teaser', $limit],  // All must be scalar!
  ],
  '#create_placeholder' => TRUE,
];

public function relatedContent(int $nid, string $view_mode, int $limit): array {
  $node = $this->entityTypeManager->getStorage('node')->load($nid);
  // ... render related content
  
  return [
    '#theme' => 'item_list',
    '#items' => $items,
    '#cache' => [
      'tags' => ['node:' . $nid, 'node_list'],
    ],
  ];
}

Example 5: Handle Array Arguments

Input: "I need to pass an array of IDs to my lazy builder"

Output:

// WRONG - arrays not allowed:
['my_service:method', [[1, 2, 3]]]  // ❌ Will fail

// CORRECT - serialize to string:
$ids = [1, 2, 3];
$build['items'] = [
  '#lazy_builder' => [
    'my_module.lazy_builders:multipleItems',
    [implode(',', $ids)],  // Pass as comma-separated string
  ],
  '#create_placeholder' => TRUE,
];

public function multipleItems(string $ids_string): array {
  $ids = array_filter(explode(',', $ids_string));
  $nodes = $this->entityTypeManager->getStorage('node')->loadMultiple($ids);
  // ... render items
}

Example 6: Block with Lazy Builder

Input: "My block shows user-specific content, how do I make it cacheable?"

Output:

class UserNotificationsBlock extends BlockBase {

  public function build() {
    // Don't render user content directly in build()
    return [
      '#lazy_builder' => [
        'my_module.lazy_builders:notifications',
        [\Drupal::currentUser()->id()],
      ],
      '#create_placeholder' => TRUE,
    ];
  }

  // Block itself is cacheable
  public function getCacheMaxAge() {
    return Cache::PERMANENT;
  }

  public function getCacheContexts() {
    // No user context needed here - lazy builder handles it
    return parent::getCacheContexts();
  }
}

Example 7: Debug Lazy Builder Issues

Input: "My lazy builder isn't being called, how do I debug?"

Output:

// Common issues:

// 1. Missing TrustedCallbackInterface
class LazyBuilders {  // ❌ Missing interface
}

class LazyBuilders implements TrustedCallbackInterface {  // ✓ Correct
  public static function trustedCallbacks() {
    return ['myMethod'];  // Must list the method!
  }
}

// 2. Wrong service name
'wrong_service:method'  // Check services.yml spelling

// 3. Object argument
['service:method', [$node]]  // ❌ Pass $node->id() instead

// 4. Check placeholder in HTML source:
// Look for: data-big-pipe-placeholder-id="callback=my_module..."

Example 8: Lazy Builder in Twig

Input: "Can I use lazy builder directly in Twig template?"

Output:

// In preprocess or controller, add to variables:
$variables['user_greeting'] = [
  '#lazy_builder' => ['my_module.lazy_builders:greeting', [$uid]],
  '#create_placeholder' => TRUE,
];

{# In template #}
<div class="greeting">
  {{ user_greeting }}
</div>

Render Element Restrictions

Lazy builder elements can only contain:

$build['lazy'] = [
  '#lazy_builder' => [...],      // Required
  '#create_placeholder' => TRUE, // Optional
  '#cache' => [...],             // Optional
  '#weight' => 10,               // Optional
];

// NOT allowed alongside #lazy_builder:
// '#markup', '#theme', '#type', '#prefix', '#children', etc.

Common Mistakes

Mistake	Error	Fix
Object argument	Serialization error	Pass ID, load in callback
Array argument	Runtime error	Use implode()
Missing trustedCallbacks()	Security exception	Implement interface method
Method not in trustedCallbacks()	Security exception	Add method to array
Other properties with #lazy_builder	Render error	Remove extra properties

Debugging

# Check if BigPipe is processing placeholders
# Look in HTML source for:
# <div data-big-pipe-placeholder-id="callback=...">

# Disable BigPipe temporarily to test
drush pm:uninstall big_pipe

# Check Drupal logs for lazy builder errors
drush watchdog:show --type=php