annotate core/lib/Drupal/Core/Cache/CacheableMetadata.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Cache;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Defines a generic class for passing cacheability metadata.
Chris@0 7 *
Chris@0 8 * @ingroup cache
Chris@0 9 */
Chris@0 10 class CacheableMetadata implements RefinableCacheableDependencyInterface {
Chris@0 11
Chris@0 12 use RefinableCacheableDependencyTrait;
Chris@0 13
Chris@0 14 /**
Chris@0 15 * {@inheritdoc}
Chris@0 16 */
Chris@0 17 public function getCacheTags() {
Chris@0 18 return $this->cacheTags;
Chris@0 19 }
Chris@0 20
Chris@0 21 /**
Chris@0 22 * Sets cache tags.
Chris@0 23 *
Chris@0 24 * @param string[] $cache_tags
Chris@0 25 * The cache tags to be associated.
Chris@0 26 *
Chris@0 27 * @return $this
Chris@0 28 */
Chris@0 29 public function setCacheTags(array $cache_tags) {
Chris@0 30 $this->cacheTags = $cache_tags;
Chris@0 31 return $this;
Chris@0 32 }
Chris@0 33
Chris@0 34 /**
Chris@0 35 * {@inheritdoc}
Chris@0 36 */
Chris@0 37 public function getCacheContexts() {
Chris@0 38 return $this->cacheContexts;
Chris@0 39 }
Chris@0 40
Chris@0 41 /**
Chris@0 42 * Sets cache contexts.
Chris@0 43 *
Chris@0 44 * @param string[] $cache_contexts
Chris@0 45 * The cache contexts to be associated.
Chris@0 46 *
Chris@0 47 * @return $this
Chris@0 48 */
Chris@0 49 public function setCacheContexts(array $cache_contexts) {
Chris@0 50 $this->cacheContexts = $cache_contexts;
Chris@0 51 return $this;
Chris@0 52 }
Chris@0 53
Chris@0 54 /**
Chris@0 55 * {@inheritdoc}
Chris@0 56 */
Chris@0 57 public function getCacheMaxAge() {
Chris@0 58 return $this->cacheMaxAge;
Chris@0 59 }
Chris@0 60
Chris@0 61 /**
Chris@0 62 * Sets the maximum age (in seconds).
Chris@0 63 *
Chris@0 64 * Defaults to Cache::PERMANENT
Chris@0 65 *
Chris@0 66 * @param int $max_age
Chris@0 67 * The max age to associate.
Chris@0 68 *
Chris@0 69 * @return $this
Chris@0 70 *
Chris@0 71 * @throws \InvalidArgumentException
Chris@0 72 * If a non-integer value is supplied.
Chris@0 73 */
Chris@0 74 public function setCacheMaxAge($max_age) {
Chris@0 75 if (!is_int($max_age)) {
Chris@0 76 throw new \InvalidArgumentException('$max_age must be an integer');
Chris@0 77 }
Chris@0 78
Chris@0 79 $this->cacheMaxAge = $max_age;
Chris@0 80 return $this;
Chris@0 81 }
Chris@0 82
Chris@0 83 /**
Chris@0 84 * Merges the values of another CacheableMetadata object with this one.
Chris@0 85 *
Chris@0 86 * @param \Drupal\Core\Cache\CacheableMetadata $other
Chris@0 87 * The other CacheableMetadata object.
Chris@0 88 *
Chris@0 89 * @return static
Chris@0 90 * A new CacheableMetadata object, with the merged data.
Chris@0 91 */
Chris@0 92 public function merge(CacheableMetadata $other) {
Chris@0 93 $result = clone $this;
Chris@0 94
Chris@0 95 // This is called many times per request, so avoid merging unless absolutely
Chris@0 96 // necessary.
Chris@0 97 if (empty($this->cacheContexts)) {
Chris@0 98 $result->cacheContexts = $other->cacheContexts;
Chris@0 99 }
Chris@0 100 elseif (empty($other->cacheContexts)) {
Chris@0 101 $result->cacheContexts = $this->cacheContexts;
Chris@0 102 }
Chris@0 103 else {
Chris@0 104 $result->cacheContexts = Cache::mergeContexts($this->cacheContexts, $other->cacheContexts);
Chris@0 105 }
Chris@0 106
Chris@0 107 if (empty($this->cacheTags)) {
Chris@0 108 $result->cacheTags = $other->cacheTags;
Chris@0 109 }
Chris@0 110 elseif (empty($other->cacheTags)) {
Chris@0 111 $result->cacheTags = $this->cacheTags;
Chris@0 112 }
Chris@0 113 else {
Chris@0 114 $result->cacheTags = Cache::mergeTags($this->cacheTags, $other->cacheTags);
Chris@0 115 }
Chris@0 116
Chris@0 117 if ($this->cacheMaxAge === Cache::PERMANENT) {
Chris@0 118 $result->cacheMaxAge = $other->cacheMaxAge;
Chris@0 119 }
Chris@0 120 elseif ($other->cacheMaxAge === Cache::PERMANENT) {
Chris@0 121 $result->cacheMaxAge = $this->cacheMaxAge;
Chris@0 122 }
Chris@0 123 else {
Chris@0 124 $result->cacheMaxAge = Cache::mergeMaxAges($this->cacheMaxAge, $other->cacheMaxAge);
Chris@0 125 }
Chris@0 126 return $result;
Chris@0 127 }
Chris@0 128
Chris@0 129 /**
Chris@0 130 * Applies the values of this CacheableMetadata object to a render array.
Chris@0 131 *
Chris@0 132 * @param array &$build
Chris@0 133 * A render array.
Chris@0 134 */
Chris@0 135 public function applyTo(array &$build) {
Chris@0 136 $build['#cache']['contexts'] = $this->cacheContexts;
Chris@0 137 $build['#cache']['tags'] = $this->cacheTags;
Chris@0 138 $build['#cache']['max-age'] = $this->cacheMaxAge;
Chris@0 139 }
Chris@0 140
Chris@0 141 /**
Chris@0 142 * Creates a CacheableMetadata object with values taken from a render array.
Chris@0 143 *
Chris@0 144 * @param array $build
Chris@0 145 * A render array.
Chris@0 146 *
Chris@0 147 * @return static
Chris@0 148 */
Chris@0 149 public static function createFromRenderArray(array $build) {
Chris@0 150 $meta = new static();
Chris@0 151 $meta->cacheContexts = (isset($build['#cache']['contexts'])) ? $build['#cache']['contexts'] : [];
Chris@0 152 $meta->cacheTags = (isset($build['#cache']['tags'])) ? $build['#cache']['tags'] : [];
Chris@0 153 $meta->cacheMaxAge = (isset($build['#cache']['max-age'])) ? $build['#cache']['max-age'] : Cache::PERMANENT;
Chris@0 154 return $meta;
Chris@0 155 }
Chris@0 156
Chris@0 157 /**
Chris@0 158 * Creates a CacheableMetadata object from a depended object.
Chris@0 159 *
Chris@0 160 * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $object
Chris@0 161 * The object whose cacheability metadata to retrieve. If it implements
Chris@0 162 * CacheableDependencyInterface, its cacheability metadata will be used,
Chris@0 163 * otherwise, the passed in object must be assumed to be uncacheable, so
Chris@0 164 * max-age 0 is set.
Chris@0 165 *
Chris@0 166 * @return static
Chris@0 167 */
Chris@0 168 public static function createFromObject($object) {
Chris@0 169 if ($object instanceof CacheableDependencyInterface) {
Chris@0 170 $meta = new static();
Chris@0 171 $meta->cacheContexts = $object->getCacheContexts();
Chris@0 172 $meta->cacheTags = $object->getCacheTags();
Chris@0 173 $meta->cacheMaxAge = $object->getCacheMaxAge();
Chris@0 174 return $meta;
Chris@0 175 }
Chris@0 176
Chris@0 177 // Objects that don't implement CacheableDependencyInterface must be assumed
Chris@0 178 // to be uncacheable, so set max-age 0.
Chris@0 179 $meta = new static();
Chris@0 180 $meta->cacheMaxAge = 0;
Chris@0 181 return $meta;
Chris@0 182 }
Chris@0 183
Chris@0 184 }