Change record status: 
Project: 
Introduced in branch: 
8.x
Introduced in version: 
8.0-alpha3
Description: 

By leveraging the unified entity rendering process and cache tags from Drupal 8 and the Render API caching (from Drupal 7), the resulting output of EntityViewBilder::view() and EntityViewBilder::viewMultiple() is now cached by default.

Note: The render cache is disabled at the moment for node and comment entities due to some outstanding issues with comment links, which are handled in #2090783: Run comment op links (delete, edit, reply, approve + contrib) through #post_render_cache to prevent render caching granularity being per-user. @todo Rejoice and delete this note when that issue is fixed.

How it works

When an entity goes through the rendering process, cache tags that are relevant to that entity are added to the render array. What does relevant mean in this context? Well, the ID of the entity and also the IDs of all the other entities that are referenced by it. For example: when a node is rendered, the cache tags will include the node ID and also the ID of node's author (a User entity). If the node contains another reference field targeting, lets say, a taxonomy term, the ID of that term will also be added.

The reason for gathering referenced entity IDs is for cache clearing purposes (which, as they say, is never easy). Thanks to this process, the render cache for an entity can be cleared automatically not only when it is changed (saved or deleted) but also when a referenced entity is changed. For example: if a user changes his username, the cache will be cleared for all the nodes that are authored by him. Likewise, when the name of a taxonomy term is changed, all the nodes that might be tagged with that term must also be updated.

Manual cache clearing

The entity render cache can also be cleared manually, with one of the following options:

  • globally: entity_render_cache_clear()
  • per entity type: \Drupal::entityManager()->getViewBuilder($entity_type)->resetCache()
  • just for a specific set of entities: \Drupal::entityManager()->getViewBuilder($entity_type)->resetCache(array($entity1->id(), $entity2->id()))

Disabling the render cache

The render cache can disabled globally per entity type by setting the 'render_cache' flag to FALSE, or individually per view mode, by settings the 'cache' property to 0.

Example for an entity type:

<?php
/**
 * My awesome entity.
 *
 * @EntityType(
 *   id = "awesome_entity",
 *   ...
 *   render_cache = FALSE,
 *   ...
 * )
 */
?>

Example for a view mode:

entity.view_mode.awesome_entity.full.yml

id: awesome_entity.full
label: Full content
status: '0'
cache: '0'
targetEntityType: awesome_entity

Other changes

A new $reset argument has been added to entity_view() and entity_view_multiple(), for easier rendering fresh (not cached) output of an entity.

Fill the cache correctly: prevent user-specific data

For example, the "new" and "updated" comment markers used to break the render cache: they are clearly user-specific, which means that if they're part of the render array and the render array gets cached, then the data for user X would also be served to users Y and Z. If you want to add user-specific output to entities, then ensure it's done through JavaScript, just like we did for "new" and "updated" comment markers: https://drupal.org/node/2086767.

Impacts: 
Site builders, administrators, editors
Module developers
Themers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done