Path

ez components / documentation / api reference / 1.0.1 / cache

eZ Components 1.0.1

Cache: ezcCacheManager

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcCacheManager

This is the main class of the Cache package. It gives you a handy interface to create and manage multiple caches at once. It enables you to configure all caches you need in your application in a central place and access them on demand in any place in your application. [source]
The use of ezcCacheManager is not required, but recommended. If you only need a few (or maybe just 1) cache instance, you can use and instantiate a ezcCacheStorage class directly.
Usage example for ezcCacheManager: 
 1.  // Some pre-work, needed by the example
 2.   $basePath = dirname( __FILE__ ).'/cache';
 3.  function getUniqueId()
 4.  {
 5.      return 'This is a unique ID';
 6.  }
 7.  
 8.  // Central creation and configuration of the caches
 9.  // The ezcCacheManager just stores the configuration right now and
10.  // performs sanity checks. The <a href="../Cache/ezcCacheStorage.html">ezcCacheStorage</a> instances
11.  // will be created on demand, when you use them for the first time
12.  
13.  // Configuration options for a cache <a href="../Cache/ezcCacheStorage.html">ezcCacheStorage</a>
14.   $options = array(
15.      'ttl'   => 60*60*24*2,     // Default would be 1 day, here 2 days
16.   );
17.  
18.  // Create a cache named "content", that resides in /var/cache/content
19.  // The cache instance will use the <a href="../Cache/ezcCacheStorageFileArray.html">ezcCacheStorageFileArray</a> class
20.  // to store the cache data. The time-to-live for cache items is set as
21.  // defined above.
22.   ezcCacheManager::createCache( 'content', $basePath.'/content', 'ezcCacheStorageFileArray', $options );
23.  
24.  // Create another cache, called "template" in /var/cache/templates.
25.  // This cache will use the <a href="../Cache/ezcCacheStorageFilePlain.html">ezcCacheStorageFilePlain</a> class to store
26.  // cache data. It has the same TTL as the cache defined above.
27.   ezcCacheManager::createCache( 'template', $basePath.'/templates', 'ezcCacheStorageFilePlain', $options );
28.  
29.  // Somewhere in the application you can access the caches
30.  
31.  // Get the instance of the cache called "content"
32.  // Now the instance of <a href="../Cache/ezcCacheStorageFileArray.html">is created and  // returned to be used. Next time you access this cache</a>, the, that, 'area', 'lang', if, or, $attributes, so, 'and, true, <a href="http://www.php.net/next">time the code is reached     $cache->store( $id</a>, $data, $attributes
33.   else
34.  {
35.      // We found cache data. Let's echo the information.
36.         echo "Cache data found.\n".var_export( $data, true )."\n";
37.  }
38.  
39.  // In some other place you can access the second defined cache.
40.   $cache = ezcCacheManager::getCache( 'template' );
41.  
42.  // Here we are removing cache items. We do not specify an ID (which would
43.  // have meant to delete 1 specific cache item), but only an array of
44.  // attributes. This will result in all cache items to be deleted, that
45.  // have this attribute assigned.
46.   $cache->delete( null, array( 'node' => 5 ) );

Method Summary

public static void createCache( $id, $location, $storageClass, [$options = array()] )
Creates a new cache in the manager.
public static ezcCacheStorage getCache( $id )
Returns the ezcCacheStorage object with the given ID.

Methods

createCache

void createCache( string $id, string $location, string $storageClass, [array(string=>string) $options = array()] )
Creates a new cache in the manager.
This method is used to create a new cache inside the manager. Each cache has a unique ID to access it during the application runtime. Each location may only be used by 1 cache.
The $storageClass parameter must be a subclass of ezcCacheStorage and tells the manager which object will be used for the cache.
The $location parameter depends on the kind of ezcCacheStorage used for the cache you create. Usually this is a directory on your file system, but may also be e.g. a data source name, if you cache in a database or similar.
The $options array consists of several standard attributes and can additionally contain options defined by the ezcCacheStorage class. Standard options are:
1.  array(
2.       'ttl'   => 60*60*24,    // Time-to-life, default: 1 day
3.   );

Parameters

Name Type Description
$id string ID of the cache to create.
$location string Location to create the cache in.
$storageClass string Subclass of ezcCacheStorage.
$options array(string=>string) Options for the cache.

Throws

ClassDescription
ezcBaseFileNotFoundException If the given location does not exist or is not a directory (thrown by sanity checks performed when storing the configuration of a cache to ensure the latter calls to ezcCacheManager::getCache() do not fail).
ezcBaseFilePermissionException If the given location is not read/writeable (thrown by sanity checks performed when storing the configuration of a cache to ensure the latter calls to ezcCacheManager::getCache() do not fail).
ezcCacheUsedLocationException If the given location is already in use by another cache.
ezcCacheInvalidStorageClassException If the given storage class does not exist or is no subclass of ezcCacheStorage.

getCache

ezcCacheStorage getCache( string $id )
Returns the ezcCacheStorage object with the given ID.
The cache ID has to be defined before using the ezcCacheManager::createCache() method. If no instance of this cache does exist yet, it's created on the fly. If one exists, it will be reused.

Parameters

Name Type Description
$id string The ID of the cache to return.

Throws

ClassDescription
ezcCacheInvalidIdException If the ID of a cache you try to access does not exist. To access a cache using this method, it first hast to be created using ezcCacheManager::createCache().
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.
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.
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.
ezcBaseSettingNotFoundException If you tried to set a non-existent option value. The accpeted options depend on th ezcCacheStorage implementation and my vary.

Last updated: Fri, 02 Nov 2007