Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Cache;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines a generic class for passing cacheability metadata.
Chris@0:  *
Chris@0:  * @ingroup cache
Chris@0:  */
Chris@0: class CacheableMetadata implements RefinableCacheableDependencyInterface {
Chris@0: 
Chris@0:   use RefinableCacheableDependencyTrait;
Chris@0: 
Chris@0:   /**
Chris@0:    * {@inheritdoc}
Chris@0:    */
Chris@0:   public function getCacheTags() {
Chris@0:     return $this->cacheTags;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets cache tags.
Chris@0:    *
Chris@0:    * @param string[] $cache_tags
Chris@0:    *   The cache tags to be associated.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setCacheTags(array $cache_tags) {
Chris@0:     $this->cacheTags = $cache_tags;
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * {@inheritdoc}
Chris@0:    */
Chris@0:   public function getCacheContexts() {
Chris@0:     return $this->cacheContexts;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets cache contexts.
Chris@0:    *
Chris@0:    * @param string[] $cache_contexts
Chris@0:    *   The cache contexts to be associated.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setCacheContexts(array $cache_contexts) {
Chris@0:     $this->cacheContexts = $cache_contexts;
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * {@inheritdoc}
Chris@0:    */
Chris@0:   public function getCacheMaxAge() {
Chris@0:     return $this->cacheMaxAge;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the maximum age (in seconds).
Chris@0:    *
Chris@0:    * Defaults to Cache::PERMANENT
Chris@0:    *
Chris@0:    * @param int $max_age
Chris@0:    *   The max age to associate.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException
Chris@0:    *   If a non-integer value is supplied.
Chris@0:    */
Chris@0:   public function setCacheMaxAge($max_age) {
Chris@0:     if (!is_int($max_age)) {
Chris@0:       throw new \InvalidArgumentException('$max_age must be an integer');
Chris@0:     }
Chris@0: 
Chris@0:     $this->cacheMaxAge = $max_age;
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Merges the values of another CacheableMetadata object with this one.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Cache\CacheableMetadata $other
Chris@0:    *   The other CacheableMetadata object.
Chris@0:    *
Chris@0:    * @return static
Chris@0:    *   A new CacheableMetadata object, with the merged data.
Chris@0:    */
Chris@0:   public function merge(CacheableMetadata $other) {
Chris@0:     $result = clone $this;
Chris@0: 
Chris@0:     // This is called many times per request, so avoid merging unless absolutely
Chris@0:     // necessary.
Chris@0:     if (empty($this->cacheContexts)) {
Chris@0:       $result->cacheContexts = $other->cacheContexts;
Chris@0:     }
Chris@0:     elseif (empty($other->cacheContexts)) {
Chris@0:       $result->cacheContexts = $this->cacheContexts;
Chris@0:     }
Chris@0:     else {
Chris@0:       $result->cacheContexts = Cache::mergeContexts($this->cacheContexts, $other->cacheContexts);
Chris@0:     }
Chris@0: 
Chris@0:     if (empty($this->cacheTags)) {
Chris@0:       $result->cacheTags = $other->cacheTags;
Chris@0:     }
Chris@0:     elseif (empty($other->cacheTags)) {
Chris@0:       $result->cacheTags = $this->cacheTags;
Chris@0:     }
Chris@0:     else {
Chris@0:       $result->cacheTags = Cache::mergeTags($this->cacheTags, $other->cacheTags);
Chris@0:     }
Chris@0: 
Chris@0:     if ($this->cacheMaxAge === Cache::PERMANENT) {
Chris@0:       $result->cacheMaxAge = $other->cacheMaxAge;
Chris@0:     }
Chris@0:     elseif ($other->cacheMaxAge === Cache::PERMANENT) {
Chris@0:       $result->cacheMaxAge = $this->cacheMaxAge;
Chris@0:     }
Chris@0:     else {
Chris@0:       $result->cacheMaxAge = Cache::mergeMaxAges($this->cacheMaxAge, $other->cacheMaxAge);
Chris@0:     }
Chris@0:     return $result;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Applies the values of this CacheableMetadata 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:     $build['#cache']['contexts'] = $this->cacheContexts;
Chris@0:     $build['#cache']['tags'] = $this->cacheTags;
Chris@0:     $build['#cache']['max-age'] = $this->cacheMaxAge;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Creates a CacheableMetadata 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 = new static();
Chris@0:     $meta->cacheContexts = (isset($build['#cache']['contexts'])) ? $build['#cache']['contexts'] : [];
Chris@0:     $meta->cacheTags = (isset($build['#cache']['tags'])) ? $build['#cache']['tags'] : [];
Chris@0:     $meta->cacheMaxAge = (isset($build['#cache']['max-age'])) ? $build['#cache']['max-age'] : Cache::PERMANENT;
Chris@0:     return $meta;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Creates a CacheableMetadata 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:     if ($object instanceof CacheableDependencyInterface) {
Chris@0:       $meta = new static();
Chris@0:       $meta->cacheContexts = $object->getCacheContexts();
Chris@0:       $meta->cacheTags = $object->getCacheTags();
Chris@0:       $meta->cacheMaxAge = $object->getCacheMaxAge();
Chris@0:       return $meta;
Chris@0:     }
Chris@0: 
Chris@0:     // Objects that don't implement CacheableDependencyInterface must be assumed
Chris@0:     // to be uncacheable, so set max-age 0.
Chris@0:     $meta = new static();
Chris@0:     $meta->cacheMaxAge = 0;
Chris@0:     return $meta;
Chris@0:   }
Chris@0: 
Chris@0: }