New cache API

See Drupal 8 Cache API for current documentation.

The following compares, at a high level, caching in Drupal 7 to caching Drupal 8.

Manipulating Cache

Caching in Drupal 7

Cache manipulation in Drupal 7 was achieved through several procedural functions.

_cache_get_object()
cache_get()
cache_get_multiple()
cache_set()
cache_clear_all()
cache_is_empty()

cache_clear_all() was especially troublesome with cache_clear_all(), cache_clear_all(NULL, $bin) and cache_clear_all('*', $bin, TRUE) all meaning subtly different things.

Also, during Drupal 7 we added the _cache_get_object() factory, an interface for cache backends etc., but this is all hidden behind procedural wrappers.

The Drupal 8 Cache factory

The new API removes cache_clear_all(), and its confusing, overloaded arguments. Deleting items from cache, expiring them or flushing the entire cache bin are now separate methods opposed to the previous, all-in-one clear() method.

The default cache object may be referenced by calling \Drupal::cache(). The cache() method accepts a string argument that can specify a cache bin other than the default. For example:

  if ($cached = \Drupal::cache()->get($cid)) {
    return $cached->data;
  }
  else {
    $data = rebuild_my_data();
    \Drupal::cache()->set($cid, $data);
  }
  // Or with a $bin other than 'default'.
  $cache = \Drupal::cache('bootstrap');
  $cache->get($cid);
  $cache->set($cid, $data);
  $cids = array(1, 2, 3);
  $cache->getMultiple($cids);
  $cache->deleteAll();
}

See the Cache API, Basics documentation for more information about the Cache object and Cache bins for more information about bins.

All cache implementations must implement the Drupal\Core\Cache\CacheBackendInterface interface. The methods of this interface include:

get()
getMultiple()
set()
delete()
deleteMultiple()
deleteTags()
deleteAll()
invalidate()
invalidateMultiple()
invalidateTags()
invalidateAll()
garbageCollection()
removeBin()

The isEmpty() equivalent to cache_is_empty() is no longer necessary and was removed in Drupal 8.

Cache deletion and invalidation

The Drupal 8 Cache API introduces a new way to “remove” a cache item. In addition to the existing delete methods where cache entries are permanently deleted, cache entries can now also be invalidated.

Delete methods

• delete()
• deleteMultiple()
• deleteTags()
• deleteAll()

Invalidate methods

• invalidate()
• invalidateMultiple()
• invalidateTags()
• invalidateAll()

Invalidation is like a “soft delete” where items are not deleted but only marked as invalid, meaning “not fresh” or “not fresh enough”. An item automatically becomes invalid when the expire time specified in the set() call is reached, or it may explicitly be marked as invalid using the functions listed above. The invalid items are not returned by a normal get() call, so in most ways they act as they have been deleted. However, by passing TRUE as the second argument for get(), it is possible to fetch the invalid value.

Comparison of Drupal 7 to Drupal 8 cache deletion:

// Drupal 7
cache_set("theme_registry:$theme->name", $registry);
cache_clear_all('theme_registry', 'cache', TRUE);
//
// Drupal 8
// Registry.php
$this->cache->set('theme_registry:' . $this->theme->getName(), $this->registry, Cache::PERMANENT, array('theme_registry' => TRUE));
// BookManager.php
\Drupal::cache('data')->deleteTags(array('bid:' . $bid));
// Contrived example, explicit invalidation
\Drupal::cache()->set('foo', 123);
\Drupal::cache()->get('foo'); // Returns a cache item
\Drupal::cache()->invalidate('foo');
\Drupal::cache()->get('foo'); // Returns FALSE
\Drupal::cache()->get('foo', TRUE); // Returns a cache item
\Drupal::cache()->garbageCollection();
\Drupal::cache()->get('foo', TRUE); // Returns FALSE
// Contrived example, expired items
\Drupal::cache()->set('bar', 123, REQUEST_TIME + 60);
\Drupal::cache()->get('bar'); // Returns a cache item
// The next lines run 61 seconds later in a new request.
\Drupal::cache()->get('bar'); // Returns FALSE
\Drupal::cache()->get('bar', TRUE); // Returns a cache item
\Drupal::cache()->garbageCollection();
\Drupal::cache()->get('bar', TRUE); // Returns FALSE

See Cache API, Delete for more information about cache deletion and invalidation.

Cache tags

The fourth argument of the \Drupal->cache::set() method can be used to specify cache tags, which are used to identify what type of data is included in each cache. Cache tags did not exist in Drupal 7. Caches may be deleted or invalidated by specifying tags.

See Cache API, tags for more information.

Cache bins

Cache bins have been re-organised to more closely match their usage:

cache.default: the default bin
Caution: cache.default used to be cache.cache.

cache.bootstrap: for items needed during bootstrap

cache.config:CMI configuration objects

cache.entity: entity items (replaces the field cache).

cache.render: cached HTML strings (replaces cache_page, cache_block etc.)

cache.data: for data structures such as path alias pre-loading, menu trees etc.