Path

ez components / documentation / api reference / 1.0.1 / cache

eZ Components 1.0.1

Cache: ezcCacheStorageFile

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

Class: 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. [source]
This class is a common base class for all file system based storage classes. To implement a file system based cache storage, you simply have to derive from this class and implement the ezcCacheStorageFile::fetchData() and ezcCacheStorageFile::prepareData() methods. Everything else is done for you by the ezcCacheStorageFile base class.
For example code of using a cache storage, see ezcCacheManager.
The Cache package already contains several implementations of ezcCacheStorageFile. As there are:
  • ezcCacheStorageFileArray
  • ezcCacheStorageFileEvalArray
  • ezcCacheStorageFilePlain

Parents

ezcCacheStorage
   |
   --ezcCacheStorageFile

Descendents

Child Class Description
ezcCacheStorageFilePlain This class implements a simple storage to cache plain text on the filesystem. It takes it's base methods from the extended storage base class ezcCacheStorageFile.
ezcCacheStorageFileEvalArray This cache storage implementation stores arrays and scalar values (int,
ezcCacheStorageFileArray This cache storage implementation stores arrays and scalar values

Inherited Member Variables

From ezcCacheStorage:
protected  ezcCacheStorage::$location
protected  ezcCacheStorage::$options

Method Summary

protected int calcLifetime( $file )
Calculates the lifetime remaining for a cache object.
public int countDataItems( [$id = null], [$attributes = array()] )
Return the number of items in the cache matching a certain criteria.
public void delete( [$id = null], [$attributes = array()] )
Delete data from the cache.
protected abstract mixed fetchData( $filename )
Fetch data from the cache.
public string generateIdentifier( $id, [$attributes = null] )
Generate the storage internal identifier from ID and attributes.
public int getRemainingLifetime( $id, [$attributes = array()] )
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.
protected abstract string prepareData( $data )
Serialize the data for storing.
public mixed|bool restore( $id, [$attributes = array()] )
Restore data from the cache.
public string store( $id, $data, [$attributes = array()] )
Store data to the cache storage.
protected void validateLocation( )
Checks if a given location is valid.

Inherited Methods

From ezcCacheStorage :
public ezcCacheStorage ezcCacheStorage::__construct()
Creates a new cache storage in the given location.
public abstract int ezcCacheStorage::countDataItems()
Return the number of items in the cache matching a certain criteria.
public abstract void ezcCacheStorage::delete()
Delete data from the cache.
public string ezcCacheStorage::getLocation()
Returns the location.
public array ezcCacheStorage::getOptions()
Return the currently set options.
public abstract int ezcCacheStorage::getRemainingLifetime()
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 exists, this method returns 0.
public abstract mixed ezcCacheStorage::restore()
Restore data from the cache.
public void ezcCacheStorage::setOptions()
Set new options.
public abstract string ezcCacheStorage::store()
Store data to the cache storage.

Methods

calcLifetime

int calcLifetime( string $file )
Calculates the lifetime remaining for a cache object.
This calculates the time a cached object stays valid and returns it.

Parameters

Name Type Description
$file string The file to calculate the remaining lifetime for.

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 describing the data to restore.

Redefinition of

Method Description
ezcCacheStorage::countDataItems() Return the number of items in the cache matching a certain criteria.

delete

void delete( [string $id = null], [array(string=>string) $attributes = array()] )
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 to purge.
$attributes array(string=>string) Attributes describing the data to restore.

Throws

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

Redefinition of

Method Description
ezcCacheStorage::delete() Delete data from the cache.

fetchData

mixed fetchData( string $filename )
Fetch data from the cache.
This method does the fetching of the data itself. In this case, the method simply includes the file and returns the value returned by the include ( or false on failure ).

Parameters

Name Type Description
$filename string The file to fetch data from.

Redefined in descendants as

Method Description
ezcCacheStorageFilePlain::fetchData() Fetch data from the cache.
ezcCacheStorageFileEvalArray::fetchData() Fetch data from a given file name.
ezcCacheStorageFileArray::fetchData() Fetch data from the cache.

generateIdentifier

string generateIdentifier( string $id, [array(string=>string) $attributes = null] )
Generate the storage internal identifier from ID and attributes.
Generates the storage internal identifier out of the provided ID and the attributes. This is the default implementation and can be overloaded if necessary.

Parameters

Name Type Description
$id string The ID.
$attributes array(string=>string) Attributes describing the data to restore.

getRemainingLifetime

int getRemainingLifetime( string $id, [array(string=>string) $attributes = array()] )
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.

Parameters

Name Type Description
$id string The item ID.
$attributes array(string=>string) Attributes describing the data to restore.

Redefinition of

Method Description
ezcCacheStorage::getRemainingLifetime() 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 exists, this method returns 0.

prepareData

string prepareData( mixed $data )
Serialize the data for storing.
Serializes a PHP variable ( except type resource and object ) to a executable PHP code representation string.

Parameters

Name Type Description
$data mixed Simple type or array

Throws

ClassDescription
ezcCacheInvalidDataException If the data submitted can not be handled by the implementation of ezcCacheStorageFile. Most implementations can not handle objects and resources.

Redefined in descendants as

Method Description
ezcCacheStorageFilePlain::prepareData() Serialize the data for storing.
ezcCacheStorageFileEvalArray::prepareData() Serialize the data for storing.
ezcCacheStorageFileArray::prepareData() Serialize the data for storing.

restore

mixed|bool restore( string $id, [array(string=>string) $attributes = array()] )
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 to restore.
$attributes array(string=>string) Attributes describing the data to restore.

Throws

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

Redefinition of

Method Description
ezcCacheStorage::restore() Restore data from the cache.

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 it's 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 Unique identifier for the data.
$data mixed The data to store.
$attributes array(string=>string) Attributes describing 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 diretory 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 diretory 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 ezcCacheStorageFile. Most implementations can not handle objects and resources.

Redefinition of

Method Description
ezcCacheStorage::store() Store data to the cache storage.

validateLocation

void validateLocation( )
Checks if a given location is valid.
Checks if the location exists and tries to create it, if not. Also checks if the location is read-/writable and throws an exception, if not.

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.

Last updated: Fri, 02 Nov 2007