3 namespace Drupal\Core\Cache;
6 * Defines a generic class for passing cacheability metadata.
10 class CacheableMetadata implements RefinableCacheableDependencyInterface {
12 use RefinableCacheableDependencyTrait;
17 public function getCacheTags() {
18 return $this->cacheTags;
24 * @param string[] $cache_tags
25 * The cache tags to be associated.
29 public function setCacheTags(array $cache_tags) {
30 $this->cacheTags = $cache_tags;
37 public function getCacheContexts() {
38 return $this->cacheContexts;
42 * Sets cache contexts.
44 * @param string[] $cache_contexts
45 * The cache contexts to be associated.
49 public function setCacheContexts(array $cache_contexts) {
50 $this->cacheContexts = $cache_contexts;
57 public function getCacheMaxAge() {
58 return $this->cacheMaxAge;
62 * Sets the maximum age (in seconds).
64 * Defaults to Cache::PERMANENT
67 * The max age to associate.
71 * @throws \InvalidArgumentException
72 * If a non-integer value is supplied.
74 public function setCacheMaxAge($max_age) {
75 if (!is_int($max_age)) {
76 throw new \InvalidArgumentException('$max_age must be an integer');
79 $this->cacheMaxAge = $max_age;
84 * Merges the values of another CacheableMetadata object with this one.
86 * @param \Drupal\Core\Cache\CacheableMetadata $other
87 * The other CacheableMetadata object.
90 * A new CacheableMetadata object, with the merged data.
92 public function merge(CacheableMetadata $other) {
93 $result = clone $this;
95 // This is called many times per request, so avoid merging unless absolutely
97 if (empty($this->cacheContexts)) {
98 $result->cacheContexts = $other->cacheContexts;
100 elseif (empty($other->cacheContexts)) {
101 $result->cacheContexts = $this->cacheContexts;
104 $result->cacheContexts = Cache::mergeContexts($this->cacheContexts, $other->cacheContexts);
107 if (empty($this->cacheTags)) {
108 $result->cacheTags = $other->cacheTags;
110 elseif (empty($other->cacheTags)) {
111 $result->cacheTags = $this->cacheTags;
114 $result->cacheTags = Cache::mergeTags($this->cacheTags, $other->cacheTags);
117 if ($this->cacheMaxAge === Cache::PERMANENT) {
118 $result->cacheMaxAge = $other->cacheMaxAge;
120 elseif ($other->cacheMaxAge === Cache::PERMANENT) {
121 $result->cacheMaxAge = $this->cacheMaxAge;
124 $result->cacheMaxAge = Cache::mergeMaxAges($this->cacheMaxAge, $other->cacheMaxAge);
130 * Applies the values of this CacheableMetadata object to a render array.
132 * @param array &$build
135 public function applyTo(array &$build) {
136 $build['#cache']['contexts'] = $this->cacheContexts;
137 $build['#cache']['tags'] = $this->cacheTags;
138 $build['#cache']['max-age'] = $this->cacheMaxAge;
142 * Creates a CacheableMetadata object with values taken from a render array.
144 * @param array $build
149 public static function createFromRenderArray(array $build) {
150 $meta = new static();
151 $meta->cacheContexts = (isset($build['#cache']['contexts'])) ? $build['#cache']['contexts'] : [];
152 $meta->cacheTags = (isset($build['#cache']['tags'])) ? $build['#cache']['tags'] : [];
153 $meta->cacheMaxAge = (isset($build['#cache']['max-age'])) ? $build['#cache']['max-age'] : Cache::PERMANENT;
158 * Creates a CacheableMetadata object from a depended object.
160 * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $object
161 * The object whose cacheability metadata to retrieve. If it implements
162 * CacheableDependencyInterface, its cacheability metadata will be used,
163 * otherwise, the passed in object must be assumed to be uncacheable, so
168 public static function createFromObject($object) {
169 if ($object instanceof CacheableDependencyInterface) {
170 $meta = new static();
171 $meta->cacheContexts = $object->getCacheContexts();
172 $meta->cacheTags = $object->getCacheTags();
173 $meta->cacheMaxAge = $object->getCacheMaxAge();
177 // Objects that don't implement CacheableDependencyInterface must be assumed
178 // to be uncacheable, so set max-age 0.
179 $meta = new static();
180 $meta->cacheMaxAge = 0;