Understanding Drupal’s Cache Tags and Contexts in Drupal 10

Why Caching Matters

Caching helps reduce the time it takes for a page to load. Instead of rebuilding a page from scratch every time a user visits, Drupal can serve a cached version — a stored copy — to save time.

However, simple caching can cause problems. What if a piece of content changes? Or what if two users should see slightly different versions of a page?

Drupal solves this with a smart caching system that knows exactly what to rebuild and when to do it.

What Are Cache Tags?

Cache Tags are like labels attached to cached data. They help Drupal identify what specific content or configuration is being stored.

For example:

• A node (article, page, etc.) might have the cache tag node:5.
• A block that depends on that node will also carry that tag.

So when node 5 is updated, Drupal automatically knows to invalidate all caches that use the tag node:5.

This means:
    Only the necessary parts of the cache are cleared.
    Other pages that don’t depend on that node remain cached.

Example of Cache Tags in Action

Let’s say your homepage displays a “Latest Articles” block. Each article node has its own cache tag, like node:3, node:5, and node:8.

If you update node:5, Drupal doesn’t have to clear the entire homepage cache — it just clears the parts linked to node:5.

That’s what makes Drupal’s caching system efficient and intelligent.

What Are Cache Contexts?

While cache tags decide when something should be invalidated, Cache Contexts decide for whom or under what conditions a cache should vary.

Think of cache contexts as the “dynamic” part of caching — they handle different scenarios.

For example:

• The user context makes a cache vary by the logged-in user.
• The languages context varies cache depending on the site’s language.
• The theme context varies cache based on which theme is active.

Example of Cache Contexts

Imagine a block that displays “Welcome, {{ username }}!”

Drupal shouldn’t show the same cached version of that block to every user.
 By using the user cache context, Drupal ensures that each logged-in user sees their personalized version of the block.

'#cache' => [

  'contexts' => ['user'],

],

This means:
    Each user gets their own cached output.
    Drupal doesn’t rebuild the block unnecessarily for every request.

Cache Tags + Contexts = Smart Caching

Together, Cache Tags and Contexts make Drupal’s caching system both precise and personalized.

• Cache Tags = Know what to clear when content changes.
• Cache Contexts = Know when to serve different cached versions for different users or conditions.

This balance gives Drupal 10 the ability to perform efficiently while still delivering the right content to the right audience.

Example: Using Cache Tags and Contexts in a Custom Block

Here’s a quick example of how you might define caching in a custom Drupal block plugin:

public function build() {

  return [

    '#markup' => $this->t('Welcome, @name!', ['@name' => $this->currentUser()->getDisplayName()]),

    '#cache' => [

      'tags' => ['user:' . $this->currentUser()->id()],

      'contexts' => ['user'],

      'max-age' => 3600, // Optional: sets the cache lifetime

    ],

  ];

}

What this does:

• The block will update if the user changes their profile (because of user: cache tag).
• Each user sees a different message (user cache context).
• The cache expires automatically after one hour (max-age).

Benefits of Drupal’s Smart Caching

• Speed: Pages load much faster by reusing cached content.
• Precision: Only the parts affected by a change are cleared.
• Scalability: Works well for large, dynamic sites with many users.
• Flexibility: Developers can control exactly how and when caches are used.

When to Use Cache Tags and Contexts

Use cache tags when your data depends on content that can change — like nodes, views, or configurations.
 Use cache contexts when your output should vary based on a condition — like user roles, language, or device type.

Together, they make Drupal caching both powerful and predictable.

Conclusion

In Drupal 10, caching is smarter than ever. Thanks to Cache Tags and Cache Contexts, your site can stay fast, dynamic, and reliable without unnecessary rebuilding.

They ensure that every user gets the right content at lightning speed — and that developers have full control over how caching behaves.

So the next time you’re optimizing performance or writing a custom module, remember:

Cache Tags keep your data fresh. Cache Contexts keep it relevant.

References:

• Drupal.org – Cache API Overview