Apache Zeta Components - high quality PHP components

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

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

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

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.

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.

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 currently on 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.

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.

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.

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.

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.

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.

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.

Overwrites the parent implementation to only allow instances of ezcCacheStackOptions.

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.

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