Download the PHP package bbc/ipr-cache without Composer

BBC\iPlayerRadio\Cache

A simple cache wrapper around Doctrine\Cache that allows us to do standard, fuzzy and stale-while-revalidate caching.

• Requirements
• Usage
  • Getting Started
  • Reading Items
  • Fuzzy Caching
  • Pure Caching
  • Stale While Revalidate Caching
  • Cache Prefixing
• Interfaces
• Mocking the Cache

Requirements

• PHP >= 5.5
• A cache backend that Doctrine/Cache understands

Usage

Getting Started

Install via Composer:

Now you need to construct an instance of BBC\iPlayerRadio\Cache, with an instance of Doctrine\Common\Cache\Cache passed to it. Here's a simple example:

The $cacheAdapter is the thing that actually does the reading and writing to the cache, our library just wraps it. Therefore we accept any of the Doctrine\Common\Cache\* classes, so if you're using Redis, or Memcached, or even plain old filesystem caches, this library will work with it. (More specifically, any class implementing the Doctrine\Common\Cache\Cache interface is accepted).

Reading Items

This library handles reading cache items slightly differently to what you might be used to. The "traditional" way, as used by Doctrine, works something like this:

This works great for a simple use-case, however if you want to be able to do things like fuzzing and stale-while-revalidate cleanly, this API style gets clunky quickly.

Instead, this library uses a repository pattern for reading and writing items into cache. This allows us to encapsulate the logic of the different cache modes more cleanly, even if it does look a bit strange at first!

Here's how we read an item from the cache:

You can if you really want, construct a BBC\iPlayerRadio\Cache\CacheItem instance yourself, however the easiest way is to simply call $cache->get('myCacheKey'); as it'll always give you back a CacheItem instance, regardless of whether it's present in the cache or not.

"Fuzzy" Caching

Let's say you have a page section that requires five operations to build itself. If we cache all of them for the same length of time, they'll all expire at the same moment, potentially overloading the service as it tries to rebuild everything at once. One way of mitigating against this is to "fuzz" your cache lifetimes; adding or subtracting a random number from any lifetime to ensure that things drop out in a more spread out way.

This is the default mode of operation for this library, all your cache times will be "fuzzed" by +/- 5% to prevent engineering a stampede. Here's how to use it:

As you can see, the cache handles the fuzzing automatically.

The default fuzz is 5%, but you can change that using setFuzz():

"Pure" Caching

What if you don't want to fuzz your lifetimes? Easy, you can use "pure" caching which essentially is just turning the fuzzing off:

Stale While Revalidate Caching

Stale while revalidate (sometimes known as "soft") caching introduces two different lifetimes for an object; it's Best Before and it's Expires time.

Once an item has exceeded it's Best Before (and become "stale"), clients should attempt to rebuild the data. Should that rebuild fail however, they can continue to use the stale data.

However an expires date works the same as in the other two modes, at that point it will be flushed from the caching backend and you must rebuild your data or gracefully degrade.

Here's how to use stale while revalidate caching:

Stale while revalidate caching and fuzzing

If you elect to use soft caching by calling setBestBefore() then the fuzzing will be applied to the Best Before time and NOT the Expires time. This is again to prevent a stampede as your app begins re-requesting data.

Cache Prefixing

New in v1.1.0

The Cache class can invisibly add an additional prefix to all of the cache keys you're supplying. This is useful when you know two applications are writing into the cache backend with similar keys (md5'd strings for instance).

You never need to use the prefix again; reading, writing and deleting objects all happens as if the prefix isn't there, the Cache class handles it all internally:

Interfaces

When passing caches as parameters, please type hint against the CacheInterface rather than Cache explicitly:

There is naturally also a BBC\iPlayerRadio\Cache\CacheItemInterface as well should you wish to write your own implementation of the cache item.

Mocking the Cache

You can easily have a mock cache instance within your unit tests by using the ArrayCache adapter from Doctrine. This is exactly how we test the Cache class itself;