class CacheableMetadata in Drupal 8

Defines a generic class for passing cacheability metadata.

Hierarchy

• class \Drupal\Core\Cache\CacheableMetadata implements RefinableCacheableDependencyInterface uses RefinableCacheableDependencyTrait

Related topics

Cache API

Information about the Drupal Cache API

144 files declare their use of CacheableMetadata

AccountPermissionsCacheContext.php in core/lib/Drupal/Core/Cache/Context/AccountPermissionsCacheContext.php

AnonymousUserResponseSubscriber.php in core/lib/Drupal/Core/EventSubscriber/AnonymousUserResponseSubscriber.php

BasicAuth.php in core/modules/basic_auth/src/Authentication/Provider/BasicAuth.php

BigPipeController.php in core/modules/big_pipe/src/Controller/BigPipeController.php

BlockComponentRenderArray.php in core/modules/layout_builder/src/EventSubscriber/BlockComponentRenderArray.php

... See full list

File

core/lib/Drupal/Core/Cache/CacheableMetadata.php, line 10

Namespace

Drupal\Core\Cache

class CacheableMetadata implements RefinableCacheableDependencyInterface {
  use RefinableCacheableDependencyTrait;

  /**
   * {@inheritdoc}
   */
  public function getCacheTags() {
    return $this->cacheTags;
  }

  /**
   * Sets cache tags.
   *
   * @param string[] $cache_tags
   *   The cache tags to be associated.
   *
   * @return $this
   */
  public function setCacheTags(array $cache_tags) {
    $this->cacheTags = $cache_tags;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheContexts() {
    return $this->cacheContexts;
  }

  /**
   * Sets cache contexts.
   *
   * @param string[] $cache_contexts
   *   The cache contexts to be associated.
   *
   * @return $this
   */
  public function setCacheContexts(array $cache_contexts) {
    $this->cacheContexts = $cache_contexts;
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheMaxAge() {
    return $this->cacheMaxAge;
  }

  /**
   * Sets the maximum age (in seconds).
   *
   * Defaults to Cache::PERMANENT
   *
   * @param int $max_age
   *   The max age to associate.
   *
   * @return $this
   *
   * @throws \InvalidArgumentException
   *   If a non-integer value is supplied.
   */
  public function setCacheMaxAge($max_age) {
    if (!is_int($max_age)) {
      throw new \InvalidArgumentException('$max_age must be an integer');
    }
    $this->cacheMaxAge = $max_age;
    return $this;
  }

  /**
   * Merges the values of another CacheableMetadata object with this one.
   *
   * @param \Drupal\Core\Cache\CacheableMetadata $other
   *   The other CacheableMetadata object.
   *
   * @return static
   *   A new CacheableMetadata object, with the merged data.
   */
  public function merge(CacheableMetadata $other) {
    $result = clone $this;

    // This is called many times per request, so avoid merging unless absolutely
    // necessary.
    if (empty($this->cacheContexts)) {
      $result->cacheContexts = $other->cacheContexts;
    }
    elseif (empty($other->cacheContexts)) {
      $result->cacheContexts = $this->cacheContexts;
    }
    else {
      $result->cacheContexts = Cache::mergeContexts($this->cacheContexts, $other->cacheContexts);
    }
    if (empty($this->cacheTags)) {
      $result->cacheTags = $other->cacheTags;
    }
    elseif (empty($other->cacheTags)) {
      $result->cacheTags = $this->cacheTags;
    }
    else {
      $result->cacheTags = Cache::mergeTags($this->cacheTags, $other->cacheTags);
    }
    if ($this->cacheMaxAge === Cache::PERMANENT) {
      $result->cacheMaxAge = $other->cacheMaxAge;
    }
    elseif ($other->cacheMaxAge === Cache::PERMANENT) {
      $result->cacheMaxAge = $this->cacheMaxAge;
    }
    else {
      $result->cacheMaxAge = Cache::mergeMaxAges($this->cacheMaxAge, $other->cacheMaxAge);
    }
    return $result;
  }

  /**
   * Applies the values of this CacheableMetadata object to a render array.
   *
   * @param array &$build
   *   A render array.
   */
  public function applyTo(array &$build) {
    $build['#cache']['contexts'] = $this->cacheContexts;
    $build['#cache']['tags'] = $this->cacheTags;
    $build['#cache']['max-age'] = $this->cacheMaxAge;
  }

  /**
   * Creates a CacheableMetadata object with values taken from a render array.
   *
   * @param array $build
   *   A render array.
   *
   * @return static
   */
  public static function createFromRenderArray(array $build) {
    $meta = new static();
    $meta->cacheContexts = isset($build['#cache']['contexts']) ? $build['#cache']['contexts'] : [];
    $meta->cacheTags = isset($build['#cache']['tags']) ? $build['#cache']['tags'] : [];
    $meta->cacheMaxAge = isset($build['#cache']['max-age']) ? $build['#cache']['max-age'] : Cache::PERMANENT;
    return $meta;
  }

  /**
   * Creates a CacheableMetadata object from a depended object.
   *
   * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $object
   *   The object whose cacheability metadata to retrieve. If it implements
   *   CacheableDependencyInterface, its cacheability metadata will be used,
   *   otherwise, the passed in object must be assumed to be uncacheable, so
   *   max-age 0 is set.
   *
   * @return static
   */
  public static function createFromObject($object) {
    if ($object instanceof CacheableDependencyInterface) {
      $meta = new static();
      $meta->cacheContexts = $object
        ->getCacheContexts();
      $meta->cacheTags = $object
        ->getCacheTags();
      $meta->cacheMaxAge = $object
        ->getCacheMaxAge();
      return $meta;
    }

    // Objects that don't implement CacheableDependencyInterface must be assumed
    // to be uncacheable, so set max-age 0.
    $meta = new static();
    $meta->cacheMaxAge = 0;
    return $meta;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
CacheableDependencyTrait::$cacheContexts	protected	property	Cache contexts.
CacheableDependencyTrait::$cacheMaxAge	protected	property	Cache max-age.
CacheableDependencyTrait::$cacheTags	protected	property	Cache tags.
CacheableDependencyTrait::setCacheability	protected	function	Sets cacheability; useful for value object constructors.
CacheableMetadata::applyTo	public	function	Applies the values of this CacheableMetadata object to a render array.	1
CacheableMetadata::createFromObject	public static	function	Creates a CacheableMetadata object from a depended object.	1
CacheableMetadata::createFromRenderArray	public static	function	Creates a CacheableMetadata object with values taken from a render array.	1
CacheableMetadata::getCacheContexts	public	function	The cache contexts associated with this object. Overrides CacheableDependencyTrait::getCacheContexts
CacheableMetadata::getCacheMaxAge	public	function	The maximum age for which this object may be cached. Overrides CacheableDependencyTrait::getCacheMaxAge
CacheableMetadata::getCacheTags	public	function	The cache tags associated with this object. Overrides CacheableDependencyTrait::getCacheTags
CacheableMetadata::merge	public	function	Merges the values of another CacheableMetadata object with this one.	1
CacheableMetadata::setCacheContexts	public	function	Sets cache contexts.
CacheableMetadata::setCacheMaxAge	public	function	Sets the maximum age (in seconds).
CacheableMetadata::setCacheTags	public	function	Sets cache tags.
RefinableCacheableDependencyTrait::addCacheableDependency	public	function		1
RefinableCacheableDependencyTrait::addCacheContexts	public	function
RefinableCacheableDependencyTrait::addCacheTags	public	function
RefinableCacheableDependencyTrait::mergeCacheMaxAge	public	function