Zeta Components - high quality PHP components

Tutorial
API

Zeta Components Manual :: Docs For Class ezcCacheStorageFile

Cache::ezcCacheStorageFile

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.

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

Source for this file: /Cache/src/storage/file.php

Implements interfaces:

ezcCacheStorage
   |
   --ezcCacheStorageFile

Version:

//autogentag//

Descendants

Child Class	Description
ezcCacheStorageFileEvalArray	This cache storage implementation stores arrays and scalar values (int,
ezcCacheStorageFileArray	This cache storage implementation stores arrays and scalar values
ezcCacheStorageFilePlain	This class implements a simple storage to cache plain text on the filesystem. It takes its base methods from the extended storage base class ezcCacheStorageFile.
ezcCacheStorageFileObject	This cache storage implementation stores arrays, 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 exist, 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 exist, 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.

Exceptions:

Type	Description
`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.
`ezcBasePropertyNotFoundException`	If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and may vary.
`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::__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	Whether to search for items if not found directly.

Exceptions:

Type	Description
`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).

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
`ezcCacheStorageFileEvalArray::fetchData()`	Fetch data from a given file name.
`ezcCacheStorageFileArray::fetchData()`	Fetch data from the cache.
`ezcCacheStorageFilePlain::fetchData()`	Fetch data from the cache.
`ezcCacheStorageFileObject::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 exist, 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 exist, 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.

Implementation of:

Method	Description
`ezcCacheStackMetaDataStorage::lock()`	Acquire a lock on the storage.

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

Exceptions:

Type	Description
`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
`ezcCacheStorageFileEvalArray::prepareData()`	Serialize the data for storing.
`ezcCacheStorageFileArray::prepareData()`	Serialize the data for storing.
`ezcCacheStorageFilePlain::prepareData()`	Serialize the data for storing.
`ezcCacheStorageFileObject::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

Implementation of:

Method	Description
`ezcCacheStackableStorage::purge()`	Purge outdated data from the storage.

reset

void reset( )

Resets the whole storage.

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

Implementation of:

Method	Description
`ezcCacheStackableStorage::reset()`	Reset the complete storage.

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	Whether to search for items if not found directly.

Exceptions:

Type	Description
`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).

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.

Implementation of:

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

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).

Exceptions:

Type	Description
`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 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 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	Unique identifier for the data.
`$data`	mixed	The data to store.
`$attributes`	array(string=>string)	Attributes describing the cached data.

Exceptions:

Type	Description
`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).
`ezcCacheInvalidDataException`	If the data submitted can not be handled by the implementation of ezcCacheStorageFile. Most implementations can not handle objects and resources.
`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, ...).

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

Implementation of:

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

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

Exceptions:

Type	Description
`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.

Implementation of:

Method	Description
`ezcCacheStackMetaDataStorage::unlock()`	Release a lock on the storage.

validateLocation

void validateLocation( )

Checks the path in the location property exists, and is read-/writable. It throws an exception if not.

Exceptions:

Type	Description
`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.

Documentation generated by phpDocumentor 1.4.3