Zeta Components - high quality PHP components

Tutorial
API

Zeta Components Manual :: Docs For Class ezcCacheStorageMemory

Cache::ezcCacheStorageMemory

Class ezcCacheStorageMemory

Base abstract class for all memory storage classes.

Abstract classes extending this class:

Implementations derived from this class and its descendants:

Source for this file: /Cache/src/storage/memory.php

Implements interfaces:

ezcCacheStorage
   |
   --ezcCacheStorageMemory

Version:

//autogentag//

Descendants

Child Class	Description
ezcCacheStorageApc	This class is a common base class for all APC based storage classes.
ezcCacheStorageMemcache	This class is a common base class for all Memcache based storage classes.

Member Variables

protected ezcCacheMemoryBackend	`$backend` Holds the memory backend object which communicates with the memory handler (Memcache, APC).
protected string	`$backendName` Holds the name of the memory backend.
protected array(mixed)	`$registry = array()` Holds the registry.
protected string	`$registryName` Holds the name of the registry.
protected array(mixed)	`$searchRegistry = array()` Holds the search registry.

Inherited Member Variables

From ezcCacheStorage
protected	`ezcCacheStorage::$properties`

Method Summary

public ezcCacheStorageMemory	`__construct( $location , [ $options = array()] )` Creates a new cache storage in the given location.
protected int	`calcLifetime( $identifier , [ $dataObject = false] )` Calculates the lifetime remaining for a cache object.
public int	`countDataItems( [ $id = null] , [ $attributes = array()] )` Returns the number of items in the cache matching a certain criteria.
public void	`delete( [ $id = null] , [ $attributes = array()] , [ $search = false] )` Deletes the data associated with $id or $attributes from the cache.
protected void	`fetchSearchRegistry( [ $requireFresh = false] )` Fetches the search registry from the backend or creates it if empty.
protected string	`generateAttrStr( [ $attributes = array()] )` Generates a string from the $attributes array.
public string	`generateIdentifier( $id , [ $attributes = null] )` Generates 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 exists, this method returns 0.
public void	`lock( )` Acquire a lock on the storage.
public array(string)	`purge( [ $limit = null] )` Purge outdated data from the storage.
protected void	`registerIdentifier( [ $id = null] , [ $attributes = array()] , [ $identifier = null] )` Registers an identifier to facilitate searching.
public void	`reset( )` Reset the complete storage.
public mixed	`restore( $id , [ $attributes = array()] , [ $search = false] )` Restores the data from the cache.
public ezcCacheStackMetaData	`restoreMetaData( )` Restores and returns the meta data struct.
protected array(mixed)	`search( [ $id = null] , [ $attributes = array()] )` Searches the storage for data defined by ID and/or attributes.
public string	`store( $id , $data , [ $attributes = array()] )` Stores data to the cache storage under the key $id.
public void	`storeMetaData( $metaData )` Stores the given meta data struct.
protected void	`storeSearchRegistry( )` Stores the search registry in the backend.
public void	`unlock( )` Release a lock on the storage.
protected void	`unRegisterIdentifier( [ $id = null] , [ $attributes = array()] , [ $identifier = null] , [ $delayStore = false] )` Un-registers a previously registered identifier.
protected void	`validateLocation( )` Checks if the location property is valid.

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

ezcCacheStorageMemory __construct( string $location , [ $options = array()] )

Creates a new cache storage in the given location.

Options can contain the 'ttl' (Time-To-Live). Specific 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
`ezcBasePropertyNotFoundException`	If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and may vary.

Redefinition of:

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

Redefined in descendants as:

Method	Description
`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.

calcLifetime

int calcLifetime( string $identifier , [bool $dataObject = false] )

Calculates the lifetime remaining for a cache object.

In case the TTL options is set to true, this method always returns 1.

Parameters:

Name	Type	Description
`$identifier`	string	The memcache identifier
`$dataObject`	bool	The optional data object for which to calculate the lifetime

Redefined in descendants as:

Method	Description
`ezcCacheStorageFileApcArray::calcLifetime()`	Calculates the lifetime remaining for a cache object.

countDataItems

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

Returns 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

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] )

Deletes the data associated with $id or $attributes from the cache.

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.

Redefined in descendants as:

Method	Description
`ezcCacheStorageFileApcArray::delete()`	Deletes the data associated with $id or $attributes from the cache.

fetchSearchRegistry

void fetchSearchRegistry( [bool $requireFresh = false] )

Fetches the search registry from the backend or creates it if empty.

Parameters:

Name	Type	Description
`$requireFresh`	bool	To create a new search registry or not

generateAttrStr

string generateAttrStr( [array(string=>string) $attributes = array()] )

Generates a string from the $attributes array.

Parameters:

Name	Type	Description
`$attributes`	array(string=>string)	Attributes describing the data

generateIdentifier

string generateIdentifier( string $id , [array(string=>string) $attributes = null] )

Generates the storage internal identifier from ID and attributes.

Parameters:

Name	Type	Description
`$id`	string	The ID
`$attributes`	array(string=>string)	Attributes describing the data

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 exists, this method returns 0.

Parameters:

Name	Type	Description
`$id`	string	The item ID
`$attributes`	array(string=>string)	Attributes describing the data

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.

purge

array(string) purge( [int $limit = null] )

Purge outdated data from the storage.

This method purges outdated data from the cache. If $limit is given, a maximum of $limit items is purged. Otherwise all outdated items are purged. The method returns an array containing the IDs of all cache items that have been purged.

Parameters:

Name	Type	Description
`$limit`	int

Implementation of:

Method	Description
`ezcCacheStackableStorage::purge()`	Purge outdated data from the storage.

registerIdentifier

void registerIdentifier( [string $id = null] , [array $attributes = array()] , [string $identifier = null] )

Registers an identifier to facilitate searching.

Parameters:

Name	Type	Description
`$id`	string	ID for the cache item
`$attributes`	array	Attributes for the cache item
`$identifier`	string	Identifier generated for the cache item

reset

void reset( )

Reset the complete storage.

This method resets the complete cache storage. All content (including content stored with the ezcCacheStackMetaDataStorage interfacer) must be deleted and the cache storage must appear as if it has just newly been created.

Implementation of:

Method	Description
`ezcCacheStackableStorage::reset()`	Reset the complete storage.

restore

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

Restores the data from the cache.

During access to cached data the caches are automatically expired. This means, that the ezcCacheStorageMemory 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 to restore
`$attributes`	array(string=>string)	Attributes describing the data to restore
`$search`	bool	Whether to search for items if not found directly

Redefinition of:

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

Redefined in descendants as:

Method	Description
`ezcCacheStorageFileApcArray::restore()`	Restores the data from the cache.

restoreMetaData

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

search

array(mixed) search( [string $id = null] , [array(string=>string) $attributes = array()] )

Searches the storage for data defined by ID and/or attributes.

Parameters:

Name	Type	Description
`$id`	string	The item ID
`$attributes`	array(string=>string)	Attributes describing the data

store

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

Stores data to the cache storage under the key $id.

The type of cache data which is expected by an ezcCacheStorageMemory implementation depends on the backend. 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 ezcCacheStorageMemory 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

Redefinition of:

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

Redefined in descendants as:

Method	Description
`ezcCacheStorageFileApcArray::store()`	Stores 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.

storeSearchRegistry

void storeSearchRegistry( )

Stores the search registry in the backend.

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.

unRegisterIdentifier

void unRegisterIdentifier( [string $id = null] , [array $attributes = array()] , [string $identifier = null] , [bool $delayStore = false] )

Un-registers a previously registered identifier.

Parameters:

Name	Type	Description
`$id`	string	ID for the cache item
`$attributes`	array	Attributes for the cache item
`$identifier`	string	Identifier generated for the cache item
`$delayStore`	bool	Delays the storing of the updated search registry

validateLocation

void validateLocation( )

Checks if the location property is valid.

Redefinition of:

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

Redefined in descendants as:

Method	Description
`ezcCacheStorageFileApcArray::validateLocation()`	Checks the path in the location property exists, and is read-/writable. It throws an exception if not.

Documentation generated by phpDocumentor 1.4.3