## Apache Zeta Components Manual :: Docs For Class ezcCacheStack

### Cache::ezcCacheStack

### Class ezcCacheStack

Hierarchical caching class using multiple storages.

An instance of this class can be used to achieve so called "hierarchical caching". A cache stack consists of an arbitrary number of cache storages, being sorted from top to bottom. Usually this order reflects the speed of access for the caches: The fastest cache is at the top, the slowest at the bottom. Whenever data is stored in the stack, it is stored in all contained storages. When data is to be restored, the stack will restore it from the highest storage it is found in. Data is removed from a storage, whenever the storage reached a configured number of items, using a ezcCacheStackReplacementStrategy.

To create a cache stack, multiple storages are necessary. The following examples assume that $storage1, $storage2 and $storage3 contain objects that implement the ezcCacheStackableStorage interface.

The slowest cache should be at the very bottom of the stack, so that items don't need to be restored from it that frequently.

1. <?php
2. $stack=new ezcCacheStack ('stack_id');
3. $stack-> pushStorage (
4. new ezcCacheStackStorageConfiguration (
5. 'filesystem_cache',
6. $storage1,
7. 1000000,
8. .5
9. )
10. );
11. ?>

This operations create a new cache stack and add $storage1 to its very bottom. The first parameter for {@linke ezcCacheStackStorageConfiguration} are a unique ID for the storage inside the stack, which should never change. The second parameter is the storage object itself. Parameter 3 is the maximum number of items the storage might contain. As soon as this limit ist reached, 500000 items will be purged from the cache. The latter number is defined through the fourth parameter, indicating the fraction of the stored item number, that is to be freed. For freeing, first already outdated items will be purged. If this does not last, more items will be freed using the ezcCacheStackReplacementStrategy used by the stack.

The following code adds the other 2 storages to the stack, where $storage2 is a memory storage ezcCacheStackMemoryStorage and $storage3 is a custom storage implementation, that stores objects in the current requests memory.

1. <?php
2. $stack-> pushStorage (
3. new ezcCacheStackStorageConfiguration (
4. 'apc_storage',
5. $storage2,
6. 10000,
7. .8
8. )
9. );
10. $stack-> pushStorage (
11. new ezcCacheStackStorageConfiguration (
12. 'custom_storage',
13. $storage3,
14. 50,
15. .3
16. )
17. );
18. ?>

The second level of the cache build by $storage2. This storage will contain 10000 items maximum and when it runs full, 8000 items will be deleted from it. The top level of the cache is the custom cache storage, that will only contain 50 objects in the currently processed request. If this storage ever runs full, which should not happen within a request, 15 items will be removed from it.

Since the top most storage in this example does not implement ezcCacheStackMetaDataStorage, another storage must be defined to be used for storing meta data about the stack:

1. <?php
2. $stack->options->metaStorage=$storage2;
3. $stack->options->replacementStrategy='ezcCacheStackLfuReplacementStrategy';
4. ?>

$storage2 is defined to store the meta information for the stack. In addition, a different replacement strategy than the default ezcCacheStackLruReplacementStrategy replacement strategy is defined. LFU removes least frequently used items, while LRU deletes least recently used items from a storage, if it runs full.

Using the $bubbleUpOnRestore option you can determine, that data which is restored from a lower storage will be automatically stored in all higher storages again. The problem with this is, that only the attributes that are used for restoring will be assigned to the item in higher storages. In addition, the items will be stored with a fresh TTL. Therefore, this behavior is not recommended.

If you want to use a cache stack in combination with {@ezcCacheManager}, you will most likely want to use ezcCacheStackConfigurator. This allows you to let the stack be configured on the fly, when it is used for the first time in a request.

Beware, that whenever you change the structure of your stack or the replacement strategy between 2 requests, you should always perform a complete ezcCacheStack::reset() on it. Otherwise, your cache data might be seriously broken which will result in undefined behaviour of the stack. Changing the replacement strategy will most possibly result in an ezcCacheInvalidMetaDataException.

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

    ezcCacheStorage
       |
       --ezcCacheStack

Version: | //autogentag//

### Properties

string | read/write | `$location` Location of this stack. Unused.
ezcCacheStackOptions | read/write | `$options` Options for the cache stack.

### Inherited Member Variables

From ezcCacheStorage
protected | `ezcCacheStorage::$properties`

### Method Summary

public ezcCacheStack | `__construct( $location , [ $options = null] )` Creates a new cache stack.
public int | `countDataItems( [ $id = null] , [ $attributes = array()] )` Counts how many items are stored, fulfilling certain criteria.
public int | `countStorages( )` Returns the number of storages on the stack.
public array(string) | `delete( [ $id = null] , [ $attributes = array()] , [ $search = false] )` Deletes an item from the stack.
public int | `getRemainingLifetime( $id , [ $attributes = array()] )` Returns the remaining lifetime for the given item ID.
public array(ezcCacheStackableStorage) | `getStorages( )` Returns all stacked storages.
public ezcCacheStackStorageConfiguration | `popStorage( )` Removes a storage from the top of the stack.
public void | `pushStorage( $storageConf )` Add a storage to the top of the stack.
public void | `reset( )` Resets the complete stack.
public mixed | `restore( $id , [ $attributes = array()] , [ $search = false] )` Restores an item from the stack.
public void | `setOptions( $options )` Sets the options for this stack instance.
public void | `store( $id , $data , [ $attributes = array()] )` Stores data in the cache stack.
protected bool | `validateLocation( )` Validates the $location parameter of the constructor.

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

ezcCacheStack __construct( string $location , [ezcCacheStackOptions $options = null] )

Creates a new cache stack.

Usually you will want to use the ezcCacheManager to take care of your caches. The $options (ezcCacheStackOptions) stored in the manager and given here can contain a class reference to an implementation of ezcCacheStackConfigurator that will be used to initially configure the stack instance directly after construction.

To perform manual configuration of the stack the ezcCacheStack::pushStorage() and ezcCacheStack::popStorage() methods can be used.

The location can be a free form string that identifies the stack uniquely in the ezcCacheManager. It is currently not used internally in the stack.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$location` | string |
`$options` | ezcCacheStackOptions |

##### Redefinition of:

Method | Description
--- | ---
`ezcCacheStorage::__construct()` | Creates a new cache storage in the given location.

#### countDataItems

int countDataItems( [string $id = null] , [array $attributes = array()] )

Counts how many items are stored, fulfilling certain criteria.

This method counts how many data items fulfilling the given criteria are stored overall. Note: The items of all contained storages are counted independantly and summarized.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$id` | string |
`$attributes` | array |

##### Redefinition of:

Method | Description
--- | ---
`ezcCacheStorage::countDataItems()` | Return the number of items in the cache matching a certain criteria.

#### countStorages

int countStorages( )

Returns the number of storages on the stack.

Returns the number of storages currently on the stack.

#### delete

array(string) delete( [string $id = null] , [array $attributes = array()] , [bool $search = false] )

Deletes an item from the stack.

This method deletes an item from the cache stack. The item will afterwards no more be stored in any of the inner cache storages. Giving the ID of the cache item will delete exactly 1 desired item. Giving an attribute array, describing the desired item in more detail, can speed up the deletion in some caches.

Giving null as the ID and just an attribibute array, with the $search attribute in addition, will delete *all* items that comply to the attributes from all storages. This might be much slower than just deleting a single item.

Deleting items from a cache stack is not recommended at all. Instead, items should expire on their own or be overwritten with more actual data.

The method returns an array containing all deleted item IDs.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$id` | string |
`$attributes` | array |
`$search` | bool |

##### Redefinition of:

Method | Description
--- | ---
`ezcCacheStorage::delete()` | Delete data from the cache.

#### getRemainingLifetime

int getRemainingLifetime( string $id , [array $attributes = array()] )

Returns the remaining lifetime for the given item ID.

This method returns the lifetime in seconds for the item identified by $item and optionally described by $attributes. Definining the $attributes might lead to faster results with some caches.

The first internal storage that is found for the data item is chosen to detemine the lifetime. If no storage contains the item or the item is outdated in all found caches, 0 is returned.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$id` | string |
`$attributes` | array |

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

#### getStorages

array(ezcCacheStackableStorage) getStorages( )

Returns all stacked storages.

This method returns the whole stack of ezcCacheStackableStorage as an array. This maybe useful to adjust options of the storages after they have been added to the stack. However, it is not recommended to perform any drastical changes to the configurations. Performing manual stores, restores and deletes on the storages is *highly discouraged*, since it may lead to irrepairable inconsistencies of the stack.

#### popStorage

ezcCacheStackStorageConfiguration popStorage( )

Removes a storage from the top of the stack.

This method can be used to remove the top most ezcCacheStackableStorage from the stack. This is commonly done to remove caches or to insert new ones into lower positions. In both cases, it is recommended to ezcCacheStack::reset() the whole cache afterwards to avoid any kind of inconsistency.

##### Exceptions:

Type | Description
--- | ---
`ezcCacheStackUnderflowException` | if called on an empty stack.

#### pushStorage

void pushStorage( ezcCacheStackStorageConfiguration $storageConf )

Add a storage to the top of the stack.

This method is used to add a new storage to the top of the cache. The $storageConf of type ezcCacheStackStorageConfiguration consists of the actual ezcCacheStackableStorage and other information.

Most importantly, the configuration object contains an ID, which must be unique within the whole storage. The itemLimit setting determines how many items might be stored in the storage at all. freeRate determines which fraction of itemLimit will be freed by the ezcCacheStackStackReplacementStrategy of the stack, when the storage runs full.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$storageConf` | ezcCacheStackStorageConfiguration |

#### reset

void reset( )

Resets the complete stack.

This method is used to reset the complete stack of storages. It will reset all storages, using ezcCacheStackableStorage::reset(), and therefore purge the complete content of the stack. In addition, it will kill the complete meta data.

The stack is in a consistent, but empty, state afterwards.

#### restore

mixed restore( string $id , [array $attributes = array()] , [bool $search = false] )

Restores an item from the stack.

This method tries to restore an item from the cache stack and returns the found data, if any. If no data is found, boolean false is returned. Given the ID of an object will restore exactly the desired object. If additional $attributes are given, this may speed up the restore process for some caches. If only attributes are given, the $search parameter makes sense, since it will instruct the inner cach storages to search their content for the given attribute combination and will restore the first item found. However, this process is much slower then restoring with an ID and therefore is not recommended.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$id` | string |
`$attributes` | array |
`$search` | bool |

##### Redefinition of:

Method | Description
--- | ---
`ezcCacheStorage::restore()` | Restore data from the cache.

#### setOptions

void setOptions( ezcCacheStackOptions $options )

Sets the options for this stack instance.

Overwrites the parent implementation to only allow instances of ezcCacheStackOptions.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$options` | ezcCacheStackOptions |

##### Redefinition of:

Method | Description
--- | ---
`ezcCacheStorage::setOptions()` | Set new options.

#### store

void store( string $id , mixed $data , [array $attributes = array()] )

Stores data in the cache stack.

This method will store the given data across the complete stack. It can afterwards be restored using the ezcCacheStack::restore() method and be deleted through the ezcCacheStack::delete() method.

The data that can be stored in the cache depends on the configured storages. Usually it is save to store arrays and scalars. However, some caches support objects or do not even support arrays. You need to make sure that the inner caches of the stack *all* support the data you want to store!

The $attributes array is optional and can be used to describe the stack further.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$id` | string |
`$data` | mixed |
`$attributes` | array |

##### Redefinition of:

Method | Description
--- | ---
`ezcCacheStorage::store()` | Store data to the cache storage.

#### validateLocation

bool validateLocation( )

Validates the $location parameter of the constructor.

Returns true, since $location is not necessary for this storage.

##### Redefinition of:

Method | Description
--- | ---
`ezcCacheStorage::validateLocation()` | Checks if the location property is valid.

Documentation generated by phpDocumentor 1.4.3