Zeta Components - high quality PHP components

Tutorial
API

Zeta Components Manual :: Docs For Class ezcCacheStorage

Cache::ezcCacheStorage

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.

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:

Implementations of ezcCacheStorageMemory:

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

Version:

//autogentag//

Descendants

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.

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.

Redefined in descendants as:

Method	Description
`ezcCacheStorageMemory::__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.
`ezcCacheStorageMemcache::__construct()`	Creates a new cache storage in the given location.
`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.

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

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.

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

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.

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 array nor an instance of ezcCacheStorageOptions.

Redefined in descendants as:

Method	Description
`ezcCacheStorageApc::setOptions()`	Return the currently set options.
`ezcCacheStorageMemcache::setOptions()`	Set new 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.

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

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.

Documentation generated by phpDocumentor 1.4.3