fCache

The fCache class provides a consistent caching interface that can use file, APC, memcached and XCache back-ends. It can be used cache any end-developer data, but is also integrated with the fDatabase, fSQLTranslation and fSchema classes.

APC and XCache are PHP op-code caches that also provide server-wide shared memory caches for user data. File caches use a single file and store serialized PHP data, while memcached is a standalone caching server that can be scaled extensively across machines.

Instantiation

Creating an instance of fCache just requires a $type and $data_store. The $type can be 'apc', 'file', 'memcache' or 'xcache'. Only 'file' and 'memcache' caches require a $data_store.

For 'file' caches, the $data_store should be a file path. For 'memcache' caches, the $data_store should be a PHP Memcache object. Please note there is also a PHP Memcached (note the d at the end) extension, however it is not currently supported as it is PHP 5.2+ only and is current in beta.

$apc_cache = new fCache('apc');
 
$file_cache = new fCache('file', '/path/to/cache');
 
$memcache = new Memcache();
$memcache->connect('localhost', 11211);
$memcache_cache = new fCache('memcache', $memcache);
 
$xcache_cache = new fCache('xcache');

Setting Values

The method set() accepts a $key, $value and optional $ttl (time-to-live). The $key should be a string of 250 characters or less, and the $value should be any PHP data type that can be serialized. The main PHP data type that can not be serialized in a resource.

The $key and $value combination will be stored in the cache permanently, unless a $ttl is provided. The $ttl is the number of seconds the cached $value will be accessible. Values with a $ttl will be cleaned up by whatever back-end is providing the cache. Warning: the APC back-end currently functions in such a way that the $ttl will be ignored when getting a value in the same script execution that it is set.

Please note that all PHP values are serialized before being stored in the cache. This ensures that the exact same value that goes into the cache will come back out, even if the back-end only supports basic types such as strings and integers.

// This value will last until explicitly deleted or the cache is cleared
$file_cache->set('computed_value', $computed_value);
 
// This value will last for 60 seconds
$file_cache->set('other_computed_value', $other_computed_value, 60);

It is also possible to only set a value if the $key does not already exist in the cache. This is performed using the add() method. add() takes the exact same parameters as set(), however it returns a boolean indicating if the value was added.

if ($file_cache->add('master_value', $master_value)) {
    // Compute a related value and store it also
}

Getting Values

The method get() takes the $key to retrieve the value for, and an optional $default to return if the $key is not set. If $default is not specified, NULL will be returned for any $key that is not currently set.

// This will return NULL if there is no value for 'computed_value'
$cached_value = $file_cache->get('computed_value');
 
// This will return 10 if there is no value for 'computed_value'
$cached_value = $file_cache->get('computed_value', 10);

Deleting Values

Values can be deleted individually from the cache by calling the method delete() and passing the $key to delete.

$file_cache->delete('computed_value');

Clearing the Cache

In addition to deleting specific cache entries, it is also possible to clear all of the entries in the cache. This will delete all key/value pairs in your cache, and depending on your cache type, may affect all other websites on the same server.

Please note that the XCache back-end may require an administrator login and password to clear the cache. This setting, and the login/password settings are controlled by ini settings.

$file_cache->clear();