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. [
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 harddisc, 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 Cache package already contains several implementations of
ezcCacheStorageFile. As there are:
- ezcCacheStorageFileArray
- ezcCacheStorageFileEvalArray
- ezcCacheStorageFilePlain
Descendents
| Child Class |
Description |
| 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.
|
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 )
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 exists, this method returns 0. |
|
public abstract mixed |
restore(
$id, [$attributes = array()], $search )
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. |
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.
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 |
$options |
array(string=>string) |
Options for the cache. |
Throws
| Class | 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. |
ezcBasePropertyNotFoundException |
If you tried to set a non-existent option value. The accpeted options depend on th ezcCacheStorage implementation and my vary. |
Redefined in descendants as
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 |
Redefined in descendants as
delete
void delete(
[string
$id = null], [array(string=>string)
$attributes = array()], bool
$search )
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 |
Wheather to search for items if not found directly. |
Throws
| Class | Description |
|---|
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). |
Redefined in descendants as
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
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 it's 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 exists, 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 |
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 exists, this method returns 0. |
restore
mixed restore(
string
$id, [array(string=>string)
$attributes = array()], bool
$search )
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 |
Wheather to search for items if not found directly. |
Throws
| Class | Description |
|---|
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). |
Redefined in descendants as
setOptions
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
Throws
| Class | Description |
|---|
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 array nor an instance of ezcCacheStorageOptions. |
Redefined in descendants as
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 |
The item ID. |
$data |
mixed |
The data to store. |
$attributes |
array(string=>string) |
Attributes that describe the cached data. |
Throws
| Class | 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 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 ezcCacheStorage. Most implementations can not handle objects and resources. |
Redefined in descendants as
Last updated: Wed, 28 Nov 2007
