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

- ezcCacheStorageFileArray
- ezcCacheStorageFileEvalArray
- ezcCacheStorageFilePlain

Implementations of ezcCacheStorageMemory:

- ezcCacheStorageMemcachePlain
- ezcCacheStorageApcPlain
- ezcCacheStorageFileApcArray

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