class ApcuBackend in Drupal 9

Stores cache items in the Alternative PHP Cache User Cache (APCu).

Hierarchy

• class \Drupal\Core\Cache\ApcuBackend implements CacheBackendInterface

1 file declares its use of ApcuBackend

ApcuBackendTest.php in core/tests/Drupal/KernelTests/Core/Cache/ApcuBackendTest.php

File

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

Namespace

Drupal\Core\Cache

class ApcuBackend implements CacheBackendInterface {

  /**
   * The name of the cache bin to use.
   *
   * @var string
   */
  protected $bin;

  /**
   * Prefix for all keys in the storage that belong to this site.
   *
   * @var string
   */
  protected $sitePrefix;

  /**
   * Prefix for all keys in this cache bin.
   *
   * Includes the site-specific prefix in $sitePrefix.
   *
   * @var string
   */
  protected $binPrefix;

  /**
   * The cache tags checksum provider.
   *
   * @var \Drupal\Core\Cache\CacheTagsChecksumInterface
   */
  protected $checksumProvider;

  /**
   * Constructs a new ApcuBackend instance.
   *
   * @param string $bin
   *   The name of the cache bin.
   * @param string $site_prefix
   *   The prefix to use for all keys in the storage that belong to this site.
   * @param \Drupal\Core\Cache\CacheTagsChecksumInterface $checksum_provider
   *   The cache tags checksum provider.
   */
  public function __construct($bin, $site_prefix, CacheTagsChecksumInterface $checksum_provider) {
    $this->bin = $bin;
    $this->sitePrefix = $site_prefix;
    $this->checksumProvider = $checksum_provider;
    $this->binPrefix = $this->sitePrefix . '::' . $this->bin . '::';
  }

  /**
   * Prepends the APCu user variable prefix for this bin to a cache item ID.
   *
   * @param string $cid
   *   The cache item ID to prefix.
   *
   * @return string
   *   The APCu key for the cache item ID.
   */
  public function getApcuKey($cid) {
    return $this->binPrefix . $cid;
  }

  /**
   * {@inheritdoc}
   */
  public function get($cid, $allow_invalid = FALSE) {
    $cache = apcu_fetch($this
      ->getApcuKey($cid));
    return $this
      ->prepareItem($cache, $allow_invalid);
  }

  /**
   * {@inheritdoc}
   */
  public function getMultiple(&$cids, $allow_invalid = FALSE) {

    // Translate the requested cache item IDs to APCu keys.
    $map = [];
    foreach ($cids as $cid) {
      $map[$this
        ->getApcuKey($cid)] = $cid;
    }
    $result = apcu_fetch(array_keys($map));
    $cache = [];
    if ($result) {
      foreach ($result as $key => $item) {
        $item = $this
          ->prepareItem($item, $allow_invalid);
        if ($item) {
          $cache[$map[$key]] = $item;
        }
      }
    }
    unset($result);
    $cids = array_diff($cids, array_keys($cache));
    return $cache;
  }

  /**
   * Returns all cached items, optionally limited by a cache ID prefix.
   *
   * APCu is a memory cache, shared across all server processes. To prevent
   * cache item clashes with other applications/installations, every cache item
   * is prefixed with a unique string for this site. Therefore, functions like
   * apcu_clear_cache() cannot be used, and instead, a list of all cache items
   * belonging to this application need to be retrieved through this method
   * instead.
   *
   * @param string $prefix
   *   (optional) A cache ID prefix to limit the result to.
   *
   * @return \APCUIterator
   *   An APCUIterator containing matched items.
   */
  protected function getAll($prefix = '') {
    return $this
      ->getIterator('/^' . preg_quote($this
      ->getApcuKey($prefix), '/') . '/');
  }

  /**
   * Prepares a cached item.
   *
   * Checks that the item is either permanent or did not expire.
   *
   * @param object $cache
   *   An item loaded from self::get() or self::getMultiple().
   * @param bool $allow_invalid
   *   If TRUE, a cache item may be returned even if it is expired or has been
   *   invalidated. See ::get().
   *
   * @return mixed
   *   The cache item or FALSE if the item expired.
   */
  protected function prepareItem($cache, $allow_invalid) {
    if (!isset($cache->data)) {
      return FALSE;
    }
    $cache->tags = $cache->tags ? explode(' ', $cache->tags) : [];

    // Check expire time.
    $cache->valid = $cache->expire == Cache::PERMANENT || $cache->expire >= REQUEST_TIME;

    // Check if invalidateTags() has been called with any of the entry's tags.
    if (!$this->checksumProvider
      ->isValid($cache->checksum, $cache->tags)) {
      $cache->valid = FALSE;
    }
    if (!$allow_invalid && !$cache->valid) {
      return FALSE;
    }
    return $cache;
  }

  /**
   * {@inheritdoc}
   */
  public function set($cid, $data, $expire = CacheBackendInterface::CACHE_PERMANENT, array $tags = []) {
    assert(Inspector::assertAllStrings($tags), 'Cache tags must be strings.');
    $tags = array_unique($tags);
    $cache = new \stdClass();
    $cache->cid = $cid;
    $cache->created = round(microtime(TRUE), 3);
    $cache->expire = $expire;
    $cache->tags = implode(' ', $tags);
    $cache->checksum = $this->checksumProvider
      ->getCurrentChecksum($tags);

    // APCu serializes/unserializes any structure itself.
    $cache->serialized = 0;
    $cache->data = $data;

    // Expiration is handled by our own prepareItem(), not APCu.
    apcu_store($this
      ->getApcuKey($cid), $cache);
  }

  /**
   * {@inheritdoc}
   */
  public function setMultiple(array $items = []) {
    foreach ($items as $cid => $item) {
      $this
        ->set($cid, $item['data'], isset($item['expire']) ? $item['expire'] : CacheBackendInterface::CACHE_PERMANENT, isset($item['tags']) ? $item['tags'] : []);
    }
  }

  /**
   * {@inheritdoc}
   */
  public function delete($cid) {
    apcu_delete($this
      ->getApcuKey($cid));
  }

  /**
   * {@inheritdoc}
   */
  public function deleteMultiple(array $cids) {
    apcu_delete(array_map([
      $this,
      'getApcuKey',
    ], $cids));
  }

  /**
   * {@inheritdoc}
   */
  public function deleteAll() {
    apcu_delete($this
      ->getIterator('/^' . preg_quote($this->binPrefix, '/') . '/'));
  }

  /**
   * {@inheritdoc}
   */
  public function garbageCollection() {

    // APCu performs garbage collection automatically.
  }

  /**
   * {@inheritdoc}
   */
  public function removeBin() {
    apcu_delete($this
      ->getIterator('/^' . preg_quote($this->binPrefix, '/') . '/'));
  }

  /**
   * {@inheritdoc}
   */
  public function invalidate($cid) {
    $this
      ->invalidateMultiple([
      $cid,
    ]);
  }

  /**
   * {@inheritdoc}
   */
  public function invalidateMultiple(array $cids) {
    foreach ($this
      ->getMultiple($cids) as $cache) {
      $this
        ->set($cache->cid, $cache, REQUEST_TIME - 1);
    }
  }

  /**
   * {@inheritdoc}
   */
  public function invalidateAll() {
    foreach ($this
      ->getAll() as $data) {
      $cid = str_replace($this->binPrefix, '', $data['key']);
      $this
        ->set($cid, $data['value'], REQUEST_TIME - 1);
    }
  }

  /**
   * Instantiates and returns the APCUIterator class.
   *
   * @param mixed $search
   *   A PCRE regular expression that matches against APC key names, either as a
   *   string for a single regular expression, or as an array of regular
   *   expressions. Or, optionally pass in NULL to skip the search.
   * @param int $format
   *   The desired format, as configured with one or more of the APC_ITER_*
   *   constants.
   * @param int $chunk_size
   *   The chunk size. Must be a value greater than 0. The default value is 100.
   * @param int $list
   *   The type to list. Either pass in APC_LIST_ACTIVE or APC_LIST_DELETED.
   *
   * @return \APCUIterator
   */
  protected function getIterator($search = NULL, $format = APC_ITER_ALL, $chunk_size = 100, $list = APC_LIST_ACTIVE) {
    return new \APCUIterator($search, $format, $chunk_size, $list);
  }

}

Members

Name	Modifiers	Type	Description	Overrides
ApcuBackend::$bin	protected	property	The name of the cache bin to use.
ApcuBackend::$binPrefix	protected	property	Prefix for all keys in this cache bin.
ApcuBackend::$checksumProvider	protected	property	The cache tags checksum provider.
ApcuBackend::$sitePrefix	protected	property	Prefix for all keys in the storage that belong to this site.
ApcuBackend::delete	public	function	Deletes an item from the cache. Overrides CacheBackendInterface::delete
ApcuBackend::deleteAll	public	function	Deletes all cache items in a bin. Overrides CacheBackendInterface::deleteAll
ApcuBackend::deleteMultiple	public	function	Deletes multiple items from the cache. Overrides CacheBackendInterface::deleteMultiple
ApcuBackend::garbageCollection	public	function	Performs garbage collection on a cache bin. Overrides CacheBackendInterface::garbageCollection
ApcuBackend::get	public	function	Returns data from the persistent cache. Overrides CacheBackendInterface::get
ApcuBackend::getAll	protected	function	Returns all cached items, optionally limited by a cache ID prefix.
ApcuBackend::getApcuKey	public	function	Prepends the APCu user variable prefix for this bin to a cache item ID.
ApcuBackend::getIterator	protected	function	Instantiates and returns the APCUIterator class.
ApcuBackend::getMultiple	public	function	Returns data from the persistent cache when given an array of cache IDs. Overrides CacheBackendInterface::getMultiple
ApcuBackend::invalidate	public	function	Marks a cache item as invalid. Overrides CacheBackendInterface::invalidate
ApcuBackend::invalidateAll	public	function	Marks all cache items as invalid. Overrides CacheBackendInterface::invalidateAll
ApcuBackend::invalidateMultiple	public	function	Marks cache items as invalid. Overrides CacheBackendInterface::invalidateMultiple
ApcuBackend::prepareItem	protected	function	Prepares a cached item.
ApcuBackend::removeBin	public	function	Remove a cache bin. Overrides CacheBackendInterface::removeBin
ApcuBackend::set	public	function	Stores data in the persistent cache. Overrides CacheBackendInterface::set
ApcuBackend::setMultiple	public	function	Store multiple items in the persistent cache. Overrides CacheBackendInterface::setMultiple
ApcuBackend::__construct	public	function	Constructs a new ApcuBackend instance.
CacheBackendInterface::CACHE_PERMANENT		constant	Indicates that the item should never be removed unless explicitly deleted.