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 is is found it. 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.

ezcCacheStorage
   |
   --ezcCacheStack

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.

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.

Returns the number of storages on the stack.

Returns the number of storages currently on the stack.

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.

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.

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.

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.

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.

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.

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.

Sets the options for this stack instance.

Overwrites the parent implementation to only allow instances of ezcCacheStackOptions.

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.

Validates the $location parameter of the constructor.

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