As a developer, I want to see a list of cache tags and contexts available to me, so I can make the most intelligent use of the cache API in my contrib modules and custom code.
I have often needed to set cache tags or contexts on a custom block I've made and found myself grepping through core to figure out what's available. ("Was it node_list
? Or entity_list
? Is there a cache tag for nodes by content type?") As far as I can tell, that's the only way to get that information right now. It would be extremely helpful to have either a handbook page or API documentation that lists all the cache tags and contexts available in Drupal core and explains their uses and effects.
As a developer looking at the documentation, I also wonder things like whether or not I can create my own cache tags and contexts and how I would go about doing so--but that may be a separate issue.
Comments
Comment #2
cilefen CreditAttribution: cilefen commented+1
I know, I know, I know that many people have put in time making the documentation clearer. And more is added every day. But what exists now is not yet instructive enough or comprehensive enough.
As one example, as far as I know, every core context is listed in the handbook but they are not really explained.
Now, all that said, I don't know for sure why we need a core issue to track this, unless we are talking about adding documentation to the code. The handbook pages have discussions (example: https://www.drupal.org/node/2459039/discuss).
Comment #3
cilefen CreditAttribution: cilefen commentedComment #4
Wim LeersA list of cache tags does not make sense. If you have 1 million nodes, you have 1 million node cache tags. and so on.
All core cache contexts are listed at https://www.drupal.org/docs/8/api/cache-api/cache-contexts. Few contrib modules add their own cache contexts, but if you want to see those too, see that page's section: basically just grep for
cache_context.*
in your D8 site's services.That's exactly what https://www.drupal.org/docs/8/api/cache-api/cache-tags explains: .
https://www.drupal.org/docs/8/api/cache-api/cache-tags + https://www.drupal.org/docs/8/api/cache-api/cache-contexts already explain this.
Comment #5
cilefen CreditAttribution: cilefen commentedThe cache API doc links to https://www.drupal.org/docs/8/api/cache-api/cache-contexts. I feel each could be better explained on the handbook page, closer to what is written in their respective classes. But, this discussion should move there.
Comment #6
cilefen CreditAttribution: cilefen commentedNote the API doc also reads: