Cache context

Cache contexts = (request) contextual dependencies

Cache contexts are similar to the HTTP Vary header.

Why?

Cache contexts provide a way to create context-dependent variants of something that needs to be cached. It makes caching logic easier to read and avoids repeating the same conditional logic wherever context-based variation is needed.

Examples:

• Output varies depending on the active theme → use the theme cache context.
• A render array displays a personalized message → use the user cache context.
• Expensive computation that depends on the server environment → use the appropriate context.

How?

A cache context is a string referring to one of the available cache context services (see below).

Cache contexts are passed as unordered string arrays (string[]), because a cacheable item may depend on multiple contexts.

Typically, cache contexts are derived from the request context (HTTP requests). However, some may also depend on deployment-specific settings, like deployment_id.

Contexts are defined hierarchically. For instance, if a part of a page varies by user and another by permission, Drupal can simplify and avoid caching unnecessarily fine-grained variants.

Syntax

• Dots . separate parent from child contexts.
• Plural names can take parameters using : (e.g., user.roles:anonymous).

Drupal 8 Core Cache Context Hierarchy

cookies
  :name
headers
  :name
ip
languages
  :type
protocol_version
request_format
route
  .book_navigation
  .menu_active_trails
    :menu_name
  .name
session
  .exists
theme
timezone
url
  .path
    .is_front
    .parent
  .query_args
    :key
    .pagers
      :pager_id
  .site
user
  .is_super_user
  .node_grants
    :operation
  .permissions
  .roles
    :role

Note: To use url.path.is_front on older versions, see this change record.

Examples

• theme – varies by current theme
• user.roles – varies by user role combination
• user.roles:anonymous – varies by whether the user is anonymous
• languages:language_interface – varies by interface language
• url.query_args:foo – varies by query parameter foo
• protocol_version – varies by HTTP/1 vs HTTP/2

Optimization & Simplification

Drupal automatically simplifies cache contexts using hierarchy rules. For example:

If one part varies by user and another by user.permissions, then only user is needed:

optimize([user, user.permissions]) = [user]

Even though user.permissions is more specific, its result will still vary per user.

If a cache context like user.node_grants has max-age = 0, then it can’t be optimized and must remain. In contrast, if user.node_grants has max-age = 3600, then it can be optimized out and replaced by user in caching logic.

How to Discover and Create Cache Contexts

Cache contexts are services tagged with cache.context. Any module can define its own.

They implement CacheContextInterface or CalculatedCacheContextInterface (for parameterized contexts).

You can find them using an IDE (by searching implementations of the interface) or use the Drupal Console:

$ drupal debug:cache:context

Example:

cache_context.route.book_navigation:
  class: Drupal\book\Cache\BookNavigationCacheContext
  arguments: ['@request_stack']
  tags:
    - { name: cache.context }

Debugging

Cache ID (CID) structure for debugging:

foo:bar:[languages:language_interface]=en:[user.permissions]=HASH:[route]=route_name.PARAMS_HASH

• Keys come first, in order.
• Cache contexts follow in alphabetical order.
• Each is formatted as [context]=value.

Debug Headers

Check the X-Drupal-Cache-Contexts HTTP response header to see active cache contexts.

If it’s missing, enable development settings.

Dynamic Page Cache

Comprehensive use of cache contexts in Drupal 8 enables a dynamic page cache, enabled by default in core.

Internal Page Cache

The internal page cache assumes all pages served to anonymous users are identical. If content varies by cache context for anonymous users, this module should be disabled (may affect performance).

See Also

• Cacheability of render arrays
• Cache tags
• Cache max-age