Commit fe04699e authored by catch's avatar catch

Issue #2429257 by Wim Leers, Fabianx, effulgentsia: Bubble cache contexts

parent 9dfa950c
......@@ -21,6 +21,26 @@ class Cache {
*/
const PERMANENT = CacheBackendInterface::CACHE_PERMANENT;
/**
* Merges arrays of cache contexts and removes duplicates.
*
* @param string[] …
* Arrays of cache contexts to merge.
*
* @return string[]
* The merged array of cache contexts.
*/
public static function mergeContexts() {
$cache_context_arrays = func_get_args();
$cache_contexts = [];
foreach ($cache_context_arrays as $contexts) {
$cache_contexts = array_merge($cache_contexts, $contexts);
}
$cache_contexts = array_unique($cache_contexts);
sort($cache_contexts);
return $cache_contexts;
}
/**
* Merges arrays of cache tags and removes duplicates.
*
......
......@@ -105,6 +105,7 @@ public function getLabels($include_calculated_cache_contexts = FALSE) {
* @throws \InvalidArgumentException
*/
public function convertTokensToKeys(array $context_tokens) {
sort($context_tokens);
$keys = [];
foreach (static::parseTokens($context_tokens) as $context) {
list($context_id, $parameter) = $context;
......
......@@ -185,9 +185,6 @@ protected function getBuildDefaults(EntityInterface $entity, $view_mode, $langco
'contexts' => array(
'theme',
'user.roles',
// @todo Move this out of here and into field formatters that depend
// on the timezone. Blocked on https://drupal.org/node/2099137.
'timezone',
),
'bin' => $this->cacheBin,
);
......
......@@ -30,6 +30,9 @@ class LanguageFormatter extends FormatterBase {
public function viewElements(FieldItemListInterface $items) {
$elements = array();
// The 'language' cache context is not necessary, because what is printed
// here is the language's name in English, not in the language of the
// response.
foreach ($items as $delta => $item) {
$elements[$delta] = array('#markup' => $item->language ? String::checkPlain($item->language->getName()) : '');
}
......
......@@ -31,7 +31,14 @@ public function viewElements(FieldItemListInterface $items) {
$elements = array();
foreach ($items as $delta => $item) {
$elements[$delta] = array('#markup' => format_date($item->value));
$elements[$delta] = [
'#cache' => [
'contexts' => [
'timezone',
],
],
'#markup' => format_date($item->value)
];
}
return $elements;
......
......@@ -17,6 +17,13 @@
*/
class BubbleableMetadata {
/**
* Cache contexts.
*
* @var string[]
*/
protected $contexts;
/**
* Cache tags.
*
......@@ -41,6 +48,8 @@ class BubbleableMetadata {
/**
* Constructs a BubbleableMetadata value object.
*
* @param string[] $contexts
* An array of cache contexts.
* @param string[] $tags
* An array of cache tags.
* @param array $attached
......@@ -48,7 +57,8 @@ class BubbleableMetadata {
* @param array $post_render_cache
* An array of #post_render_cache metadata.
*/
public function __construct(array $tags = [], array $attached = [], array $post_render_cache = []) {
public function __construct(array $contexts = [], array $tags = [], array $attached = [], array $post_render_cache = []) {
$this->contexts = $contexts;
$this->tags = $tags;
$this->attached = $attached;
$this->postRenderCache = $post_render_cache;
......@@ -69,6 +79,7 @@ public function __construct(array $tags = [], array $attached = [], array $post_
*/
public function merge(BubbleableMetadata $other) {
$result = new BubbleableMetadata();
$result->contexts = Cache::mergeContexts($this->contexts, $other->contexts);
$result->tags = Cache::mergeTags($this->tags, $other->tags);
$result->attached = Renderer::mergeAttachments($this->attached, $other->attached);
$result->postRenderCache = NestedArray::mergeDeep($this->postRenderCache, $other->postRenderCache);
......@@ -82,6 +93,7 @@ public function merge(BubbleableMetadata $other) {
* A render array.
*/
public function applyTo(array &$build) {
$build['#cache']['contexts'] = $this->contexts;
$build['#cache']['tags'] = $this->tags;
$build['#attached'] = $this->attached;
$build['#post_render_cache'] = $this->postRenderCache;
......@@ -97,6 +109,7 @@ public function applyTo(array &$build) {
*/
public static function createFromRenderArray(array $build) {
$meta = new static();
$meta->contexts = (isset($build['#cache']['contexts'])) ? $build['#cache']['contexts'] : [];
$meta->tags = (isset($build['#cache']['tags'])) ? $build['#cache']['tags'] : [];
$meta->attached = (isset($build['#attached'])) ? $build['#attached'] : [];
$meta->postRenderCache = (isset($build['#post_render_cache'])) ? $build['#post_render_cache'] : [];
......
......@@ -166,6 +166,7 @@ protected function doRender(&$elements, $is_root_call = FALSE) {
// Try to fetch the prerendered element from cache, run any
// #post_render_cache callbacks and return the final markup.
$pre_bubbling_cid = NULL;
if (isset($elements['#cache'])) {
$cached_element = $this->cacheGet($elements);
if ($cached_element !== FALSE) {
......@@ -185,6 +186,15 @@ protected function doRender(&$elements, $is_root_call = FALSE) {
$this->bubbleStack();
return $elements['#markup'];
}
else {
// Two-tier caching: set pre-bubbling cache ID, if this element is
// cacheable..
// @see ::cacheGet()
// @see ::cacheSet()
if ($this->requestStack->getCurrentRequest()->isMethodSafe() && $cid = $this->createCacheID($elements)) {
$pre_bubbling_cid = $cid;
}
}
}
// If the default values for this element have not been loaded yet, populate
......@@ -206,6 +216,7 @@ protected function doRender(&$elements, $is_root_call = FALSE) {
}
// Defaults for bubbleable rendering metadata.
$elements['#cache']['contexts'] = isset($elements['#cache']['contexts']) ? $elements['#cache']['contexts'] : array();
$elements['#cache']['tags'] = isset($elements['#cache']['tags']) ? $elements['#cache']['tags'] : array();
$elements['#attached'] = isset($elements['#attached']) ? $elements['#attached'] : array();
$elements['#post_render_cache'] = isset($elements['#post_render_cache']) ? $elements['#post_render_cache'] : array();
......@@ -347,7 +358,7 @@ protected function doRender(&$elements, $is_root_call = FALSE) {
// Cache the processed element if #cache is set, and the metadata necessary
// to generate a cache ID is present.
if (isset($elements['#cache']) && (isset($elements['#cache']['keys']) || isset($elements['#cache']['cid']))) {
$this->cacheSet($elements);
$this->cacheSet($elements, $pre_bubbling_cid);
}
// Only when we're in a root (non-recursive) drupal_render() call,
......@@ -495,6 +506,12 @@ protected function cacheGet(array $elements) {
if (!empty($cid) && ($cache_bin = $this->cacheFactory->get($bin)) && $cache = $cache_bin->get($cid)) {
$cached_element = $cache->data;
// Two-tier caching: redirect to actual (post-bubbling) cache item.
// @see ::doRender()
// @see ::cacheSet()
if (isset($cached_element['#cache_redirect'])) {
return $this->cacheGet($cached_element);
}
// Return the cached element.
return $cached_element;
}
......@@ -508,13 +525,15 @@ protected function cacheGet(array $elements) {
*
* @param array $elements
* A renderable array.
* @param string|null $pre_bubbling_cid
* The pre-bubbling cache ID.
*
* @return bool|null
* Returns FALSE if no cache item could be created, NULL otherwise.
*
* @see ::getFromCache()
*/
protected function cacheSet(array &$elements) {
protected function cacheSet(array &$elements, $pre_bubbling_cid) {
// Form submissions rely on the form being built during the POST request,
// and render caching of forms prevents this from happening.
// @todo remove the isMethodSafe() check when
......@@ -525,14 +544,174 @@ protected function cacheSet(array &$elements) {
$data = $this->getCacheableRenderArray($elements);
// Cache tags are cached, but we also want to assocaite the "rendered" cache
// Cache tags are cached, but we also want to associate the "rendered" cache
// tag. This allows us to invalidate the entire render cache, regardless of
// the cache bin.
$data['#cache']['tags'][] = 'rendered';
$bin = isset($elements['#cache']['bin']) ? $elements['#cache']['bin'] : 'render';
$expire = isset($elements['#cache']['expire']) ? $elements['#cache']['expire'] : Cache::PERMANENT;
$this->cacheFactory->get($bin)->set($cid, $data, $expire, $data['#cache']['tags']);
$cache = $this->cacheFactory->get($bin);
// Two-tier caching: detect different CID post-bubbling, create redirect,
// update redirect if different set of cache contexts.
// @see ::doRender()
// @see ::cacheGet()
if (isset($pre_bubbling_cid) && $pre_bubbling_cid !== $cid) {
// The cache redirection strategy we're implementing here is pretty
// simple in concept. Suppose we have the following render structure:
// - A (pre-bubbling, specifies #cache['keys'] = ['foo'])
// -- B (specifies #cache['contexts'] = ['b'])
//
// At the time that we're evaluating whether A's rendering can be
// retrieved from cache, we won't know the contexts required by its
// children (the children might not even be built yet), so cacheGet()
// will only be able to get what is cached for a $cid of 'foo'. But at
// the time we're writing to that cache, we do know all the contexts that
// were specified by all children, so what we need is a way to
// persist that information between the cache write and the next cache
// read. So, what we can do is store the following into 'foo':
// [
// '#cache_redirect' => TRUE,
// '#cache' => [
// ...
// 'contexts' => ['b'],
// ],
// ]
//
// This efficiently lets cacheGet() redirect to a $cid that includes all
// of the required contexts. The strategy is on-demand: in the case where
// there aren't any additional contexts required by children that aren't
// already included in the parent's pre-bubbled #cache information, no
// cache redirection is needed.
//
// When implementing this redirection strategy, special care is needed to
// resolve potential cache ping-pong problems. For example, consider the
// following render structure:
// - A (pre-bubbling, specifies #cache['keys'] = ['foo'])
// -- B (pre-bubbling, specifies #cache['contexts'] = ['b'])
// --- C (pre-bubbling, specifies #cache['contexts'] = ['c'])
// --- D (pre-bubbling, specifies #cache['contexts'] = ['d'])
//
// Additionally, suppose that:
// - C only exists for a 'b' context value of 'b1'
// - D only exists for a 'b' context value of 'b2'
// This is an acceptable variation, since B specifies that its contents
// vary on context 'b'.
//
// A naive implementation of cache redirection would result in the
// following:
// - When a request is processed where context 'b' = 'b1', what would be
// cached for a $pre_bubbling_cid of 'foo' is:
// [
// '#cache_redirect' => TRUE,
// '#cache' => [
// ...
// 'contexts' => ['b', 'c'],
// ],
// ]
// - When a request is processed where context 'b' = 'b2', we would
// retrieve the above from cache, but when following that redirection,
// get a cache miss, since we're processing a 'b' context value that
// has not yet been cached. Given the cache miss, we would continue
// with rendering the structure, perform the required context bubbling
// and then overwrite the above item with:
// [
// '#cache_redirect' => TRUE,
// '#cache' => [
// ...
// 'contexts' => ['b', 'd'],
// ],
// ]
// - Now, if a request comes in where context 'b' = 'b1' again, the above
// would redirect to a cache key that doesn't exist, since we have not
// yet cached an item that includes 'b'='b1' and something for 'd'. So
// we would process this request as a cache miss, at the end of which,
// we would overwrite the above item back to:
// [
// '#cache_redirect' => TRUE,
// '#cache' => [
// ...
// 'contexts' => ['b', 'c'],
// ],
// ]
// - The above would always result in accurate renderings, but would
// result in poor performance as we keep processing requests as cache
// misses even though the target of the redirection is cached, and
// it's only the redirection element itself that is creating the
// ping-pong problem.
//
// A way to resolve the ping-pong problem is to eventually reach a cache
// state where the redirection element includes all of the contexts used
// throughout all requests:
// [
// '#cache_redirect' => TRUE,
// '#cache' => [
// ...
// 'contexts' => ['b', 'c', 'd'],
// ],
// ]
//
// We can't reach that state right away, since we don't know what the
// result of future requests will be, but we can incrementally move
// towards that state by progressively merging the 'contexts' value
// across requests. That's the strategy employed below and tested in
// \Drupal\Tests\Core\Render\RendererBubblingTest::testConditionalCacheContextBubblingSelfHealing().
// The set of cache contexts for this element, including the bubbled ones,
// for which we are handling a cache miss.
$cache_contexts = $data['#cache']['contexts'];
// Get the contexts by which this element should be varied according to
// the current redirecting cache item, if any.
$stored_cache_contexts = [];
$stored_cache_tags = [];
if ($stored_cache_redirect = $cache->get($pre_bubbling_cid)) {
$stored_cache_contexts = $stored_cache_redirect->data['#cache']['contexts'];
$stored_cache_tags = $stored_cache_redirect->data['#cache']['tags'];
}
// Calculate the union of the cache contexts for this request and the
// stored cache contexts.
$merged_cache_contexts = Cache::mergeContexts($stored_cache_contexts, $cache_contexts);
// Stored cache contexts incomplete: this request causes cache contexts to
// be added to the redirecting cache item.
if (array_diff($merged_cache_contexts, $stored_cache_contexts)) {
$redirect_data = [
'#cache_redirect' => TRUE,
'#cache' => [
// The cache keys of the current element; this remains the same
// across requests.
'keys' => $elements['#cache']['keys'],
// The union of the current element's and stored cache contexts.
'contexts' => $merged_cache_contexts,
// The union of the current element's and stored cache tags.
'tags' => Cache::mergeTags($stored_cache_tags, $data['#cache']['tags']),
],
];
$cache->set($pre_bubbling_cid, $redirect_data, $expire, $redirect_data['#cache']['tags']);
}
// Current cache contexts incomplete: this request only uses a subset of
// the cache contexts stored in the redirecting cache item. Vary by these
// additional (conditional) cache contexts as well, otherwise the
// redirecting cache item would be pointing to a cache item that can never
// exist.
if (array_diff($merged_cache_contexts, $cache_contexts)) {
// Recalculate the cache ID.
$recalculated_cid_pseudo_element = [
'#cache' => [
'keys' => $elements['#cache']['keys'],
'contexts' => $merged_cache_contexts,
]
];
$cid = $this->createCacheID($recalculated_cid_pseudo_element);
// Ensure the about-to-be-cached data uses the merged cache contexts.
$data['#cache']['contexts'] = $merged_cache_contexts;
}
}
$cache->set($cid, $data, $expire, $data['#cache']['tags']);
}
/**
......@@ -572,6 +751,7 @@ public function getCacheableRenderArray(array $elements) {
'#attached' => $elements['#attached'],
'#post_render_cache' => $elements['#post_render_cache'],
'#cache' => [
'contexts' => $elements['#cache']['contexts'],
'tags' => $elements['#cache']['tags'],
],
];
......
......@@ -72,13 +72,31 @@ public function renderPlain(&$elements);
* provided by the children is typically inserted into the markup generated by
* the parent array.
*
* An important aspect of rendering is the bubbling of rendering metadata:
* cache tags, attached assets and #post_render_cache metadata all need to be
* bubbled up. That information is needed once the rendering to a HTML string
* is completed: the resulting HTML for the page must know by which cache tags
* it should be invalidated, which (CSS and JavaScript) assets must be loaded,
* and which #post_render_cache callbacks should be executed. A stack data
* structure is used to perform this bubbling.
* An important aspect of rendering is caching the result, when appropriate.
* Because the HTML of a rendered item includes all of the HTML of the
* rendered children, caching it requires certain information to bubble up
* from child elements to their parents:
* - Cache contexts, so that the render cache is varied by every context that
* affects the rendered HTML. Because cache contexts affect the cache ID,
* and therefore must be resolved for cache hits as well as misses, it is
* up to the implementation of this interface to decide how to implement
* the caching of items whose children specify cache contexts not directly
* specified by the parent. \Drupal\Core\Render\Renderer implements this
* with a lazy two-tier caching strategy. Alternate strategies could be to
* not cache such parents at all or to cache them with the child elements
* replaced by placeholder tokens that are dynamically rendered after cache
* retrieval.
* - Cache tags, so that cached renderings are invalidated when site content
* or configuration that can affect that rendering changes.
* - #post_render_cache callbacks, for executing code to handle dynamic
* requirements that cannot be cached.
* A stack of \Drupal\Core\Render\BubbleableMetadata objects can be used to
* perform this bubbling.
*
* Additionally, whether retrieving from cache or not, it is important to
* know all of the assets (CSS and JavaScript) required by the rendered HTML,
* and this must also bubble from child to parent. Therefore,
* \Drupal\Core\Render\BubbleableMetadata includes that data as well.
*
* The process of rendering an element is recursive unless the element defines
* an implemented theme hook in #theme. During each call to
......@@ -111,6 +129,20 @@ public function renderPlain(&$elements);
* metadata from the element retrieved from render cache. Then, this stack
* frame is bubbled: the two topmost frames are popped from the stack,
* they are merged, and the result is pushed back onto the stack.
* However, also in case of a cache miss we have to do something. Note
* that a Renderer renders top-down, which means that we try to render a
* parent first, and we try to avoid the work of rendering the children by
* using the render cache. Though in this case, we are dealing with a
* cache miss. So a Renderer traverses down the tree, rendering all
* children. In doing so, the render stack is updated with the bubbleable
* metadata of the children. That means that once the children are
* rendered, we can render cache this element. But the cache ID may have
* *changed* at that point, because the children's cache contexts have
* been bubbled!
* It is for that case that we must store the current (pre-bubbling) cache
* ID, so that we can compare it with the new (post-bubbling) cache ID
* when writing to the cache. We store the current cache ID in
* $pre_bubbling_cid.
* - If this element has #type defined and the default attributes for this
* element have not already been merged in (#defaults_loaded = TRUE) then
* the defaults for this type of element, defined in hook_element_info(),
......@@ -210,6 +242,12 @@ public function renderPlain(&$elements);
* - If this element has #cache defined, the rendered output of this element
* is saved to Renderer::render()'s internal cache. This includes the
* changes made by #post_render.
* At the same time, if $pre_bubbling_cid is set, it is compared to the
* calculated cache ID. If they are different, then a redirecting cache
* item is created, containing the #cache metadata of the current element,
* and written to cache using the value of $pre_bubbling_cid as the cache
* ID. This ensures the pre-bubbling ("wrong") cache ID redirects to the
* post-bubbling ("right") cache ID.
* - If this element has an array of #post_render_cache functions defined,
* or any of its children has (which we would know thanks to the stack
* having been updated just before the render caching step), they are
......
......@@ -157,6 +157,7 @@ public function viewElements(FieldItemListInterface $items) {
// Unpublished comments are not included in
// $entity->get($field_name)->comment_count, but unpublished comments
// should display if the user is an administrator.
$elements['#cache']['contexts'][] = 'user.roles';
if ($this->currentUser->hasPermission('access comments') || $this->currentUser->hasPermission('administer comments')) {
// This is a listing of Comment entities, so associate its list cache
// tag for correct invalidation.
......@@ -182,6 +183,7 @@ public function viewElements(FieldItemListInterface $items) {
// display below the entity. Do not show the form for the print view mode.
if ($status == CommentItemInterface::OPEN && $comment_settings['form_location'] == CommentItemInterface::FORM_BELOW && $this->viewMode != 'print') {
// Only show the add comment form if the user has permission.
$elements['#cache']['contexts'][] = 'user.roles';
if ($this->currentUser->hasPermission('post comments')) {
// All users in the "anonymous" role can use the same form: it is fine
// for this form to be stored in the render cache.
......
......@@ -127,6 +127,11 @@ public function viewElements(FieldItemListInterface $items) {
// Display the date using theme datetime.
$elements[$delta] = array(
'#cache' => [
'contexts' => [
'timezone',
],
],
'#theme' => 'time',
'#text' => $formatted_date,
'#html' => FALSE,
......
......@@ -46,7 +46,14 @@ public function viewElements(FieldItemListInterface $items) {
}
$output = $date->format($format);
}
$elements[$delta] = array('#markup' => $output);
$elements[$delta] = [
'#cache' => [
'contexts' => [
'timezone',
],
],
'#markup' => $output,
];
}
return $elements;
......
......@@ -85,6 +85,13 @@ class FilterProcessResult {
*/
protected $cacheTags;
/**
* The associated cache contexts.
*
* @var string[]
*/
protected $cacheContexts;
/**
* The associated #post_render_cache callbacks.
*
......@@ -105,6 +112,7 @@ public function __construct($processed_text) {
$this->assets = array();
$this->cacheTags = array();
$this->cacheContexts = array();
$this->postRenderCacheCallbacks = array();
}
......@@ -174,6 +182,41 @@ public function setCacheTags(array $cache_tags) {
return $this;
}
/**
* Gets cache contexts associated with the processed text.
*
* @return string[]
*/
public function getCacheContexts() {
return $this->cacheContexts;
}
/**
* Adds cache contexts associated with the processed text.
*
* @param string[] $cache_contexts
* The cache contexts to be added.
*
* @return $this
*/
public function addCacheContexts(array $cache_contexts) {
$this->cacheContexts = Cache::mergeContexts($this->cacheContexts, $cache_contexts);
return $this;
}
/**
* Sets cache contexts associated with the processed text.
*
* @param string[] $cache_contexts
* The cache contexts to be associated.
*
* @return $this
*/
public function setCacheContexts(array $cache_contexts) {
$this->cacheContexts = $cache_contexts;
return $this;
}
/**
* Gets assets associated with the processed text.
*
......@@ -256,6 +299,7 @@ public function setPostRenderCacheCallbacks(array $post_render_cache_callbacks)
*/
public function getBubbleableMetadata() {
return new BubbleableMetadata(
$this->getCacheContexts(),
$this->getCacheTags(),
$this->getAssets(),
$this->getPostRenderCacheCallbacks()
......
......@@ -216,6 +216,10 @@ function testProcessedTextElement() {
'weight' => 0,
'status' => TRUE,
),
'filter_test_cache_contexts' => array(
'weight' => 0,
'status' => TRUE,
),
'filter_test_post_render_cache' => array(
'weight' => 1,
'status' => TRUE,
......@@ -253,6 +257,11 @@ function testProcessedTextElement() {
'foo:baz',
);
$this->assertEqual($expected_cache_tags, $build['#cache']['tags'], 'Expected cache tags present.');
$expected_cache_contexts = [
// The cache context set by the filter_test_cache_contexts filter.
'language',
];
$this->assertEqual($expected_cache_contexts, $build['#cache']['contexts'], 'Expected cache contexts present.');
$expected_markup = '<p>Hello, world!</p><p>This is a dynamic llama.</p>';
$this->assertEqual($expected_markup, $build['#markup'], 'Expected #post_render_cache callback has been applied.');
}
......
<?php
/**
* @file
* Contains \Drupal\filter_test\Plugin\Filter\FilterTestCacheContexts.
*/
namespace Drupal\filter_test\Plugin\Filter;
use Drupal\filter\FilterProcessResult;
use Drupal\filter\Plugin\FilterBase;
/**
* Provides a test filter to associate cache contexts.
*
* @Filter(
* id = "filter_test_cache_contexts",
* title = @Translation("Testing filter"),
* description = @Translation("Does not change content; associates cache contexts."),
* type = Drupal\filter\Plugin\FilterInterface::TYPE_TRANSFORM_REVERSIBLE
* )
*/
class FilterTestCacheContexts extends FilterBase {
/**
* {@inheritdoc}
*/