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:
Source for this file: /Cache/src/storage/file.php
ezcCacheStorage | --ezcCacheStorageFile
Version: | //autogentag// |
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 |
protected resource(file) |
$lockResource
= false
Resource used for the lock file. |
From ezcCacheStorage | |
---|---|
protected |
ezcCacheStorage::$properties
|
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. |
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. |
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.
Name | Type | Description |
---|---|---|
$location |
string | Path to the cache location |
$options |
array(string=>string) | Options for the cache. |
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. |
Method | Description |
---|---|
ezcCacheStorage::__construct() |
Creates a new cache storage in the given location. |
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.
Name | Type | Description |
---|---|---|
$file |
string | The file to calculate the remaining lifetime for. |
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.
Name | Type | Description |
---|---|---|
$id |
string | The item ID. |
$attributes |
array(string=>string) | Attributes describing the data to restore. |
Method | Description |
---|---|
ezcCacheStorage::countDataItems() |
Return the number of items in the cache matching a certain criteria. |
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.
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. |
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). |
Method | Description |
---|---|
ezcCacheStorage::delete() |
Delete data from the cache. |
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 ).
Name | Type | Description |
---|---|---|
$filename |
string | The file to fetch data from. |
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. |
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.
Name | Type | Description |
---|---|---|
$id |
string | The ID. |
$attributes |
array(string=>string) | Attributes describing the data to restore. |
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.
Name | Type | Description |
---|---|---|
$id |
string | The item ID. |
$attributes |
array(string=>string) | Attributes describing the data to restore. |
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. |
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.
Method | Description |
---|---|
ezcCacheStackMetaDataStorage::lock() |
Acquire a lock on the storage. |
Serialize the data for storing.
Serializes a PHP variable ( except type resource and object ) to a executable PHP code representation string.
Name | Type | Description |
---|---|---|
$data |
mixed | Simple type or array |
Type | Description |
---|---|
ezcCacheInvalidDataException |
If the data submitted can not be handled by the implementation of ezcCacheStorageFile. Most implementations can not handle objects and resources. |
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. |
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.
Name | Type | Description |
---|---|---|
$limit |
int |
Method | Description |
---|---|
ezcCacheStackableStorage::purge() |
Purge outdated data from the storage. |
Resets the whole storage.
Deletes all data in the storage including ezcCacheStackMetaData that was stored using storeMetaData().
Method | Description |
---|---|
ezcCacheStackableStorage::reset() |
Reset the complete storage. |
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.
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. |
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). |
Method | Description |
---|---|
ezcCacheStorage::restore() |
Restore data from the cache. |
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.
Method | Description |
---|---|
ezcCacheStackMetaDataStorage::restoreMetaData() |
Restores and returns the meta data struct. |
Method | Description |
---|---|
ezcCacheStorageFilePlain::restoreMetaData() |
Restores and returns the meta data struct. |
Search the storage for data.
Name | Type | Description |
---|---|---|
$id |
string | An item ID. |
$attributes |
array(string=>string) | Attributes describing the data to restore. |
Search the storage for data recursively.
Name | Type | Description |
---|---|---|
$pattern |
string | Pattern used with http://www.php.net/glob. |
$directory |
mixed | Directory to search in. |
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:
Name | Type | Description |
---|---|---|
$options |
ezcCacheStorageFileOptions | The options to set (accepts ezcCacheStorageOptions or array for compatibility reasons, too). |
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. |
Method | Description |
---|---|
ezcCacheStorage::setOptions() |
Set new options. |
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".
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. |
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, ...). |
Method | Description |
---|---|
ezcCacheStorage::store() |
Store data to the cache storage. |
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.
Name | Type | Description |
---|---|---|
$metaData |
ezcCacheStackMetaData |
Method | Description |
---|---|
ezcCacheStackMetaDataStorage::storeMetaData() |
Stores the given meta data struct. |
Method | Description |
---|---|
ezcCacheStorageFilePlain::storeMetaData() |
Stores the given meta data struct. |
Actually stores the given data.
Name | Type | Description |
---|---|---|
$filename |
string | |
$data |
string |
Type | Description |
---|---|
ezcBaseFileIoException |
if the store fails. |
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.
Method | Description |
---|---|
ezcCacheStackMetaDataStorage::unlock() |
Release a lock on the storage. |
Checks the path in the location property exists, and is read-/writable. It throws an exception if not.
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. |
Method | Description |
---|---|
ezcCacheStorage::validateLocation() |
Checks if the location property is valid. |