Path

ez components / documentation / api reference / trunk / cache

eZ Components trunk

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]

Implemented Interfaces

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

Member Variables

protected resource(file) $lockResource = false
Resource used for the lock file.

Inherited Member Variables

From ezcCacheStorage:
protected  ezcCacheStorage::$properties

Method Summary

public ezcCacheStorageFile __construct( $location, [$options = array()] )
Creates a new cache storage in the given location.
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()], [$search = false] )
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.
public void lock( )
Acquire a lock on the storage.
protected abstract string prepareData( $data )
Serialize the data for storing.
public array(string) purge( [$limit = null] )
Purges the given number of cache items.
public void reset( )
Resets the whole storage.
public mixed|bool restore( $id, [$attributes = array()], [$search = false] )
Restore data from the cache.
public ezcCacheStackMetaData|null restoreMetaData( )
Restores and returns the meta data struct.
protected array(int=>string) search( [$id = null], [$attributes = array()] )
Search the storage for data.
protected array(int=>string) searchRecursive( $pattern, $directory )
Search the storage for data recursively.
public void setOptions( $options )
Set new options.
public string store( $id, $data, [$attributes = array()] )
Store data to the cache storage.
public void storeMetaData( $metaData )
Stores the given meta data struct.
protected void storeRawData( $filename, $data )
Actually stores the given data.
public void unlock( )
Release a lock on the storage.
protected void validateLocation( )
Checks the path in the location property exists, and is read-/writable. It throws an exception if not.

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 ezcCacheStorageOptions 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.
protected abstract void ezcCacheStorage::validateLocation()
Checks if the location property is valid.

Methods

__construct

ezcCacheStorageFile __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 in case of this storage class is a valid file system directory.
Options can contain the 'ttl' ( Time-To-Life ). This is per default set to 1 day. The option 'permissions' can be used to define the file permissions of created cache items. Specific ezcCacheStorageFile implementations can have additional options.
For details about the options see ezcCacheStorageFileOptions.

Parameters

Name Type Description
$location string Path to the cache location
$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 accpeted options depend on th ezcCacheStorage implementation and my vary.

Redefinition of

Method Description
ezcCacheStorage::__construct() Creates a new cache storage in the given location.

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. In case the TTL is set to false, this method always returns a value of 1.

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()], [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 to purge.
$attributes array(string=>string) Attributes describing the data to restore.
$search bool Wheather to search for items if not found directly.

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.

lock

void lock( )
Acquire a lock on the storage.
This method acquires a lock on the storage. If locked, the storage must block all other method calls until the lock is freed again using ezcCacheStackMetaDataStorage::unlock(). Methods that are called within the request that successfully acquired the lock must succeed as usual.

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.

purge

array(string) purge( [int $limit = null] )
Purges the given number of cache items.
This method minimally purges the $limit number of outdated cache items from the storage. If limit is left out, all outdated items are purged. The purged item IDs are returned.

Parameters

Name Type Description
$limit int  

reset

void reset( )
Resets the whole storage.
Deletes all data in the storage including ezcCacheStackMetaData that was stored using storeMetaData().

restore

mixed|bool 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.
Note that with the ezcCacheStorageFilePlain all restored data will be of type string. If you expect a different data type you need to perform a cast after restoring.

Parameters

Name Type Description
$id string The item ID to restore.
$attributes array(string=>string) Attributes describing the data to restore.
$search bool Wheather to search for items if not found directly.

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.

restoreMetaData

ezcCacheStackMetaData|null restoreMetaData( )
Restores and returns the meta data struct.
This method fetches the meta data stored in the storage and returns the according struct of type ezcCacheStackMetaData. The meta data must be stored inside the storage, but should not be visible as normal cache items to the user.

Redefined in descendants as

Method Description
ezcCacheStorageFilePlain::restoreMetaData() Restores and returns the meta data struct.

search

array(int=>string) search( [string $id = null], [array(string=>string) $attributes = array()] )
Search the storage for data.

Parameters

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

searchRecursive

array(int=>string) searchRecursive( string $pattern, mixed $directory )
Search the storage for data recursively.

Parameters

Name Type Description
$pattern string Pattern used with http://www.php.net/glob.
$directory mixed Directory to search in.

setOptions

void setOptions( ezcCacheStorageFileOptions $options )
Set new options.
This method allows you to change the options of a cache file storage. Change of options take effect directly after this method has been called. The available options depend on the ezcCacheStorageFile 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.
  • permissions The file permissions to set for new files.
The usage of ezcCacheStorageOptions and arrays for setting options is deprecated, but still supported. You should migrate to ezcCacheStorageFileOptions.

Parameters

Name Type Description
$options ezcCacheStorageFileOptions The options to set (accepts ezcCacheStorageOptions or array for compatibility reasons, too).

Throws

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

Redefinition of

Method Description
ezcCacheStorage::setOptions() Set new options.

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.

storeMetaData

void storeMetaData( ezcCacheStackMetaData $metaData )
Stores the given meta data struct.
This method stores the given $metaData inside the storage. The data must be stored with the same mechanism that the storage itself uses. However, it should not be stored as a normal cache item, if possible, to avoid accedental user manipulation.

Parameters

Name Type Description
$metaData ezcCacheStackMetaData  

Redefined in descendants as

Method Description
ezcCacheStorageFilePlain::storeMetaData() Stores the given meta data struct.

storeRawData

void storeRawData( string $filename, string $data )
Actually stores the given data.

Parameters

Name Type Description
$filename string  
$data string  

Throws

ClassDescription
ezcBaseFileIoException if the store fails.

unlock

void unlock( )
Release a lock on the storage.
This method releases the lock of the storage, that has been acquired via ezcCacheStackMetaDataStorage::lock(). After this method has been called, blocked method calls (including calls to lock()) can suceed again.

validateLocation

void validateLocation( )
Checks the path in the location property exists, and is read-/writable. It 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.

Redefinition of

Method Description
ezcCacheStorage::validateLocation() Checks if the location property is valid.

Last updated: Mon, 10 Nov 2008