## Apache 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:

- ezcCacheStackableStorage
- ezcCacheStackMetaDataStorage

    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