abstract class CacheCollector in Drupal 9
Same name and namespace in other branches
- 8 core/lib/Drupal/Core/Cache/CacheCollector.php \Drupal\Core\Cache\CacheCollector
Default implementation for CacheCollectorInterface.
By default, the class accounts for caches where calling functions might request keys that won't exist even after a cache rebuild. This prevents situations where a cache rebuild would be triggered over and over due to a 'missing' item. These cases are stored internally as a value of NULL. This means that the CacheCollector::get() method must be overridden if caching data where the values can legitimately be NULL, and where CacheCollector->has() needs to correctly return (equivalent to array_key_exists() vs. isset()). This should not be necessary in the majority of cases.
Hierarchy
- class \Drupal\Core\Cache\CacheCollector implements CacheCollectorInterface, DestructableInterface
Expanded class hierarchy of CacheCollector
Related topics
7 files declare their use of CacheCollector
- AliasWhitelist.php in core/
modules/ path_alias/ src/ AliasWhitelist.php - BlockContentUuidLookup.php in core/
modules/ block_content/ src/ BlockContentUuidLookup.php - CacheCollectorHelper.php in core/
tests/ Drupal/ Tests/ Core/ Cache/ CacheCollectorHelper.php - LibraryDiscoveryCollector.php in core/
lib/ Drupal/ Core/ Asset/ LibraryDiscoveryCollector.php - LocaleLookup.php in core/
modules/ locale/ src/ LocaleLookup.php
File
- core/
lib/ Drupal/ Core/ Cache/ CacheCollector.php, line 25
Namespace
Drupal\Core\CacheView source
abstract class CacheCollector implements CacheCollectorInterface, DestructableInterface {
/**
* The cache id that is used for the cache entry.
*
* @var string
*/
protected $cid;
/**
* A list of tags that are used for the cache entry.
*
* @var array
*/
protected $tags;
/**
* The cache backend that should be used.
*
* @var \Drupal\Core\Cache\CacheBackendInterface
*/
protected $cache;
/**
* The lock backend that should be used.
*
* @var \Drupal\Core\Lock\LockBackendInterface
*/
protected $lock;
/**
* An array of keys to add to the cache on service termination.
*
* @var array
*/
protected $keysToPersist = [];
/**
* An array of keys to remove from the cache on service termination.
*
* @var array
*/
protected $keysToRemove = [];
/**
* Storage for the data itself.
*
* @var array
*/
protected $storage = [];
/**
* Stores the cache creation time.
*
* This is used to check if an invalidated cache item has been overwritten in
* the meantime.
*
* @var int
*/
protected $cacheCreated;
/**
* Flag that indicates of the cache has been invalidated.
*
* @var bool
*/
protected $cacheInvalidated = FALSE;
/**
* Indicates if the collected cache was already loaded.
*
* The collected cache is lazy loaded when an entry is set, get or deleted.
*
* @var bool
*/
protected $cacheLoaded = FALSE;
/**
* Constructs a CacheCollector object.
*
* @param string $cid
* The cid for the array being cached.
* @param \Drupal\Core\Cache\CacheBackendInterface $cache
* The cache backend.
* @param \Drupal\Core\Lock\LockBackendInterface $lock
* The lock backend.
* @param array $tags
* (optional) The tags to specify for the cache item.
*/
public function __construct($cid, CacheBackendInterface $cache, LockBackendInterface $lock, array $tags = []) {
assert(Inspector::assertAllStrings($tags), 'Cache tags must be strings.');
$this->cid = $cid;
$this->cache = $cache;
$this->tags = $tags;
$this->lock = $lock;
}
/**
* Gets the cache ID.
*
* @return string
*/
protected function getCid() {
return $this->cid;
}
/**
* {@inheritdoc}
*/
public function has($key) {
// Make sure the value is loaded.
$this
->get($key);
return isset($this->storage[$key]) || array_key_exists($key, $this->storage);
}
/**
* {@inheritdoc}
*/
public function get($key) {
$this
->lazyLoadCache();
if (isset($this->storage[$key]) || array_key_exists($key, $this->storage)) {
return $this->storage[$key];
}
else {
return $this
->resolveCacheMiss($key);
}
}
/**
* Implements \Drupal\Core\Cache\CacheCollectorInterface::set().
*
* This is not persisted by default. In practice this means that setting a
* value will only apply while the object is in scope and will not be written
* back to the persistent cache. This follows a similar pattern to static vs.
* persistent caching in procedural code. Extending classes may wish to alter
* this behavior, for example by adding a call to persist().
*/
public function set($key, $value) {
$this
->lazyLoadCache();
$this->storage[$key] = $value;
// The key might have been marked for deletion.
unset($this->keysToRemove[$key]);
$this
->invalidateCache();
}
/**
* {@inheritdoc}
*/
public function delete($key) {
$this
->lazyLoadCache();
unset($this->storage[$key]);
$this->keysToRemove[$key] = $key;
// The key might have been marked for persisting.
unset($this->keysToPersist[$key]);
$this
->invalidateCache();
}
/**
* Flags an offset value to be written to the persistent cache.
*
* @param string $key
* The key that was requested.
* @param bool $persist
* (optional) Whether the offset should be persisted or not, defaults to
* TRUE. When called with $persist = FALSE the offset will be unflagged so
* that it will not be written at the end of the request.
*/
protected function persist($key, $persist = TRUE) {
$this->keysToPersist[$key] = $persist;
}
/**
* Resolves a cache miss.
*
* When an offset is not found in the object, this is treated as a cache
* miss. This method allows classes using this implementation to look up the
* actual value and allow it to be cached.
*
* @param string $key
* The offset that was requested.
*
* @return mixed
* The value of the offset, or NULL if no value was found.
*/
protected abstract function resolveCacheMiss($key);
/**
* Writes a value to the persistent cache immediately.
*
* @param bool $lock
* (optional) Whether to acquire a lock before writing to cache. Defaults to
* TRUE.
*/
protected function updateCache($lock = TRUE) {
$data = [];
foreach ($this->keysToPersist as $offset => $persist) {
if ($persist) {
$data[$offset] = $this->storage[$offset];
}
}
if (empty($data) && empty($this->keysToRemove)) {
return;
}
// Lock cache writes to help avoid stampedes.
$cid = $this
->getCid();
$lock_name = $this
->normalizeLockName($cid . ':' . __CLASS__);
if (!$lock || $this->lock
->acquire($lock_name)) {
// Set and delete operations invalidate the cache item. Try to also load
// an eventually invalidated cache entry, only update an invalidated cache
// entry if the creation date did not change as this could result in an
// inconsistent cache.
if ($cache = $this->cache
->get($cid, $this->cacheInvalidated)) {
if ($this->cacheInvalidated && $cache->created != $this->cacheCreated) {
// We have invalidated the cache in this request and got a different
// cache entry. Do not attempt to overwrite data that might have been
// changed in a different request. We'll let the cache rebuild in
// later requests.
$this->cache
->delete($cid);
$this->lock
->release($lock_name);
return;
}
$data = array_merge($cache->data, $data);
}
elseif ($this->cacheCreated) {
// Getting here indicates that there was a cache entry at the
// beginning of the request, but now it's gone (some other process
// must have cleared it). We back out to prevent corrupting the cache
// with incomplete data, since we won't be able to properly merge
// the existing cache data from earlier with the new data.
// A future request will properly hydrate the cache from scratch.
if ($lock) {
$this->lock
->release($lock_name);
}
return;
}
// Remove keys marked for deletion.
foreach ($this->keysToRemove as $delete_key) {
unset($data[$delete_key]);
}
$this->cache
->set($cid, $data, Cache::PERMANENT, $this->tags);
if ($lock) {
$this->lock
->release($lock_name);
}
}
$this->keysToPersist = [];
$this->keysToRemove = [];
}
/**
* Normalizes a cache ID in order to comply with database limitations.
*
* @param string $cid
* The passed in cache ID.
*
* @return string
* An ASCII-encoded cache ID that is at most 255 characters long.
*/
protected function normalizeLockName($cid) {
// Nothing to do if the ID is a US ASCII string of 255 characters or less.
$cid_is_ascii = mb_check_encoding($cid, 'ASCII');
if (strlen($cid) <= 255 && $cid_is_ascii) {
return $cid;
}
// Return a string that uses as much as possible of the original cache ID
// with the hash appended.
$hash = Crypt::hashBase64($cid);
if (!$cid_is_ascii) {
return $hash;
}
return substr($cid, 0, 255 - strlen($hash)) . $hash;
}
/**
* {@inheritdoc}
*/
public function reset() {
$this->storage = [];
$this->keysToPersist = [];
$this->keysToRemove = [];
$this->cacheLoaded = FALSE;
}
/**
* {@inheritdoc}
*/
public function clear() {
$this
->reset();
if ($this->tags) {
Cache::invalidateTags($this->tags);
}
else {
$this->cache
->delete($this
->getCid());
}
}
/**
* {@inheritdoc}
*/
public function destruct() {
$this
->updateCache();
}
/**
* Loads the cache if not already done.
*/
protected function lazyLoadCache() {
if ($this->cacheLoaded) {
return;
}
// The cache was not yet loaded, set flag to TRUE.
$this->cacheLoaded = TRUE;
if ($cache = $this->cache
->get($this
->getCid())) {
$this->cacheCreated = $cache->created;
$this->storage = $cache->data;
}
}
/**
* Invalidate the cache.
*/
protected function invalidateCache() {
// Invalidate the cache to make sure that other requests immediately see the
// deletion before this request is terminated.
$this->cache
->invalidate($this
->getCid());
$this->cacheInvalidated = TRUE;
}
}
Members
Name | Modifiers | Type | Description | Overrides |
---|---|---|---|---|
CacheCollector:: |
protected | property | The cache backend that should be used. | 1 |
CacheCollector:: |
protected | property | Stores the cache creation time. | |
CacheCollector:: |
protected | property | Flag that indicates of the cache has been invalidated. | |
CacheCollector:: |
protected | property | Indicates if the collected cache was already loaded. | |
CacheCollector:: |
protected | property | The cache id that is used for the cache entry. | |
CacheCollector:: |
protected | property | An array of keys to add to the cache on service termination. | |
CacheCollector:: |
protected | property | An array of keys to remove from the cache on service termination. | |
CacheCollector:: |
protected | property | The lock backend that should be used. | 1 |
CacheCollector:: |
protected | property | Storage for the data itself. | |
CacheCollector:: |
protected | property | A list of tags that are used for the cache entry. | |
CacheCollector:: |
public | function |
Clears the collected cache entry. Overrides CacheCollectorInterface:: |
1 |
CacheCollector:: |
public | function |
Deletes the element. Overrides CacheCollectorInterface:: |
|
CacheCollector:: |
public | function |
Performs destruct operations. Overrides DestructableInterface:: |
|
CacheCollector:: |
public | function |
Gets value from the cache. Overrides CacheCollectorInterface:: |
2 |
CacheCollector:: |
protected | function | Gets the cache ID. | 3 |
CacheCollector:: |
public | function |
Returns whether data exists for this key. Overrides CacheCollectorInterface:: |
1 |
CacheCollector:: |
protected | function | Invalidate the cache. | |
CacheCollector:: |
protected | function | Loads the cache if not already done. | 1 |
CacheCollector:: |
protected | function | Normalizes a cache ID in order to comply with database limitations. | |
CacheCollector:: |
protected | function | Flags an offset value to be written to the persistent cache. | |
CacheCollector:: |
public | function |
Resets the local cache. Overrides CacheCollectorInterface:: |
1 |
CacheCollector:: |
abstract protected | function | Resolves a cache miss. | 7 |
CacheCollector:: |
public | function |
Implements \Drupal\Core\Cache\CacheCollectorInterface::set(). Overrides CacheCollectorInterface:: |
1 |
CacheCollector:: |
protected | function | Writes a value to the persistent cache immediately. | 1 |
CacheCollector:: |
public | function | Constructs a CacheCollector object. | 6 |