Path

ez components / documentation / api reference / 2009.2.1 / cache


eZ Components 2009.2.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 ezcCacheStorage instances
11.  // will be created on demand, when you use them for the first time
12.  
13.  // Configuration options for a cache (see ezcCacheStorage)
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 ezcCacheStorageFileArray 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 ezcCacheStorageFilePlain 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 ezcCacheStorageFileArray is created and
33.  // returned to be used. Next time you access this cache, the created
34.  // instance will be reused.
35.  $cache ezcCacheManager::getCache'content' );
36.  
37.  // Instead of using the createCache()/getCache() mechanism you can also
38.  // create cache on-demand with delayed initialization. You can find
39.  // information on how to use that in the tutorial.
40.  
41.  // Specify any number of attributes to identify the cache item you want
42.  // to store. This attributes can be used later to perform operations
43.  // on a set of cache items, that share a common attribute.
44.  $attributes array'node' => 2'area' => 'admin''lang' => 'en-GB' );
45.  
46.  // This function is not part of the Cache package. You have to define
47.  // unique IDs for your cache items yourself.
48.  $id getUniqueId();
49.  
50.  // Initialize the data variable you want to restore
51.  $data '';
52.  
53.  // Check if data is available in the cache. The restore method returns
54.  // the cached data, if available, or bool false.
55.  if ( ( $data $cache->restore$id$attributes ) ) === false )
56.  {
57.      // The cache item we tried to restore does not exist, so we have to
58.      // generate the data.
59.      $data array'This is some data''and some more data.' );
60.      // For testing we echo something here...
61.      echo "No cache data found. Generated some.\n".var_export$datatrue )."\n";
62.      // Now we store the data in the cache. It will be available through
63.      // restore, next time the code is reached
64.      $cache->store$id$data$attributes );
65.  }
66.  else
67.  {
68.      // We found cache data. Let's echo the information.
69.      echo "Cache data found.\n".var_export$datatrue )."\n";
70.  }
71.  
72.  // In some other place you can access the second defined cache.
73.  $cache ezcCacheManager::getCache'template' );
74.  
75.  // Here we are removing cache items. We do not specify an ID (which would
76.  // have meant to delete 1 specific cache item), but only an array of
77.  // attributes. This will result in all cache items to be deleted, that
78.  // have this attribute assigned.
79.  $cache->deletenullarray'node' => ) );

Method Summary

public static void createCache( $id, [$location = null], $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 = null], 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. For memory-based storage (ezcCacheStorageApcPlain or ezcCacheStorageMemcachePlain) it is null, but for memory/file hybrid storage (ezcCacheStorageFileApcArray) it should be an existing writeable path.
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. Null for memory-based storage and an existing writeable path for file or memory/file storage.
$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).
ezcCacheInvalidStorageClassException If the given storage class does not exist or is no subclass of ezcCacheStorage.
ezcCacheUsedLocationException If the given location is already in use by another cache.

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().
ezcBasePropertyNotFoundException If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and may vary.
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.
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.
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.

Last updated: Tue, 23 Mar 2010