## Apache Zeta Components Manual :: File Source for manager.php

## Source for file manager.php

Documentation is available at manager.php

1. <?php
2. /**
3. * File containing the ezcCacheManager class.
4. *
5. * Licensed to the Apache Software Foundation (ASF) under one
6. * or more contributor license agreements. See the NOTICE file
7. * distributed with this work for additional information
8. * regarding copyright ownership. The ASF licenses this file
9. * to you under the Apache License, Version 2.0 (the
10. * "License"); you may not use this file except in compliance
11. * with the License. You may obtain a copy of the License at
12. *
13. * http://www.apache.org/licenses/LICENSE-2.0
14. *
15. * Unless required by applicable law or agreed to in writing,
16. * software distributed under the License is distributed on an
17. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18. * KIND, either express or implied. See the License for the
19. * specific language governing permissions and limitations
20. * under the License.
21. *
22. * @package Cache
23. * @version //autogentag//
24. * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
25. * @filesource
26. */
28. /**
29. * This is the main class of the Cache package. It gives you a handy interface
30. * to create and manage multiple caches at once. It enables you to configure
31. * all caches you need in your application in a central place and access them
32. * on demand in any place in your application.
33. *
34. * The use of ezcCacheManager is not required, but recommended. If you only
35. * need a few (or maybe just 1) cache instance, you can use and instantiate
36. * a {@link ezcCacheStorage} class directly.
37. *
38. * Usage example for ezcCacheManager:
39. * <code>
40. * // Some pre-work, needed by the example
41. * $basePath = dirname( __FILE__ ).'/cache';
42. * function getUniqueId()
43. * {
44. * return 'This is a unique ID';
45. * }
46. *
47. * // Central creation and configuration of the caches
48. * // The ezcCacheManager just stores the configuration right now and
49. * // performs sanity checks. The ezcCacheStorage instances
50. * // will be created on demand, when you use them for the first time
51. *
52. * // Configuration options for a cache (see ezcCacheStorage)
53. * $options = array(
54. * 'ttl' => 60*60*24*2, // Default would be 1 day, here 2 days
55. * );
56. *
57. * // Create a cache named "content", that resides in /var/cache/content
58. * // The cache instance will use the ezcCacheStorageFileArray class
59. * // to store the cache data. The time-to-live for cache items is set as
60. * // defined above.
61. * ezcCacheManager::createCache( 'content', $basePath.'/content', 'ezcCacheStorageFileArray', $options );
62. *
63. * // Create another cache, called "template" in /var/cache/templates.
64. * // This cache will use the ezcCacheStorageFilePlain class to store
65. * // cache data. It has the same TTL as the cache defined above.
66. * ezcCacheManager::createCache( 'template', $basePath.'/templates', 'ezcCacheStorageFilePlain', $options );
67. *
68. * // Somewhere in the application you can access the caches
69. *
70. * // Get the instance of the cache called "content"
71. * // Now the instance of ezcCacheStorageFileArray is created and
72. * // returned to be used. Next time you access this cache, the created
73. * // instance will be reused.
74. * $cache = ezcCacheManager::getCache( 'content' );
75. *
76. * // Instead of using the createCache()/getCache() mechanism you can also
77. * // create cache on-demand with delayed initialization. You can find
78. * // information on how to use that in the tutorial.
79. *
80. * // Specify any number of attributes to identify the cache item you want
81. * // to store. This attributes can be used later to perform operations
82. * // on a set of cache items, that share a common attribute.
83. * $attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
84. *
85. * // This function is not part of the Cache package. You have to define
86. * // unique IDs for your cache items yourself.
87. * $id = getUniqueId();
88. *
89. * // Initialize the data variable you want to restore
90. * $data = '';
91. *
92. * // Check if data is available in the cache. The restore method returns
93. * // the cached data, if available, or bool false.
94. * if ( ( $data = $cache->restore( $id, $attributes ) ) === false )
95. * {
96. * // The cache item we tried to restore does not exist, so we have to
97. * // generate the data.
98. * $data = array( 'This is some data', 'and some more data.' );
99. * // For testing we echo something here...
100. * echo "No cache data found. Generated some.\n".var_export( $data, true )."\n";
101. * // Now we store the data in the cache. It will be available through
102. * // restore, next time the code is reached
103. * $cache->store( $id, $data, $attributes );
104. * }
105. * else
106. * {
107. * // We found cache data. Let's echo the information.
108. * echo "Cache data found.\n".var_export( $data, true )."\n";
109. * }
110. *
111. * // In some other place you can access the second defined cache.
112. * $cache = ezcCacheManager::getCache( 'template' );
113. *
114. * // Here we are removing cache items. We do not specify an ID (which would
115. * // have meant to delete 1 specific cache item), but only an array of
116. * // attributes. This will result in all cache items to be deleted, that
117. * // have this attribute assigned.
118. * $cache->delete( null, array( 'node' => 5 ) );
119. * </code>
120. *
121. * @package Cache
122. * @version //autogentag//
123. * @mainclass
124. */
125. class ezcCacheManager
126. {
127. /**
128. * Keeps track of the ezcCacheStorage instances.
129. * Each cache is created only once per request on the first time it is
130. * accessed through {@link ezcCacheManager::getCache()}. Until then,
131. * only its configuration is stored in the
132. * {@link ezcCacheManager::$configurations} array.
133. *
134. * @var array(int=>ezcCacheStorage)
135. */
136. private static $caches = array();
138. /**
139. * ezcCacheStorage configurations
140. * Storage to keep track of ezcCacheStorage configurations. For each
141. * configured cache the configuration is initially stored here.
142. * {@link ezcCacheStorage} objects are created on first access
143. * through {@link ezcCacheManager::getCache()}.
144. *
145. * @var array(string=>array(string=>string))
146. */
147. private static $configurations = array();
149. /**
150. * Private. This class has static methods only.
151. *
152. * @see ezcCacheManager::createCache()
153. * @see ezcCacheManager::getCache()
154. */
155. private function __construct()
156. {
157. }
159. /**
160. * Creates a new cache in the manager.
161. * This method is used to create a new cache inside the manager.
162. * Each cache has a unique ID to access it during the application
163. * runtime. Each location may only be used by 1 cache.
164. *
165. * The $storageClass parameter must be a subclass of
166. * {@link ezcCacheStorage} and tells the manager which object
167. * will be used for the cache.
168. *
169. * The $location parameter depends on the kind of {@link ezcCacheStorage}
170. * used for the cache you create. Usually this is a directory on your
171. * file system, but may also be e.g. a data source name, if you cache in
172. * a database or similar. For memory-based storage ({@link ezcCacheStorageApcPlain}
173. * or {@link ezcCacheStorageMemcachePlain}) it is null, but for
174. * memory/file hybrid storage ({@link ezcCacheStorageFileApcArray}) it should
175. * be an existing writeable path.
176. *
177. * The $options array consists of several standard attributes and can
178. * additionally contain options defined by the {@link ezcCacheStorage}
179. * class. Standard options are:
180. *
181. * <code>
182. * array(
183. * 'ttl' => 60*60*24, // Time-to-life, default: 1 day
184. * );
185. * </code>
186. *
187. * @param string $id ID of the cache to create.
188. * @param string $location Location to create the cache in. Null for
189. * memory-based storage and an existing
190. * writeable path for file or memory/file
191. * storage.
192. * @param string $storageClass Subclass of {@link ezcCacheStorage}.
193. * @param array(string=>string) $options Options for the cache.
194. * @return void
195. *
196. * @throws ezcBaseFileNotFoundException
197. * If the given location does not exist or is not a
198. * directory (thrown by sanity checks performed when storing the
199. * configuration of a cache to ensure the latter calls to
200. * {@link ezcCacheManager::getCache()} do not fail).
201. * @throws ezcBaseFilePermissionException
202. * If the given location is not read/writeable (thrown by sanity
203. * checks performed when storing the configuration of a cache to
204. * ensure the latter calls to {@link ezcCacheManager::getCache()}
205. * do not fail).
206. * @throws ezcCacheUsedLocationException
207. * If the given location is already in use by another cache.
208. * @throws ezcCacheInvalidStorageClassException
209. * If the given storage class does not exist or is no subclass of
210. * ezcCacheStorage.
211. */
212. public static function createCache ( $id, $location = null, $storageClass, $options = array() )
213. {
214. // BC for missing location. The location should not be missing.
215. if ( $location !== null )
216. {
217. // Unifiy file system locations
218. if ( substr ( $location, 0, 1 ) === '/' )
219. {
220. // If non-existent
221. if ( ( $realLocation = realpath ( $location ) ) === false )
222. {
223. throw new ezcBaseFileNotFoundException (
224. $location,
225. 'cache location',
226. 'Does not exist or is no directory.'
227. );
228. }
229. $location = $realLocation;
230. }
232. // Sanity check double taken locations.
233. foreach ( self::$configurations as $confId => $config )
234. {
235. if ( $config['location'] === $location )
236. {
237. throw new ezcCacheUsedLocationException( $location, $confId );
238. }
239. }
240. }
242. // Sanity check storage class.
243. if ( ! ezcBaseFeatures :: classExists ( $storageClass ) || ! is_subclass_of ( $storageClass, 'ezcCacheStorage' ) )
244. {
245. throw new ezcCacheInvalidStorageClassException ( $storageClass );
246. }
247. self::$configurations[$id] = array(
248. 'location' => $location,
249. 'class' => $storageClass,
250. 'options' => $options,
251. );
252. }
254. /**
255. * Returns the ezcCacheStorage object with the given ID.
256. * The cache ID has to be defined before using the
257. * {@link ezcCacheManager::createCache()} method. If no instance of this
258. * cache does exist yet, it's created on the fly. If one exists, it will
259. * be reused.
260. *
261. * @param string $id The ID of the cache to return.
262. * @return ezcCacheStorage The cache with the given ID.
263. *
264. * @throws ezcCacheInvalidIdException
265. * If the ID of a cache you try to access does not exist. To access
266. * a cache using this method, it first hast to be created using
267. * {@link ezcCacheManager::createCache()}.
268. * @throws ezcBaseFileNotFoundException
269. * If the storage location does not exist. This should usually not
270. * happen, since {@link ezcCacheManager::createCache()} already
271. * performs sanity checks for the cache location. In case this
272. * exception is thrown, your cache location has been corrupted
273. * after the cache was configured.
274. * @throws ezcBaseFileNotFoundException
275. * If the storage location is not a directory. This should usually
276. * not happen, since {@link ezcCacheManager::createCache()} already
277. * performs sanity checks for the cache location. In case this
278. * exception is thrown, your cache location has been corrupted
279. * after the cache was configured.
280. * @throws ezcBaseFilePermissionException
281. * If the storage location is not writeable. This should usually not
282. * happen, since {@link ezcCacheManager::createCache()} already
283. * performs sanity checks for the cache location. In case this
284. * exception is thrown, your cache location has been corrupted
285. * after the cache was configured.
286. * @throws ezcBasePropertyNotFoundException
287. * If you tried to set a non-existent option value. The accepted
288. * options depend on the ezcCacheStorage implementation and may
289. * vary.
290. */
291. public static function getCache ( $id )
292. {
293. // Look for already existing cache object
294. if ( !isset( self::$caches[$id] ) )
295. {
296. // Failed, look for configuration, and if it does not exist, use
297. // delayed initialization.
298. if ( !isset( self::$configurations[$id] ) )
299. {
300. ezcBaseInit::fetchConfig( 'ezcInitCacheManager', $id );
301. }
302. // Check whether delayed initialization actually worked, if not,
303. // throw an exception
304. if ( !isset( self::$configurations[$id] ) )
305. {
306. throw new ezcCacheInvalidIdException( $id );
307. }
308. $class = self::$configurations[$id]['class'];
309. self::$caches[$id] = new $class( self::$configurations[$id]['location'], self::$configurations[$id]['options'] );
310. }
311. return self::$caches[$id];
312. }
313. }
314. ?>

Documentation generated by phpDocumentor 1.4.3