Cache Items

Cache Item Keys and Values

The key of a cache item is a plain string which acts as its identifier, so it must be unique for each cache pool. You can freely choose the keys, but they should only contain letters (A-Z, a-z), numbers (0-9) and the _ and . symbols. Other common symbols (such as {, }, (, ), /, \, @ and :) are reserved by the PSR-6 standard for future uses.

The value of a cache item can be any data represented by a type which is serializable by PHP, such as basic types (string, integer, float, boolean, null), arrays and objects.

Creating Cache Items

Cache items are created with the getItem($key) method of the cache pool. The argument is the key of the item:

1
2

// $cache pool object was created before
$productsCount = $cache->getItem('stats.products_count');

Then, use the set() method to set the data stored in the cache item:

1
2
3
4
5
6
7
8
9
10

// storing a simple integer
$productsCount->set(4711);
$cache->save($productsCount);

// storing an array
$productsCount->set([
    'category1' => 4711,
    'category2' => 2387,
]);
$cache->save($productsCount);

The key and the value of any given cache item can be obtained with the corresponding getter methods:

1
2
3
4

$cacheItem = $cache->getItem('exchange_rate');
// ...
$key = $cacheItem->getKey();
$value = $cacheItem->get();

1
2
3
4
5

$latestNews = $cache->getItem('latest_news');
$latestNews->expiresAfter(60);  // 60 seconds = 1 minute

// this method also accepts \DateInterval instances
$latestNews->expiresAfter(DateInterval::createFromDateString('1 hour'));

1
2

$mostPopularNews = $cache->getItem('popular_news');
$mostPopularNews->expiresAt(new \DateTime('tomorrow'));

Cache Item Hits and Misses

Using a cache mechanism is important to improve the application performance, but it should not be required to make the application work. In fact, the PSR-6 standard states that caching errors should not result in application failures.

In practice this means that the getItem() method always returns an object which implements the Psr\Cache\CacheItemInterface interface, even when the cache item doesn't exist. Therefore, you don't have to deal with null return values and you can safely store in the cache values such as false and null.

In order to decide if the returned object is correct or not, caches use the concept of hits and misses:

• Cache Hits occur when the requested item is found in the cache, its value is not corrupted or invalid and it hasn't expired;
• Cache Misses are the opposite of hits, so they occur when the item is not found in the cache, its value is corrupted or invalid for any reason or the item has expired.

Cache item objects define a boolean isHit() method which returns true for cache hits:

1
2
3
4
5
6
7
8
9

$latestNews = $cache->getItem('latest_news');

if (!$latestNews->isHit()) {
    // do some heavy computation
    $news = ...;
    $cache->save($latestNews->set($news));
} else {
    $news = $latestNews->get();
}