Path

ez components / documentation / api reference / 2009.1alpha1 / cache


eZ Components 2009.1alpha1

Cache: ezcCacheStorage

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcCacheStorage

This is the abstract base class for all cache storages. It provides the interface to be implemented by a cache backend as abstract methods. [source]
For your convenience it contains some methods you can utilize to create your own storage implementation (e.g. for storing cache data into a database).
Implementations of ezcCacheStorage can be used with the ezcCacheManager or on their own. If you want to implement a cache storage backend that stores cache data in a file on your harddisk, there is an extended version of ezcCacheStorage, ezcCacheStorageFile, which already implements large parts of the API and leaves only very few work for you to do. The descendant class ezcCacheStorageMemory is a base class for storage using memory.
For example code of using a cache storage, see ezcCacheManager.
The Cache package already contains several implementations of ezcCacheStorageFile:

Descendents

Child Class Description
ezcCacheStorageMemory Base abstract class for all memory storage classes.
ezcCacheStorageFile This class implements most of the methods which have been declared abstract in ezcCacheStorage, but also declares 2 new methods abstract, which have to be implemented by storage driver itself.
ezcCacheStack Hierarchical caching class using multiple storages.

Properties

string read/write  $location
The location the cache resides in.
ezcCacheStorageOptions read/write  $options
Options for the cache storage. Which options are supported depends on the specific implementation of the ezcCacheStorage.

Member Variables

protected array(string=>mixed) $properties
Container to hold the properties

Method Summary

public ezcCacheStorage __construct( $location, [$options = array()] )
Creates a new cache storage in the given location.
public abstract int countDataItems( [$id = null], [$attributes = array()] )
Return the number of items in the cache matching a certain criteria.
public abstract void delete( [$id = null], [$attributes = array()], [$search = false] )
Delete data from the cache.
public string getLocation( )
Returns the location.
public ezcCacheStorageOptions getOptions( )
Return the currently set options.
public abstract int getRemainingLifetime( $id, [$attributes = array()] )
Returns the time ( in seconds ) that remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exist, this method returns 0.
public abstract mixed restore( $id, [$attributes = array()], [$search = false] )
Restore data from the cache.
public void setOptions( $options )
Set new options.
public abstract string store( $id, $data, [$attributes = array()] )
Store data to the cache storage.
protected abstract void validateLocation( )
Checks if the location property is valid.

Methods

__construct

ezcCacheStorage __construct( string $location, [array(string=>string) $options = array()] )
Creates a new cache storage in the given location.
Creates a new cache storage for a given location. The location can differ for each ezcCacheStorage implementation, but will most likely be a filesystem path to a directory where cache data is stored in. The location is null for memory storage and an existing writeable path for file or memory/file storage.
Per default there is only 1 common option for all ezcCacheStorage classes, which is the 'ttl' ( Time-To-Life ). This is per default set to 1 day. Specific ezcCacheStorage implementations can have additional options.

Parameters

Name Type Description
$location string Path to the cache location. Null for memory-based storage and an existing writeable path for file or memory/file storage.
$options array(string=>string) Options for the cache.

Throws

ClassDescription
ezcBaseFileNotFoundException If the storage location does not exist. This should usually not happen, since ezcCacheManager::createCache() already performs sanity checks for the cache location. In case this exception is thrown, your cache location has been corrupted after the cache was configured.
ezcBaseFileNotFoundException If the storage location is not a directory. This should usually not happen, since ezcCacheManager::createCache() already performs sanity checks for the cache location. In case this exception is thrown, your cache location has been corrupted after the cache was configured.
ezcBaseFilePermissionException If the storage location is not writeable. This should usually not happen, since ezcCacheManager::createCache() already performs sanity checks for the cache location. In case this exception is thrown, your cache location has been corrupted after the cache was configured.
ezcBasePropertyNotFoundException If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and may vary.

Redefined in descendants as

Method Description
ezcCacheStorageMemory::__construct() Creates a new cache storage in the given location.
ezcCacheStorageMemcache::__construct() Creates a new cache storage in the given location.
ezcCacheStorageApc::__construct() Creates a new cache storage in the given location.
ezcCacheStorageFileApcArray::__construct() Creates a new cache storage in the given location. The location in case of this storage class must a valid file system directory.
ezcCacheStorageFile::__construct() Creates a new cache storage in the given location.
ezcCacheStack::__construct() Creates a new cache stack.

countDataItems

int countDataItems( [string $id = null], [array(string=>string) $attributes = array()] )
Return the number of items in the cache matching a certain criteria.
This method determines if cache data described by the given ID and/or attributes exists. It returns the number of cache data items found.

Parameters

Name Type Description
$id string The item ID.
$attributes array(string=>string) Attributes that describe the item

Redefined in descendants as

Method Description
ezcCacheStorageMemory::countDataItems() Returns the number of items in the cache matching a certain criteria.
ezcCacheStorageFile::countDataItems() Return the number of items in the cache matching a certain criteria.
ezcCacheStack::countDataItems() Counts how many items are stored, fulfilling certain criteria.

delete

void delete( [string $id = null], [array(string=>string) $attributes = array()], [bool $search = false] )
Delete data from the cache.
Purges the cached data for a given ID and or attributes. Using an ID purges only the cache data for just this ID.
Additional attributes provided will matched additionally. This can give you an immense speed improvement against just searching for ID ( see ezcCacheStorage::restore() ).
If you only provide attributes for deletion of cache data, all cache data matching these attributes will be purged.

Parameters

Name Type Description
$id string The item ID.
$attributes array(string=>string) Attributes that describe the cached data.
$search bool Whether to search for items if not found directly. Default is false.

Throws

ClassDescription
ezcBaseFilePermissionException If an already existsing cache file could not be unlinked. This exception means most likely that your cache directory has been corrupted by external influences (file permission change).

Redefined in descendants as

Method Description
ezcCacheStorageMemory::delete() Deletes the data associated with $id or $attributes from the cache.
ezcCacheStorageFileApcArray::delete() Deletes the data associated with $id or $attributes from the cache.
ezcCacheStorageFile::delete() Delete data from the cache.
ezcCacheStack::delete() Deletes an item from the stack.

getLocation

string getLocation( )
Returns the location.
Returns the location the current storage resides in. The $location attribute has no setter, since it can only be set during construction.

getOptions

ezcCacheStorageOptions getOptions( )
Return the currently set options.
Return the currently set options. The options are returned on an array that has the same format as the one passed to ezcCacheStorage::setOptions(). The possible options for a storage depend on its implementation.

getRemainingLifetime

int getRemainingLifetime( string $id, [array(string=>string) $attributes = array()] )
Returns the time ( in seconds ) that remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exist, this method returns 0.

Parameters

Name Type Description
$id string The item ID.
$attributes array(string=>string) Attributes that describe the

Redefined in descendants as

Method Description
ezcCacheStorageMemory::getRemainingLifetime() Returns the time in seconds which remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exists, this method returns 0.
ezcCacheStorageFile::getRemainingLifetime() Returns the time ( in seconds ) which remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exist, this method returns 0.
ezcCacheStack::getRemainingLifetime() Returns the remaining lifetime for the given item ID.

restore

mixed restore( string $id, [array(string=>string) $attributes = array()], [bool $search = false] )
Restore data from the cache.
Restores the data associated with the given cache and returns it. Please see ezcCacheStorage::store() for more detailed information of cachable datatypes.
During access to cached data the caches are automatically expired. This means, that the ezcCacheStorage object checks before returning the data if it's still actual. If the cache has expired, data will be deleted and false is returned.
You should always provide the attributes you assigned, although the cache storages must be able to find a cache ID even without them. BEWARE: Finding cache data only by ID can be much slower than finding it by ID and attributes.

Parameters

Name Type Description
$id string The item ID.
$attributes array(string=>string) Attributes that describe the cached data.
$search bool Whether to search for items if not found directly. Default is false.

Throws

ClassDescription
ezcBaseFilePermissionException If an already existsing cache file could not be unlinked. This exception means most likely that your cache directory has been corrupted by external influences (file permission change).

Redefined in descendants as

Method Description
ezcCacheStorageMemory::restore() Restores the data from the cache.
ezcCacheStorageFileApcArray::restore() Restores the data from the cache.
ezcCacheStorageFile::restore() Restore data from the cache.
ezcCacheStack::restore() Restores an item from the stack.

setOptions

void setOptions( ezcCacheStorageOptions $options )
Set new options.
This method allows you to change the options of a cache storage. Change of options take effect directly after this method has been called. The available options depend on the ezcCacheStorage implementation. All implementations have to offer the following options:
  • ttl The time-to-life. After this time span, a cache item becomes invalid and will be purged. The ezcCacheStorage::restore() method will then return false.
  • extension The "extension" for your cache items. This is usually the file name extension, when you deal with file system based caches or e.g. a database ID extension.

Parameters

Name Type Description
$options ezcCacheStorageOptions The options to set.

Throws

ClassDescription
ezcBasePropertyNotFoundException If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and may vary.
ezcBaseValueException If the value is not valid for the desired option.
ezcBaseValueException If you submit neither an array nor an instance of ezcCacheStorageOptions.

Redefined in descendants as

Method Description
ezcCacheStorageMemcache::setOptions() Set new options.
ezcCacheStorageApc::setOptions() Return the currently set options.
ezcCacheStorageFile::setOptions() Set new options.
ezcCacheStack::setOptions() Sets the options for this stack instance.

store

string store( string $id, mixed $data, [array(string=>string) $attributes = array()] )
Store data to the cache storage.
This method stores the given cache data into the cache, assigning the ID given to it.
The type of cache data which is expected by a ezcCacheStorage depends on its implementation. In most cases strings and arrays will be accepted, in some rare cases only strings might be accepted.
Using attributes you can describe your cache data further. This allows you to deal with multiple cache data at once later. Some ezcCacheStorage implementations also use the attributes for storage purposes. Attributes form some kind of "extended ID".

Parameters

Name Type Description
$id string The item ID.
$data mixed The data to store.
$attributes array(string=>string) Attributes that describe the cached data.

Throws

ClassDescription
ezcBaseFilePermissionException If an already existsing cache file could not be unlinked to store the new data (may occur, when a cache item's TTL has expired and the file should be stored with more actual data). This exception means most likely that your cache directory has been corrupted by external influences (file permission change).
ezcBaseFilePermissionException If the directory to store the cache file could not be created. This exception means most likely that your cache directory has been corrupted by external influences (file permission change).
ezcBaseFileIoException If an error occured while writing the data to the cache. If this exception occurs, a serious error occured and your storage might be corruped (e.g. broken network connection, file system broken, ...).
ezcCacheInvalidDataException If the data submitted can not be handled by the implementation of ezcCacheStorage. Most implementations can not handle objects and resources.

Redefined in descendants as

Method Description
ezcCacheStorageMemory::store() Stores data to the cache storage under the key $id.
ezcCacheStorageFileApcArray::store() Stores data to the cache storage.
ezcCacheStorageFile::store() Store data to the cache storage.
ezcCacheStack::store() Stores data in the cache stack.

validateLocation

void validateLocation( )
Checks if the location property is valid.

Redefined in descendants as

Method Description
ezcCacheStorageMemory::validateLocation() Checks if the location property is valid.
ezcCacheStorageFileApcArray::validateLocation() Checks the path in the location property exists, and is read-/writable. It throws an exception if not.
ezcCacheStorageFile::validateLocation() Checks the path in the location property exists, and is read-/writable. It throws an exception if not.
ezcCacheStack::validateLocation() Validates the $location parameter of the constructor.

Last updated: Tue, 26 May 2009