Cache contexts are now hierarchical

Change record status: 
Project: 
Introduced in branch: 
8.0.x
Introduced in version: 
8.0.0-BETA8
Description: 

When varying something per-user, it's pointless to also vary that per-role. But if one part of the page is varied per user and another per role, then Drupal needs to be smart enough to make the combination of the two only vary per user.

Therefore, a hierarchy of cache contexts is necessary. This is crucial for ensuring good cache hit ratios. (And therefore also for #2429617: Make D8 2x as fast: SmartCache: context-dependent page caching (for *all* users!).)

Also see the docs: https://www.drupal.org/developing/api/8/cache/contexts

Before

Not only is there no hierarchy information, it's also kind of a jungle to wade through.

book_navigation

language

menu.active_trail

node_view_grants

pager

theme

timezone

url

user

user.roles

After

We've established a clear pattern to define the tree:

  • periods separate parents from children
  • everywhere where cache contexts are used, that entire hierarchy is listed, which has 3 benefits:
    1. no ambiguity: it's clear what parent cache context is based on wherever it is used
    2. comparing (and folding) cache contexts becomes simpler: if both a.b.c and a.b are present, it's obvious that a.b encompasses a.b.c, and thus it's clear why the a.b can be omitted, why it can be "folded" into the parent
    3. no need to deal with ensuring each level in a tree is unique in the entire tree
  • a plurally named cache context indicates a parameter may be specified; to use: append a colon, then specify the desired parameter (when no parameter is specified, all possible parameters are captured, e.g. all query arguments)
cookies

  :name

headers

  :name

ip

languages

  :type

request_format

route

  .book_navigation

  .menu_active_trails

    :menu_name

  .name

theme

timezone

url

  .host

  .query_args

    :key

    .pagers

      :pager_id

user

  .is_super_user

  .node_grants

    :operation

  .roles

    :role

Updating existing code

Unaffected cache contexts:

  • theme
  • timezone
  • url
  • user
  • user.roles

Affected cache contexts:

  • pager:0 -> url.query_args.pagers:0
  • language -> languages
  • node_view_grants -> user.node_grants:view
  • menu_active_trail:tools -> url.route.menu_active_trails:tools

New cache contexts:

  • cookies
  • cookies:<name>
  • headers
  • headers:<name>
  • ip
  • languages:<type>
  • request_format
  • route
  • route.menu_active_trails
  • route.name
  • url.host
  • url.pagers
  • url.query_args
  • url.query_args:<key>
  • user.is_super_user
  • user.node_grants
  • user.node_grants:<operation other than view>
  • user.roles:<role>
Impacts: 
Module developers

Updates Done (doc team, etc.)
Online documentation: 
Generic online documentation done
Theming guide: 
Not done
Module developer documentation: 
Module developer documentation done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Not done