Download the PHP package geekcache/geekcache without Composer

GeekCache

GeeKCache is a wrapper for Memcached with tags, soft invalidation, memoization, and regeneration through callbacks. It is free (MIT license), fully tested and easily extendable. It also beta, so all disclaimers regarding using beta software in production apply, especially regarding functional changes, but it is in active use on http://boardgamegeek.com.

Installation

GeekCache can be installed via composer.

{
    "require": {
        "geekcache/geekcache": "0.1.*@beta"
    }
}

This package has one package dependency: the service providers requires Laravel's dependency injection container.

GeekCache also requires a key/value storage system for the back end. Currently, GeekCache is implemented for only one system: Memcached, using the Memcached PECL extension.

Usage

To use GeekCache, it is most convenient to use the included service providers to add the builders to the container.

If your Memcache server or servers are running anywhere other than the localhost, port 11211, you can set them as described in the Configuration section, below.

Once the service is registered, you can resolve the builders and the clearer from the container. The builder is the object you should inject into the constructor of a class that will use caching, while the clearer is used for clearing multiple cache items at once. Here is a simple usage example:

The CacheItem has only three methods: get, put, and delete. The builder is an immutable object, and can be used to make multiple cache items with different options.

Tags

Tags can be added to a CacheItem to allow all items tagged with the same tag to be cleared together.

When any tag is cleared, all cache items that had that tag added will be cleared as well. Note that if you add tags to an item when you store a value, you must add the same tags, in the same order, to the cache item when you want to retrieve the value.

Memoization

Memoization allows you to tell the cache item to store the value retrieved in a local in-memory cache rather than going to the caching service for every lookup. Ths can be useful if you have a cache item that may be looked up many times on a given pageload. Memoization lasts only as long as a PHP process.

Regenerators

Rather than putting data directly into cache, you can pass a callable into get(). If the there is no value in cache, the regenerator will be run, and the result of that will be put into cache (and returned) if it does not return false.

Soft invalidation and queued regeneration

You can also use a regenerator to trigger a process to queue regeneration at some other time, so that the user does not have to wait for a slow process to generate data. If you do so, GeekCache will allow you to return stale data to the user while the regenerator executes, as follows.

While this will get data that has been cleared because a tag has been cleared, by default the same is not true of data that has expired due to time. However, you can set a grace period for your cache item, so that even data that has gone past its expiration time is available when a regenerator that returns false is passed.

You can also set a grace period of 0, which indicates that the stale value should ALWAYS be available when a $regenerator is passed, similar to setting an expire value of 0 for Memcached. If you add a grace period when you save an item, you must also include the grace period when you get the result. (I hope to remove this limitation a future version of GeekCache.)

Counter

A counter is a simple cache with the same methods as CacheItem, plus increment(). Incrementing is atomic; even if multiple processes increment at the same time, the total will remain correct. It can be built similarly to how the CacheItem is built (counters have their own builder), with the caveat that the only option available is memoization--Tags or grace periods are not available for counters, in order to more easily maintain atomic incrementing.

Usage notes

You can safely cache any value or serializable data structure, with the exception of the boolean false, which cannot be cached. If you need to cache a value that may be false, I suggest serializing/unserializing the data. I'd like to remove this limitation in a future version of this library.

A note regarding using these features together: Internally, the builder adds features to the cache item in the order you call the add function. For this reason, if you are going to memoize the cache item, call memoize first.

A grace period is useless unless you plan to pass in a regenerator which queues a process for regeneration (and returns false).

A regenerator is guaranteed to be called only once for a given get(). In addition, a single parameter is passed to the regenerator: a boolean indicating whether stale data is available to be returned. The intended purpose of this boolean is so that the $regenerator can set the priority of the queued process--high priority if blanks are being returned, low priority if stale data is available.

Although a regenerator will be called only once for a get(), if get is called multiple times, or in multiple processes, a regenerator that is queuing regeneration processes may be called multiple times. For this reason, I recommmend a queuing system such as Gearman, which has functionality to coalesce duplicate processes.

Configuration

GeekCache is configured via setting variables on the container--they must be set before GeekCache is used, but need not be set before the providers are registered.