Cache API

Last updated on
27 October 2023

This documentation needs work. See "Help improve this page" in the sidebar.

Drupal's Cache API enables the storage of data that may require a significant amount of time to calculate. This cached data can have various lifespans; it can be kept indefinitely, set to expire after a specified duration, or configured to expire when related data changes. The following sections go into more detail on each feature.

For a brief run-down, see also the Cache API page from the API documentation.

Cacheability metadata

Cacheability metadata, a fundamental concept within Drupal, ensures efficient caching. It is associated with all elements that can be rendered or influence the rendering process, encompassing a wide range of items from access results to entities and URLs. This metadata includes the information and rules that guide the caching and management of cached data, determining when and how content can be cached and ensuring effective cache invalidation. As a result, it leads to improved website performance and efficiency.

Cacheability metadata comprises three key properties:

Cache Tags

These represent dependencies on data managed by Drupal, such as entities and configuration. When any of these dependencies change, Drupal knows to invalidate or update the cached content, ensuring that your site's data remains up-to-date.

Cache Contexts
These handle variations based on the request context. For instance, they account for variations in content that might be influenced by factors like the user's role or language. Cache contexts enable Drupal to serve personalized content efficiently.
Cache Max-Age
This property is responsible for time-sensitive caching. It defines the duration for which content remains valid in the cache before it needs to be re-fetched. Cache max-age ensures that content remains relevant and reduces the load on your server by minimizing unnecessary recalculations.

Practical: how you'll typically use the Cache API

Typically, your code will end up rendering things (blocks, entities, and so on) and your controllers will return render arrays or responses. So, usually, you won't be interacting with the Cache API directly. Instead you'll be using:

Render caching (aka fragment caching)
The Render API uses cacheability metadata embedded in render arrays to perform caching (aka render caching). Therefore, the Cache API should not be used to interact with the render cache (neither to retrieve cache items nor to create new ones).
See Cacheability of render arrays.
Response caching
The cacheability metadata used by the Render API (see the previous section) bubbles all the way up to Response objects (usually a HtmlResponse) that implement CacheableResponseInterface.
The cacheability metadata on these Response objects is what allows Drupal 8 to ship with Page Cache and Dynamic Page Cache enabled by default, because it allows them to work transparently: they are always up-to-date and always vary appropriately.
See CacheableResponseInterface.

Help improve this page

Page status: Needs work

You can: