class CacheableMetadata

Same name in other branches
  1. 8.9.x core/lib/Drupal/Core/Cache/CacheableMetadata.php \Drupal\Core\Cache\CacheableMetadata
  2. 10 core/lib/Drupal/Core/Cache/CacheableMetadata.php \Drupal\Core\Cache\CacheableMetadata
  3. 11.x core/lib/Drupal/Core/Cache/CacheableMetadata.php \Drupal\Core\Cache\CacheableMetadata

Defines a generic class for passing cacheability metadata.

Hierarchy

Expanded class hierarchy of CacheableMetadata

Related topics

155 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
View source
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

Title Sort descending Modifiers Object type Summary Overriden Title 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

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.