Flourish PHP Unframework

fCache

Class Resources

Variables

Methods

Uses

class, v1.0.0b6

A simple interface to cache data using different backends

Changes:
1.0.0b6Fixed a bug with add() setting a value when it shouldn't if no ttl was given for the file backend 1/12/12
1.0.0b5Added missing documentation for using Redis as a backend 8/25/11
1.0.0b4Added the database, directory and redis types, added support for the memcached extention and support for custom serialization callbacks 6/21/11
1.0.0b3Added 0 to the memcache delete method call since otherwise the method triggers notices on some installs 5/10/11
1.0.0b2Fixed API calls to the memcache extension to pass the TTL as the correct parameter 2/1/11
1.0.0bThe initial implementation 4/28/09

Variables

->config protected

The cache configuration, used for database, directory and file caches

The array structure for database caches is: 

array(
    'table'        => (string) {the database table to use},
    'key_column'   => (string) {the varchar column to store the key in, should be able to handle at least 250 characters},
    'value_column' => (string) {the text/varchar column to store the value in},
    'ttl_column'   => (string) {the integer column to store the expiration time in}
)

The array structure for directory caches: 

array(
    'path' => (string) {the directory path with trailing slash}
)

The array structure for file caches: 

array(
    'path'  => (string) {the file path},
    'state' => (string) {clean or dirty, used to appropriately save}
)

Type

array

->data_store protected

The data store to use

Either the:

  • array structure for file cache
  • Memcache or Memcached object for memcache
  • fDatabase object for database
  • Redis object for redis

Not used for apc, directory or xcache

Type

mixed

->type protected

The type of cache

The valid values are:

  • 'apc'
  • 'database'
  • 'directory'
  • 'file'
  • 'memcache'
  • 'redis'
  • 'xcache'

Type

string

Methods

->__construct() public

Set the type and master key for the cache

A file cache uses a single file to store values in an associative array and is probably not suitable for a large number of keys.

Using an apc or xcache cache will have far better performance than a file or directory, however please remember that keys are shared server-wide.

$config is an associative array of configuration options for the various backends. Some backend require additional configuration, while others provide provide optional settings.

The following $config options must be set for the database backend:

  • table: The database table to use for caching
  • key_column: The column to store the cache key in - must support at least 250 character strings
  • value_column: The column to store the serialized value in - this should probably be a TEXT column to support large values, or BLOB if binary serialization is used
  • value_data_type: If a BLOB column is being used for the value_column, this should be set to 'blob', otherwise string
  • ttl_column: The column to store the expiration timestamp of the cached entry - this should be an integer

The following $config for the following items can be set for all backends:

  • serializer: A callback to serialize data with, defaults to the PHP function serialize()
  • unserializer: A callback to unserialize data with, defaults to the PHP function unserialize()

Common serialization callbacks include:

  • json_encode/json_decode
  • igbinary_serialize/igbinary_unserialize

Please note that using JSON for serialization will exclude all non-public properties of objects from being serialized.

A custom serialize and unserialze option is string, which will cast all values to a string when storing, instead of serializing them. If a __toString() method is provided for objects, it will be called.

Signature

fCache __construct( string $type, mixed $data_store=NULL, array $config=array() )

Parameters

string $type The type of caching to use: 'apc', 'database', 'directory', 'file', 'memcache', 'redis', 'xcache'
mixed $data_store The path for a file or directory cache, an Memcache or Memcached object for a memcache cache, an fDatabase object for a database cache or a Redis object for a redis cache - not used for apc or xcache
array $config Configuration options - see method description for details

->__destruct() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Cleans up after the cache object

Signature

void __destruct( )

->add() public

Tries to set a value to the cache, but stops if a value already exists

Signature

boolean add( string $key, mixed $value, integer $ttl=0 )

Parameters

string $key The key to store as, this should not exceed 250 characters
mixed $value The value to store, this will be serialized
integer $ttl The number of seconds to keep the cache valid for, 0 for no limit

Returns

If the key/value pair were added successfully

->clean() public

Removes all cache entries that have expired

Signature

void clean( )

->clear() public

Clears the WHOLE cache of every key, use with caution!

xcache may require a login or password depending on your ini settings.

Signature

boolean clear( )

Returns

If the cache was successfully cleared

->delete() public

Deletes a value from the cache

Signature

boolean delete( string $key )

Parameters

string $key The key to delete

Returns

If the delete succeeded

->get() public

Returns a value from the cache

Signature

mixed get( string $key, mixed $default=NULL )

Parameters

string $key The key to return the value for
mixed $default The value to return if the key did not exist

Returns

The cached value or the default value if no cached value was found

->save() public

Only valid for file caches, saves the file to disk

Signature

void save( )

->serialize() protected

Serializes a value before storing it in the cache

Signature

string serialize( mixed $value )

Parameters

mixed $value The value to serialize

Returns

The serialized value

->set() public

Sets a value to the cache, overriding any previous value

Signature

boolean set( string $key, mixed $value, integer $ttl=0 )

Parameters

string $key The key to store as, this should not exceed 250 characters
mixed $value The value to store, this will be serialized
integer $ttl The number of seconds to keep the cache valid for, 0 for no limit

Returns

If the value was successfully saved

->unserialize() protected

Unserializes a value before returning it

Signature

mixed unserialize( string $value )

Parameters

string $value The serialized value

Returns

The PHP value