Cache: ezcCacheManager
[ ]
[ ]
[ ]
[ ]
[ ]
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( $data, true )."\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( $data, true )."\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->delete( null, array( 'node' => 5 ) );
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 $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
| Class | Description |
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
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
| Class | Description |
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. |
ezcBasePropertyNotFoundException |
If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and my vary. |
Last updated: Mon, 09 Feb 2009