Core:Cache Class

From Habari Project

Revision as of 02:36, 5 November 2010 by chrismeller (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


Storing Cache

The way you store something in the cache should be the same no matter what kind of cache system your installation is using. Items in the cache are organised into groups (with the default group being 'default').

Adding an item to the cache is very straight forward. The following example adds the item $value to the cache and sets them to expire after one hour.

// Add an item (named 'name') in a specific group (named 'group')
Cache::set(array('group', 'name'), $value, 3600);
// Add an item with no group
Cache::set('name', $value, 3600)

The set method takes three parameters.

  1. The first can be either an array with two items (the group and the name) or a string (just the name). If a string is passed the value will be put into the default group.
  2. The second is the value to store. There's no need to worry about serialisation of arrays or object (this should be handled by the cache class).
  3. The third parameter is the time (in seconds) after which the cache will expire. This is optional, and the default is 3600 (1 hour).

As a general rule you should always define the group your cache item should be stored in. This will go a long way to avoiding conflicts between plugins which use the cache unintentionally overwriting each others cached values.

Extending a Cache's Life

Extending a cache's life is super simple as well. All you need to know is how long you want the cache to stay alive (from now, in seconds) and what the cache is called (and maybe it's group if it has one).

// Extend a cache item with a specified group by one hour
Cache::extend(array('group','name'), 3600);
// Extend a cache item without a specified group by two hours
Cache::extend('name', 7200);

Forcing a Cache's Expiration

Forcing a cache to expire is also super easy (are you starting to get the picture - it's easy). All you need to know is the name of the cache item and its group if it has one.

// Expire a cache item in a specific group
Cache::expire(array('group', 'name'));
// Expire a cache item which isn't in a specified group

Retrieving Cache

Getting an item back out of cache is, also, very straight forward. Just as for adding items to the cache there is no need to worry about (un)serialisation of complex variables or anything like that. It's as simple as a single method call.

// Get the cached item named 'name' from the group 'group'
$value = Cache::get(array('group', 'name');
// Get the cached item named 'name' which isn't in a specific group.
$value = Cache::get('name');

You can also retrieve whole groups from the cache at once using the Cache::get_group() method.

// Get all items stored in the group named 'group'
$cached_group = Cache::get_group('group');
    [item_name] => Item value.
    [another_item] => Array
            [0] => another item's value (this time it's an array)

If you try and retrieve a cached value that isn't in the cache (either hasn't been set or has expired) the Cache::get() method will return NULL. Since NULL could be a valid value to store in the cache, you'll probably want to check if the value exists in cache explicitly rather than relying on the return value of Cache::get().

Verifying a Cache Existence

To check if the cache contains a specific item use the Cache::has() method in exactly the same way you'd use the Cache::get() method. The only difference is that it will simply return a boolean value indicating if the item exists in cache (including for an item with a value of NULL).

// Check the existence of an item named 'name' in the group 'group'
$exists = Cache::has(array('group', 'name'));
// Check the existence of an item named 'name' which isn't in a specific group
$exists = Cache::has('name');

Just like with the Cache::get_group() method (see above) there is a Cache::has_group() method which you can use to check if the cache has current items stored in a specific group.

// Check if the cache has items in a group called 'group'
$group_exists = Cache::has_group('group');

Quick Start: Usage Examples

The following code example could be written in many other ways, but it's just there to get you started, quickly. There are also many other ways and contexts in which you might want to use the Cache class, but this assumes you're using it in the context of a plugin class.

 * This method performs some computationally intense
 * calculation  or goes and gets a bunch of stuff 
 * off the web via some API and returns a value. We 
 * want to make sure this doesn't have to happen too 
 * often. 
 * Abusing APIs and slow page loads are bad, mmmk?
function get_my_data() {
    if (!Cache::has(array('MyPluginClassName', 'my_data'))) {
        $my_data = array();
        // Do the really intense stuff here and store the result in $my_data
        // Store it in a sensible place in the cache
        // and make sure it doesn't expire for a 
        // couple of hours
        Cache::set(array('MyPluginClassName', 'my_data'), $my_data, 7200);
        return $my_data;
    return Cache::get(array('MyPluginClassName', 'my_data'));

How Cache Works

The Cache class itself is an abstract class and therefore cannot be instantiated. However, it uses the magic of static functions, and specifically the (Habari provided) magic method __static() to create an instance of one of its child classes (FileCache by default) and store that instance in a static variable. The __static() method is called the very first time the Cache class is used (by the magic of __autoload()).

After instantiating one of its inheriting classes via the magic described above, the Cache class does two things:

  1. Provides a bunch of publicly accessible static methods which can be used to manage cached data:
    • has( $name )
    • has_group( $group )
    • get( $name )
    • get_group( $group )
    • set( $name, $value, $expiry = 3600 )
    • expire( $name )
    • extend( $name, $expiry )
  2. Defines a bunch of analogous abstract methods which the child class it has instantiated must define which actually do the caching work:
    • _has( $name, $group )
    • _has_group( $group )
    • _get( $name, $group )
    • _get_group( $group )
    • _set( $name, $value, $expiry, $group )
    • _expire( $name, $group )
    • _extend( $name, $expiry, $group )

Classes Extending Cache

This page describes a PHP class that is in the Habari software. For more comprehensive technical information visit the API Documentation.
Other Class Pages
Personal tools