Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Render;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for turning a render array into a string.
Chris@0:  */
Chris@0: interface RendererInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Renders final HTML given a structured array tree.
Chris@0:    *
Chris@0:    * Calls ::render() in such a way that placeholders are replaced.
Chris@0:    *
Chris@0:    * Should therefore only be used in occasions where the final rendering is
Chris@0:    * happening, just before sending a Response:
Chris@0:    * - system internals that are responsible for rendering the final HTML
Chris@0:    * - render arrays for non-HTML responses, such as feeds
Chris@0:    *
Chris@0:    * (Cannot be executed within another render context.)
Chris@0:    *
Chris@0:    * @param array $elements
Chris@0:    *   The structured array describing the data to be rendered.
Chris@0:    *
Chris@0:    * @return \Drupal\Component\Render\MarkupInterface
Chris@0:    *   The rendered HTML.
Chris@0:    *
Chris@0:    * @throws \LogicException
Chris@0:    *   When called from inside another renderRoot() call.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Render\RendererInterface::render()
Chris@0:    */
Chris@0:   public function renderRoot(&$elements);
Chris@0: 
Chris@0:   /**
Chris@0:    * Renders final HTML in situations where no assets are needed.
Chris@0:    *
Chris@0:    * Calls ::render() in such a way that placeholders are replaced.
Chris@0:    *
Chris@0:    * Useful for instance when rendering the values of tokens or emails, which
Chris@0:    * need a render array being turned into a string, but do not need any of the
Chris@0:    * bubbleable metadata (the attached assets and cache tags).
Chris@0:    *
Chris@0:    * Some of these are a relatively common use case and happen *within* a
Chris@0:    * ::renderRoot() call, but that is generally highly problematic (and hence an
Chris@0:    * exception is thrown when a ::renderRoot() call happens within another
Chris@0:    * ::renderRoot() call). However, in this case, we only care about the output,
Chris@0:    * not about the bubbling. Hence this uses a separate render context, to not
Chris@0:    * affect the parent ::renderRoot() call.
Chris@0:    *
Chris@0:    * (Can be executed within another render context: it runs in isolation.)
Chris@0:    *
Chris@0:    * @param array $elements
Chris@0:    *   The structured array describing the data to be rendered.
Chris@0:    *
Chris@0:    * @return \Drupal\Component\Render\MarkupInterface
Chris@0:    *   The rendered HTML.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Render\RendererInterface::renderRoot()
Chris@0:    * @see \Drupal\Core\Render\RendererInterface::render()
Chris@0:    */
Chris@0:   public function renderPlain(&$elements);
Chris@0: 
Chris@0:   /**
Chris@0:    * Renders final HTML for a placeholder.
Chris@0:    *
Chris@0:    * Renders the placeholder in isolation.
Chris@0:    *
Chris@0:    * @param string $placeholder
Chris@0:    *   An attached placeholder to render. (This must be a key of one of the
Chris@0:    *   values of $elements['#attached']['placeholders'].)
Chris@0:    * @param array $elements
Chris@0:    *   The structured array describing the data to be rendered.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The updated $elements.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Render\RendererInterface::render()
Chris@0:    */
Chris@0:   public function renderPlaceholder($placeholder, array $elements);
Chris@0: 
Chris@0:   /**
Chris@0:    * Renders HTML given a structured array tree.
Chris@0:    *
Chris@0:    * Renderable arrays have two kinds of key/value pairs: properties and
Chris@0:    * children. Properties have keys starting with '#' and their values influence
Chris@0:    * how the array will be rendered. Children are all elements whose keys do not
Chris@0:    * start with a '#'. Their values should be renderable arrays themselves,
Chris@0:    * which will be rendered during the rendering of the parent array. The markup
Chris@0:    * provided by the children is typically inserted into the markup generated by
Chris@0:    * the parent array.
Chris@0:    *
Chris@0:    * An important aspect of rendering is caching the result, when appropriate.
Chris@0:    * Because the HTML of a rendered item includes all of the HTML of the
Chris@0:    * rendered children, caching it requires certain information to bubble up
Chris@0:    * from child elements to their parents:
Chris@0:    * - Cache contexts, so that the render cache is varied by every context that
Chris@0:    *   affects the rendered HTML. Because cache contexts affect the cache ID,
Chris@0:    *   and therefore must be resolved for cache hits as well as misses, it is
Chris@0:    *   up to the implementation of this interface to decide how to implement
Chris@0:    *   the caching of items whose children specify cache contexts not directly
Chris@0:    *   specified by the parent. \Drupal\Core\Render\Renderer implements this
Chris@0:    *   with a lazy two-tier caching strategy. Alternate strategies could be to
Chris@0:    *   not cache such parents at all or to cache them with the child elements
Chris@0:    *   replaced by placeholder tokens that are dynamically rendered after cache
Chris@0:    *   retrieval.
Chris@0:    * - Cache tags, so that cached renderings are invalidated when site content
Chris@0:    *   or configuration that can affect that rendering changes.
Chris@0:    * - Placeholders, with associated self-contained placeholder render arrays,
Chris@0:    *   for executing code to handle dynamic requirements that cannot be cached.
Chris@0:    * A render context (\Drupal\Core\Render\RenderContext) can be used to perform
Chris@0:    * bubbling; it is a stack of \Drupal\Core\Render\BubbleableMetadata objects.
Chris@0:    *
Chris@0:    * Additionally, whether retrieving from cache or not, it is important to
Chris@0:    * know all of the assets (CSS and JavaScript) required by the rendered HTML,
Chris@0:    * and this must also bubble from child to parent. Therefore,
Chris@0:    * \Drupal\Core\Render\BubbleableMetadata includes that data as well.
Chris@0:    *
Chris@0:    * The process of rendering an element is recursive unless the element defines
Chris@0:    * an implemented theme hook in #theme. During each call to
Chris@0:    * Renderer::render(), the outermost renderable array (also known as an
Chris@0:    * "element") is processed using the following steps:
Chris@0:    *   - If this element has already been printed (#printed = TRUE) or the user
Chris@0:    *     does not have access to it (#access = FALSE), then an empty string is
Chris@0:    *     returned.
Chris@0:    *   - If no render context is set yet, an exception is thrown. Otherwise,
Chris@0:    *     an empty \Drupal\Core\Render\BubbleableMetadata is pushed onto the
Chris@0:    *     render context.
Chris@0:    *   - If this element has #cache defined then the cached markup for this
Chris@0:    *     element will be returned if it exists in Renderer::render()'s cache. To
Chris@0:    *     use Renderer::render() caching, set the element's #cache property to an
Chris@0:    *     associative array with one or several of the following keys:
Chris@0:    *     - 'keys': An array of one or more keys that identify the element. If
Chris@0:    *       'keys' is set, the cache ID is created automatically from these keys.
Chris@0:    *     - 'contexts': An array of one or more cache context IDs. These are
Chris@0:    *       converted to a final value depending on the request. (For instance,
Chris@0:    *       'user' is mapped to the current user's ID.)
Chris@0:    *     - 'max-age': A time in seconds. Zero seconds means it is not cacheable.
Chris@0:    *       \Drupal\Core\Cache\Cache::PERMANENT means it is cacheable forever.
Chris@0:    *     - 'bin': Specify a cache bin to cache the element in. Default is
Chris@0:    *       'default'.
Chris@0:    *     When there is a render cache hit, there is no rendering work left to be
Chris@0:    *     done, so the stack must be updated. The empty (and topmost) frame that
Chris@0:    *     was just pushed onto the stack is updated with all bubbleable rendering
Chris@0:    *     metadata from the element retrieved from render cache. Then, this stack
Chris@0:    *     frame is bubbled: the two topmost frames are popped from the stack,
Chris@0:    *     they are merged, and the result is pushed back onto the stack.
Chris@0:    *     However, also in case of a cache miss we have to do something. Note
Chris@0:    *     that a Renderer renders top-down, which means that we try to render a
Chris@0:    *     parent first, and we try to avoid the work of rendering the children by
Chris@0:    *     using the render cache. Though in this case, we are dealing with a
Chris@0:    *     cache miss. So a Renderer traverses down the tree, rendering all
Chris@0:    *     children. In doing so, the render stack is updated with the bubbleable
Chris@0:    *     metadata of the children. That means that once the children are
Chris@0:    *     rendered, we can render cache this element. But the cache ID may have
Chris@0:    *     *changed* at that point, because the children's cache contexts have
Chris@0:    *     been bubbled!
Chris@0:    *     It is for that case that we must store the current (pre-bubbling) cache
Chris@0:    *     ID, so that we can compare it with the new (post-bubbling) cache ID
Chris@0:    *     when writing to the cache. We store the current cache ID in
Chris@0:    *     $pre_bubbling_cid.
Chris@0:    *   - If this element has #type defined and the default attributes for this
Chris@0:    *     element have not already been merged in (#defaults_loaded = TRUE) then
Chris@0:    *     the defaults for this type of element, defined by an element plugin,
Chris@0:    *     are merged into the array. #defaults_loaded is set by functions that
Chris@0:    *     process render arrays and call the element info service before passing
Chris@0:    *     the array to Renderer::render(), such as form_builder() in the Form
Chris@0:    *     API.
Chris@0:    *   - If this element has #create_placeholder set to TRUE, and it has a
Chris@0:    *     #lazy_builder callback, then the element is replaced with another
Chris@0:    *     element that has only two properties: #markup and #attached. #markup
Chris@0:    *     will contain placeholder markup, and #attached contains the placeholder
Chris@0:    *     metadata, that will be used for replacing this placeholder. That
Chris@0:    *     metadata contains a very compact render array (containing only
Chris@0:    *     #lazy_builder and #cache) that will be rendered to replace the
Chris@0:    *     placeholder with its final markup. This means that when the
Chris@0:    *     #lazy_builder callback is called, it received a render array to add to
Chris@0:    *     that only contains #cache.
Chris@0:    *   - If this element has a #lazy_builder or an array of #pre_render
Chris@0:    *     functions defined, they are called sequentially to modify the element
Chris@0:    *     before rendering. #lazy_builder is preferred, since it allows for
Chris@0:    *     placeholdering (see previous step), but #pre_render is still supported.
Chris@0:    *     Both have their use case: #lazy_builder is for building a render array,
Chris@0:    *     #pre_render is for decorating an existing render array.
Chris@0:    *     After the #lazy_builder function is called, #lazy_builder is removed,
Chris@0:    *     and #built is set to TRUE.
Chris@0:    *     After the #lazy_builder and all #pre_render functions have been called,
Chris@0:    *     #printed is checked a second time in case a #lazy_builder or
Chris@0:    *     #pre_render function flags the element as printed. If #printed is set,
Chris@0:    *     we return early and hence no rendering work is left to be done,
Chris@0:    *     similarly to a render cache hit. Once again, the empty (and topmost)
Chris@0:    *     frame that was just pushed onto the stack is updated with all
Chris@0:    *     bubbleable rendering metadata from the element whose #printed = TRUE.
Chris@0:    *     Then, this stack frame is bubbled: the two topmost frames are popped
Chris@0:    *     from the stack, they are merged, and the result is pushed back onto the
Chris@0:    *     stack.
Chris@0:    *   - The child elements of this element are sorted by weight using uasort()
Chris@0:    *     in \Drupal\Core\Render\Element::children(). Since this is expensive,
Chris@0:    *     when passing already sorted elements to Renderer::render(), for example
Chris@0:    *     from a database query, set $elements['#sorted'] = TRUE to avoid sorting
Chris@0:    *     them a second time.
Chris@0:    *   - The main render phase to produce #children for this element takes
Chris@0:    *     place:
Chris@0:    *     - If this element has #theme defined and #theme is an implemented theme
Chris@0:    *       hook/suggestion then ThemeManagerInterface::render() is called and
Chris@0:    *       must render both the element and its children. If #render_children is
Chris@0:    *       set, ThemeManagerInterface::render() will not be called.
Chris@0:    *       #render_children is usually only set internally by
Chris@0:    *       ThemeManagerInterface::render() so that we can avoid the situation
Chris@0:    *       where Renderer::render() called from within a theme preprocess
Chris@0:    *       function creates an infinite loop.
Chris@0:    *     - If this element does not have a defined #theme, or the defined #theme
Chris@0:    *       hook is not implemented, or #render_children is set, then
Chris@0:    *       Renderer::render() is called recursively on each of the child
Chris@0:    *       elements of this element, and the result of each is concatenated onto
Chris@0:    *       #children. This is skipped if #children is not empty at this point.
Chris@0:    *     - Once #children has been rendered for this element, if #theme is not
Chris@0:    *       implemented and #markup is set for this element, #markup will be
Chris@0:    *       prepended to #children.
Chris@0:    *   - If this element has #states defined then JavaScript state information
Chris@0:    *     is added to this element's #attached attribute by
Chris@0:    *     drupal_process_states().
Chris@0:    *   - If this element has #attached defined then any required libraries,
Chris@0:    *     JavaScript, CSS, or other custom data are added to the current page by
Chris@0:    *     \Drupal\Core\Render\AttachmentsResponseProcessorInterface::processAttachments().
Chris@0:    *   - If this element has an array of #theme_wrappers defined and
Chris@0:    *     #render_children is not set, #children is then re-rendered by passing
Chris@0:    *     the element in its current state to ThemeManagerInterface::render()
Chris@0:    *     successively for each item in #theme_wrappers. Since #theme and
Chris@0:    *     #theme_wrappers hooks often define variables with the same names it is
Chris@0:    *     possible to explicitly override each attribute passed to each
Chris@0:    *     #theme_wrappers hook by setting the hook name as the key and an array
Chris@0:    *     of overrides as the value in #theme_wrappers array.
Chris@0:    *     For example, if we have a render element as follows:
Chris@0:    *     @code
Chris@0:    *     array(
Chris@0:    *       '#theme' => 'image',
Chris@0:    *       '#attributes' => array('class' => array('foo')),
Chris@0:    *       '#theme_wrappers' => array('container'),
Chris@0:    *     );
Chris@0:    *     @endcode
Chris@0:    *     and we need to pass the class 'bar' as an attribute for 'container', we
Chris@0:    *     can rewrite our element thus:
Chris@0:    *     @code
Chris@0:    *     array(
Chris@0:    *       '#theme' => 'image',
Chris@0:    *       '#attributes' => array('class' => array('foo')),
Chris@0:    *       '#theme_wrappers' => array(
Chris@0:    *         'container' => array(
Chris@0:    *           '#attributes' => array('class' => array('bar')),
Chris@0:    *         ),
Chris@0:    *       ),
Chris@0:    *     );
Chris@0:    *      @endcode
Chris@0:    *   - If this element has an array of #post_render functions defined, they
Chris@0:    *     are called sequentially to modify the rendered #children. Unlike
Chris@0:    *     #pre_render functions, #post_render functions are passed both the
Chris@0:    *     rendered #children attribute as a string and the element itself.
Chris@0:    *   - If this element has #prefix and/or #suffix defined, they are
Chris@0:    *     concatenated to #children.
Chris@0:    *   - The rendering of this element is now complete. The next step will be
Chris@0:    *     render caching. So this is the perfect time to update the stack. At
Chris@0:    *     this point, children of this element (if any), have been rendered also,
Chris@0:    *     and if there were any, their bubbleable rendering metadata will have
Chris@0:    *     been bubbled up into the stack frame for the element that is currently
Chris@0:    *     being rendered. The render cache item for this element must contain the
Chris@0:    *     bubbleable rendering metadata for this element and all of its children.
Chris@0:    *     However, right now, the topmost stack frame (the one for this element)
Chris@0:    *     currently only contains the metadata for the children. Therefore, the
Chris@0:    *     topmost stack frame is updated with this element's metadata, and then
Chris@0:    *     the element's metadata is replaced with the metadata in the topmost
Chris@0:    *     stack frame. This element now contains all bubbleable rendering
Chris@0:    *     metadata for this element and all its children, so it's now ready for
Chris@0:    *     render caching.
Chris@0:    *   - If this element has #cache defined, the rendered output of this element
Chris@0:    *     is saved to Renderer::render()'s internal cache. This includes the
Chris@0:    *     changes made by #post_render.
Chris@0:    *     At the same time, if $pre_bubbling_cid is set, it is compared to the
Chris@0:    *     calculated cache ID. If they are different, then a redirecting cache
Chris@0:    *     item is created, containing the #cache metadata of the current element,
Chris@0:    *     and written to cache using the value of $pre_bubbling_cid as the cache
Chris@0:    *     ID. This ensures the pre-bubbling ("wrong") cache ID redirects to the
Chris@0:    *     post-bubbling ("right") cache ID.
Chris@0:    *   - If this element also has #cache_properties defined, all the array items
Chris@0:    *     matching the specified property names will be cached along with the
Chris@0:    *     element markup. If properties include children names, the system
Chris@0:    *     assumes only children's individual markup is relevant and ignores the
Chris@0:    *     parent markup. This approach is normally not needed and should be
Chris@0:    *     adopted only when dealing with very advanced use cases.
Chris@0:    *   - If this element has attached placeholders ([#attached][placeholders]),
Chris@0:    *     or any of its children has (which we would know thanks to the stack
Chris@0:    *     having been updated just before the render caching step), its
Chris@0:    *     placeholder element containing a #lazy_builder function is rendered in
Chris@0:    *     isolation. The resulting markup is used to replace the placeholder, and
Chris@0:    *     any bubbleable metadata is merged.
Chris@0:    *     Placeholders must be unique, to guarantee that for instance, samples of
Chris@0:    *     placeholders are not replaced as well.
Chris@0:    *   - Just before finishing the rendering of this element, this element's
Chris@0:    *     stack frame (the topmost one) is bubbled: the two topmost frames are
Chris@0:    *     popped from the stack, they are merged and the result is pushed back
Chris@0:    *     onto the stack.
Chris@0:    *     So if for instance this element was a child element, then a new frame
Chris@0:    *     was pushed onto the stack element at the beginning of rendering this
Chris@0:    *     element, it was updated when the rendering was completed, and now we
Chris@0:    *     merge it with the frame for the parent, so that the parent now has the
Chris@0:    *     bubbleable rendering metadata for its child.
Chris@0:    *   - #printed is set to TRUE for this element to ensure that it is only
Chris@0:    *     rendered once.
Chris@0:    *   - The final value of #children for this element is returned as the
Chris@0:    *     rendered output.
Chris@0:    *
Chris@0:    * @param array $elements
Chris@0:    *   The structured array describing the data to be rendered.
Chris@0:    * @param bool $is_root_call
Chris@0:    *   (Internal use only.) Whether this is a recursive call or not. See
Chris@0:    *   ::renderRoot().
Chris@0:    *
Chris@0:    * @return \Drupal\Component\Render\MarkupInterface
Chris@0:    *   The rendered HTML.
Chris@0:    *
Chris@0:    * @throws \LogicException
Chris@0:    *   When called outside of a render context (i.e. outside of a renderRoot(),
Chris@0:    *   renderPlain() or executeInRenderContext() call).
Chris@0:    * @throws \Exception
Chris@0:    *   If a #pre_render callback throws an exception, it is caught to mark the
Chris@0:    *   renderer as no longer being in a root render call, if any. Then the
Chris@0:    *   exception is rethrown.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Render\ElementInfoManagerInterface::getInfo()
Chris@0:    * @see \Drupal\Core\Theme\ThemeManagerInterface::render()
Chris@0:    * @see drupal_process_states()
Chris@0:    * @see \Drupal\Core\Render\AttachmentsResponseProcessorInterface::processAttachments()
Chris@0:    * @see \Drupal\Core\Render\RendererInterface::renderRoot()
Chris@0:    */
Chris@0:   public function render(&$elements, $is_root_call = FALSE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Checks whether a render context is active.
Chris@0:    *
Chris@0:    * This is useful only in very specific situations to determine whether the
Chris@0:    * system is already capable of collecting bubbleable metadata. Normally it
Chris@0:    * should not be necessary to be concerned about this.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the renderer has a render context active, FALSE otherwise.
Chris@0:    */
Chris@0:   public function hasRenderContext();
Chris@0: 
Chris@0:   /**
Chris@0:    * Executes a callable within a render context.
Chris@0:    *
Chris@0:    * Only for very advanced use cases. Prefer using ::renderRoot() and
Chris@0:    * ::renderPlain() instead.
Chris@0:    *
Chris@0:    * All rendering must happen within a render context. Within a render context,
Chris@0:    * all bubbleable metadata is bubbled and hence tracked. Outside of a render
Chris@0:    * context, it would be lost. This could lead to missing assets, incorrect
Chris@0:    * cache variations (and thus security issues), insufficient cache
Chris@0:    * invalidations, and so on.
Chris@0:    *
Chris@0:    * Any and all rendering must therefore happen within a render context, and it
Chris@0:    * is this method that provides that.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Render\RenderContext $context
Chris@0:    *   The render context to execute the callable within.
Chris@0:    * @param callable $callable
Chris@0:    *   The callable to execute.
Chris@0:    *
Chris@0:    * @return mixed
Chris@0:    *   The callable's return value.
Chris@0:    *
Chris@0:    * @throws \LogicException
Chris@0:    *   In case bubbling has failed, can only happen in case of broken code.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Render\RenderContext
Chris@0:    * @see \Drupal\Core\Render\BubbleableMetadata
Chris@0:    */
Chris@0:   public function executeInRenderContext(RenderContext $context, callable $callable);
Chris@0: 
Chris@0:   /**
Chris@0:    * Merges the bubbleable rendering metadata o/t 2nd render array with the 1st.
Chris@0:    *
Chris@0:    * @param array $a
Chris@0:    *   A render array.
Chris@0:    * @param array $b
Chris@0:    *   A render array.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The first render array, modified to also contain the bubbleable rendering
Chris@0:    *   metadata of the second render array.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Render\BubbleableMetadata
Chris@0:    */
Chris@0:   public function mergeBubbleableMetadata(array $a, array $b);
Chris@0: 
Chris@0:   /**
Chris@0:    * Adds a dependency on an object: merges its cacheability metadata.
Chris@0:    *
Chris@0:    * For instance, when a render array depends on some configuration, an entity,
Chris@0:    * or an access result, we must make sure their cacheability metadata is
Chris@0:    * present on the render array. This method makes doing that simple.
Chris@0:    *
Chris@0:    * @param array &$elements
Chris@0:    *   The render array to update.
Chris@0:    * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
Chris@0:    *   The dependency. If the object implements CacheableDependencyInterface,
Chris@0:    *   then its cacheability metadata will be used. Otherwise, the passed in
Chris@0:    *   object must be assumed to be uncacheable, so max-age 0 is set.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheableMetadata::createFromObject()
Chris@0:    */
Chris@0:   public function addCacheableDependency(array &$elements, $dependency);
Chris@0: 
Chris@0: }