aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Render;
   4
   5 /**
   6  * Defines an interface for turning a render array into a placeholder.
   7  *
   8  * This encapsulates logic related to generating placeholders.
   9  *
  10  * Makes it possible to determine whether a render array can be placeholdered
  11  * (it can be reconstructed independently of the request context), whether a
  12  * render array should be placeholdered (its cacheability meets the conditions),
  13  * and to create a placeholder.
  14  *
  15  * @see \Drupal\Core\Render\RendererInterface
  16  */
  17 interface PlaceholderGeneratorInterface {
  18
  19   /**
  20    * Analyzes whether the given render array can be placeholdered.
  21    *
  22    * @param array $element
  23    *   A render array. Its #lazy_builder and #create_placeholder properties are
  24    *   analyzed.
  25    *
  26    * @return bool
  27    */
  28   public function canCreatePlaceholder(array $element);
  29
  30   /**
  31    * Whether the given render array should be automatically placeholdered.
  32    *
  33    * The render array should be placeholdered if its cacheability either has a
  34    * cache context with too high cardinality, a cache tag with a too high
  35    * invalidation rate, or a max-age that is too low. Either of these would make
  36    * caching ineffective, and thus we choose to placeholder instead.
  37    *
  38    * @param array $element
  39    *   The render array whose cacheability to analyze.
  40    *
  41    * @return bool
  42    *   Whether the given render array's cacheability meets the placeholdering
  43    *   conditions.
  44    */
  45   public function shouldAutomaticallyPlaceholder(array $element);
  46
  47   /**
  48    * Turns the given element into a placeholder.
  49    *
  50    * Placeholdering allows us to avoid "poor cacheability contamination": this
  51    * maps the current render array to one that only has #markup and #attached,
  52    * and #attached contains a placeholder with this element's prior cacheability
  53    * metadata. In other words: this placeholder is perfectly cacheable, the
  54    * placeholder replacement logic effectively cordons off poor cacheability.
  55    *
  56    * @param array $element
  57    *   The render array to create a placeholder for.
  58    *
  59    * @return array
  60    *   Render array with placeholder markup and the attached placeholder
  61    *   replacement metadata.
  62    */
  63   public function createPlaceholder(array $element);
  64
  65 }