caching-strategy

Drupal Caching Strategy

Cache Metadata (The Three Pillars)

Every render array MUST include cache metadata:

$build = [
  '#theme' => 'my_template',
  '#data' => $data,
  '#cache' => [
    'tags' => ['node_list', 'node:42'],           // WHAT invalidates this
    'contexts' => ['user.permissions', 'url.path'], // WHAT varies this
    'max-age' => 3600,                              // HOW LONG to cache (seconds)
  ],
];

Cache Tags — "What invalidates this cache?"

• node:NID — Invalidated when a specific node changes
• node_list — Invalidated when any node is created/updated/deleted
• user:UID — Invalidated when a specific user changes
• taxonomy_term:TID — Invalidated when a term changes
• config:system.site — Invalidated when site config changes
• Custom: MODULE_NAME:ENTITY:ID

Invalidate manually:

\Drupal\Core\Cache\Cache::invalidateTags(['node:42']);

Cache Contexts — "What makes this vary?"

• user — Different per user
• user.permissions — Different per permission set (fewer variations)
• user.roles — Different per role combination
• url.path — Different per URL path
• url.query_args — Different per query string
• url.query_args:sort — Different per specific query param
• languages:language_interface — Different per language
• theme — Different per theme
• route — Different per route

Max-Age

• Cache::PERMANENT (or -1) — Never expires (invalidated by tags only)
• 0 — Uncacheable (use sparingly — kills performance)
• 3600 — Cache for 1 hour
• 86400 — Cache for 1 day

Cache Bubbling

Cache metadata "bubbles up" from child elements to parents. Drupal automatically merges:

• Tags: Union of all tags
• Contexts: Union of all contexts
• Max-age: Minimum of all max-ages (most restrictive wins)

This means if ANY child has max-age: 0, the entire page becomes uncacheable.

Lazy Builders

For uncacheable content within cacheable pages:

$build['dynamic_part'] = [
  '#lazy_builder' => ['MODULE_NAME.my_service:renderDynamic', [$entity_id]],
  '#create_placeholder' => TRUE,
];