Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Render;
Chris@0: 
Chris@0: use Drupal\Component\Utility\NestedArray;
Chris@0: use Drupal\Core\Cache\CacheableMetadata;
Chris@0: 
Chris@0: /**
Chris@0:  * Value object used for bubbleable rendering metadata.
Chris@0:  *
Chris@0:  * @see \Drupal\Core\Render\RendererInterface::render()
Chris@0:  */
Chris@0: class BubbleableMetadata extends CacheableMetadata implements AttachmentsInterface {
Chris@0: 
Chris@0:   use AttachmentsTrait;
Chris@0: 
Chris@0:   /**
Chris@0:    * Merges the values of another bubbleable metadata object with this one.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Cache\CacheableMetadata $other
Chris@0:    *   The other bubbleable metadata object.
Chris@0:    *
Chris@0:    * @return static
Chris@0:    *   A new bubbleable metadata object, with the merged data.
Chris@0:    */
Chris@0:   public function merge(CacheableMetadata $other) {
Chris@0:     $result = parent::merge($other);
Chris@0: 
Chris@0:     // This is called many times per request, so avoid merging unless absolutely
Chris@0:     // necessary.
Chris@0:     if ($other instanceof BubbleableMetadata) {
Chris@0:       if (empty($this->attachments)) {
Chris@0:         $result->attachments = $other->attachments;
Chris@0:       }
Chris@0:       elseif (empty($other->attachments)) {
Chris@0:         $result->attachments = $this->attachments;
Chris@0:       }
Chris@0:       else {
Chris@0:         $result->attachments = static::mergeAttachments($this->attachments, $other->attachments);
Chris@0:       }
Chris@0:     }
Chris@0: 
Chris@0:     return $result;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Applies the values of this bubbleable metadata object to a render array.
Chris@0:    *
Chris@0:    * @param array &$build
Chris@0:    *   A render array.
Chris@0:    */
Chris@0:   public function applyTo(array &$build) {
Chris@0:     parent::applyTo($build);
Chris@0:     $build['#attached'] = $this->attachments;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Creates a bubbleable metadata object with values taken from a render array.
Chris@0:    *
Chris@0:    * @param array $build
Chris@0:    *   A render array.
Chris@0:    *
Chris@0:    * @return static
Chris@0:    */
Chris@0:   public static function createFromRenderArray(array $build) {
Chris@0:     $meta = parent::createFromRenderArray($build);
Chris@0:     $meta->attachments = (isset($build['#attached'])) ? $build['#attached'] : [];
Chris@0:     return $meta;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Creates a bubbleable metadata object from a depended object.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $object
Chris@0:    *   The object whose cacheability metadata to retrieve. If it implements
Chris@0:    *   CacheableDependencyInterface, its cacheability metadata will be used,
Chris@0:    *   otherwise, the passed in object must be assumed to be uncacheable, so
Chris@0:    *   max-age 0 is set.
Chris@0:    *
Chris@0:    * @return static
Chris@0:    */
Chris@0:   public static function createFromObject($object) {
Chris@0:     $meta = parent::createFromObject($object);
Chris@0: 
Chris@0:     if ($object instanceof AttachmentsInterface) {
Chris@0:       $meta->attachments = $object->getAttachments();
Chris@0:     }
Chris@0: 
Chris@0:     return $meta;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * {@inheritdoc}
Chris@0:    */
Chris@0:   public function addCacheableDependency($other_object) {
Chris@0:     parent::addCacheableDependency($other_object);
Chris@0: 
Chris@0:     if ($other_object instanceof AttachmentsInterface) {
Chris@0:       $this->addAttachments($other_object->getAttachments());
Chris@0:     }
Chris@0: 
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Merges two attachments arrays (which live under the '#attached' key).
Chris@0:    *
Chris@0:    * The values under the 'drupalSettings' key are merged in a special way, to
Chris@0:    * match the behavior of:
Chris@0:    *
Chris@0:    * @code
Chris@0:    *   jQuery.extend(true, {}, $settings_items[0], $settings_items[1], ...)
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * This means integer indices are preserved just like string indices are,
Chris@0:    * rather than re-indexed as is common in PHP array merging.
Chris@0:    *
Chris@0:    * Example:
Chris@0:    * @code
Chris@0:    * function module1_page_attachments(&$page) {
Chris@0:    *   $page['a']['#attached']['drupalSettings']['foo'] = ['a', 'b', 'c'];
Chris@0:    * }
Chris@0:    * function module2_page_attachments(&$page) {
Chris@0:    *   $page['#attached']['drupalSettings']['foo'] = ['d'];
Chris@0:    * }
Chris@0:    * // When the page is rendered after the above code, and the browser runs the
Chris@0:    * // resulting <SCRIPT> tags, the value of drupalSettings.foo is
Chris@0:    * // ['d', 'b', 'c'], not ['a', 'b', 'c', 'd'].
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * By following jQuery.extend() merge logic rather than common PHP array merge
Chris@0:    * logic, the following are ensured:
Chris@0:    * - Attaching JavaScript settings is idempotent: attaching the same settings
Chris@0:    *   twice does not change the output sent to the browser.
Chris@0:    * - If pieces of the page are rendered in separate PHP requests and the
Chris@0:    *   returned settings are merged by JavaScript, the resulting settings are
Chris@0:    *   the same as if rendered in one PHP request and merged by PHP.
Chris@0:    *
Chris@0:    * @param array $a
Chris@0:    *   An attachments array.
Chris@0:    * @param array $b
Chris@0:    *   Another attachments array.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The merged attachments array.
Chris@0:    */
Chris@0:   public static function mergeAttachments(array $a, array $b) {
Chris@0:     // If both #attached arrays contain drupalSettings, then merge them
Chris@0:     // correctly; adding the same settings multiple times needs to behave
Chris@0:     // idempotently.
Chris@0:     if (!empty($a['drupalSettings']) && !empty($b['drupalSettings'])) {
Chris@0:       $drupalSettings = NestedArray::mergeDeepArray([$a['drupalSettings'], $b['drupalSettings']], TRUE);
Chris@0:       // No need for re-merging them.
Chris@0:       unset($a['drupalSettings']);
Chris@0:       unset($b['drupalSettings']);
Chris@0:     }
Chris@0:     // Optimize merging of placeholders: no need for deep merging.
Chris@0:     if (!empty($a['placeholders']) && !empty($b['placeholders'])) {
Chris@0:       $placeholders = $a['placeholders'] + $b['placeholders'];
Chris@0:       // No need for re-merging them.
Chris@0:       unset($a['placeholders']);
Chris@0:       unset($b['placeholders']);
Chris@0:     }
Chris@0:     // Apply the normal merge.
Chris@0:     $a = array_merge_recursive($a, $b);
Chris@0:     if (isset($drupalSettings)) {
Chris@0:       // Save the custom merge for the drupalSettings.
Chris@0:       $a['drupalSettings'] = $drupalSettings;
Chris@0:     }
Chris@0:     if (isset($placeholders)) {
Chris@0:       // Save the custom merge for the placeholders.
Chris@0:       $a['placeholders'] = $placeholders;
Chris@0:     }
Chris@0:     return $a;
Chris@0:   }
Chris@0: 
Chris@0: }