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

## Source for file storage.php

Documentation is available at storage.php

1. <?php
2. /**
3. * File containing the ezcCacheStorage 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 abstract base class for all cache storages. It provides
30. * the interface to be implemented by a cache backend as abstract methods.
31. * For your convenience it contains some methods you can utilize to create your
32. * own storage implementation (e.g. for storing cache data into a database).
33. *
34. * Implementations of ezcCacheStorage can be used with the
35. * {@link ezcCacheManager} or on their own. If you want to implement a cache
36. * storage backend that stores cache data in a file on your harddisk, there
37. * is an extended version of ezcCacheStorage, {@link ezcCacheStorageFile},
38. * which already implements large parts of the API and leaves only
39. * very few work for you to do. The descendant class {@link ezcCacheStorageMemory}
40. * is a base class for storage using memory.
41. *
42. * For example code of using a cache storage, see {@link ezcCacheManager}.
43. *
44. * The Cache package already contains several implementations of
45. * {@link ezcCacheStorageFile}:
46. *
47. * - {@link ezcCacheStorageFileArray}
48. * - {@link ezcCacheStorageFileEvalArray}
49. * - {@link ezcCacheStorageFilePlain}
50. *
51. * Implementations of {@link ezcCacheStorageMemory}:
52. *
53. * - {@link ezcCacheStorageMemcachePlain}
54. * - {@link ezcCacheStorageApcPlain}
55. * - {@link ezcCacheStorageFileApcArray}
56. *
57. * @property ezcCacheStorageOptions $options
58. * Options for the cache storage. Which options are
59. * supported depends on the specific implementation of the
60. * ezcCacheStorage.
61. * @property string $location
62. * The location the cache resides in.
63. *
64. * @package Cache
65. * @version //autogentag//
66. */
67. abstract class ezcCacheStorage
68. {
69. /**
70. * Container to hold the properties
71. *
72. * @var array(string=>mixed)
73. */
74. protected $properties ;
76. /**
77. * Creates a new cache storage in the given location.
78. * Creates a new cache storage for a given location. The location can
79. * differ for each ezcCacheStorage implementation, but will most likely
80. * be a filesystem path to a directory where cache data is stored in. The
81. * location is null for memory storage and an existing writeable path
82. * for file or memory/file storage.
83. *
84. * Per default there is only 1 common option for all ezcCacheStorage
85. * classes, which is the 'ttl' ( Time-To-Life ). This is per default set
86. * to 1 day. Specific ezcCacheStorage implementations can have
87. * additional options.
88. *
89. * @param string $location Path to the cache location. Null for
90. * memory-based storage and an existing
91. * writeable path for file or memory/file
92. * storage.
93. * @param array(string=>string) $options Options for the cache.
94. *
95. * @throws ezcBaseFileNotFoundException
96. * If the storage location does not exist. This should usually not
97. * happen, since {@link ezcCacheManager::createCache()} already
98. * performs sanity checks for the cache location. In case this
99. * exception is thrown, your cache location has been corrupted
100. * after the cache was configured.
101. * @throws ezcBaseFileNotFoundException
102. * If the storage location is not a directory. This should usually
103. * not happen, since {@link ezcCacheManager::createCache()} already
104. * performs sanity checks for the cache location. In case this
105. * exception is thrown, your cache location has been corrupted
106. * after the cache was configured.
107. * @throws ezcBaseFilePermissionException
108. * If the storage location is not writeable. This should usually not
109. * happen, since {@link ezcCacheManager::createCache()} already
110. * performs sanity checks for the cache location. In case this
111. * exception is thrown, your cache location has been corrupted
112. * after the cache was configured.
113. * @throws ezcBasePropertyNotFoundException
114. * If you tried to set a non-existent option value. The accepted
115. * options depend on the ezcCacheStorage implementation and may
116. * vary.
117. */
118. public function __construct ( $location, $options = array() )
119. {
120. $this-> properties ['location'] = ( substr ( $location, -1 ) === '/' ) ? $location : $location . '/';
121. $this-> validateLocation ();
122. $this-> properties ['options'] = new ezcCacheStorageOptions ( $options );
123. }
125. /**
126. * Store data to the cache storage.
127. * This method stores the given cache data into the cache, assigning the
128. * ID given to it.
129. *
130. * The type of cache data which is expected by a ezcCacheStorage depends on
131. * its implementation. In most cases strings and arrays will be accepted,
132. * in some rare cases only strings might be accepted.
133. *
134. * Using attributes you can describe your cache data further. This allows
135. * you to deal with multiple cache data at once later. Some ezcCacheStorage
136. * implementations also use the attributes for storage purposes. Attributes
137. * form some kind of "extended ID".
138. *
139. * @param string $id The item ID.
140. * @param mixed $data The data to store.
141. * @param array(string=>string) $attributes Attributes that describe the
142. * cached data.
143. *
144. * @return string The ID of the newly cached data.
145. *
146. * @throws ezcBaseFilePermissionException
147. * If an already existsing cache file could not be unlinked to
148. * store the new data (may occur, when a cache item's TTL
149. * has expired and the file should be stored with more actual
150. * data). This exception means most likely that your cache directory
151. * has been corrupted by external influences (file permission
152. * change).
153. * @throws ezcBaseFilePermissionException
154. * If the directory to store the cache file could not be created.
155. * This exception means most likely that your cache directory
156. * has been corrupted by external influences (file permission
157. * change).
158. * @throws ezcBaseFileIoException
159. * If an error occured while writing the data to the cache. If this
160. * exception occurs, a serious error occured and your storage might
161. * be corruped (e.g. broken network connection, file system broken,
162. * ...).
163. * @throws ezcCacheInvalidDataException
164. * If the data submitted can not be handled by the implementation
165. * of {@link ezcCacheStorage}. Most implementations can not
166. * handle objects and resources.
167. */
168. abstract public function store ( $id, $data, $attributes = array() );
170. /**
171. * Restore data from the cache.
172. * Restores the data associated with the given cache and
173. * returns it. Please see {@link ezcCacheStorage::store()}
174. * for more detailed information of cachable datatypes.
175. *
176. * During access to cached data the caches are automatically
177. * expired. This means, that the ezcCacheStorage object checks
178. * before returning the data if it's still actual. If the cache
179. * has expired, data will be deleted and false is returned.
180. *
181. * You should always provide the attributes you assigned, although
182. * the cache storages must be able to find a cache ID even without
183. * them. BEWARE: Finding cache data only by ID can be much
184. * slower than finding it by ID and attributes.
185. *
186. * @param string $id The item ID.
187. * @param array(string=>string) $attributes Attributes that describe the
188. * cached data.
189. * @param bool $search Whether to search for items
190. * if not found directly. Default is
191. * false.
192. *
193. * @return mixed The cached data on success, otherwise false.
194. *
195. * @throws ezcBaseFilePermissionException
196. * If an already existsing cache file could not be unlinked.
197. * This exception means most likely that your cache directory
198. * has been corrupted by external influences (file permission
199. * change).
200. */
201. abstract public function restore ( $id, $attributes = array(), $search = false );
203. /**
204. * Delete data from the cache.
205. * Purges the cached data for a given ID and or attributes. Using an ID
206. * purges only the cache data for just this ID.
207. *
208. * Additional attributes provided will matched additionally. This can give
209. * you an immense speed improvement against just searching for ID ( see
210. * {@link ezcCacheStorage::restore()} ).
211. *
212. * If you only provide attributes for deletion of cache data, all cache
213. * data matching these attributes will be purged.
214. *
215. * @param string $id The item ID.
216. * @param array(string=>string) $attributes Attributes that describe the
217. * cached data.
218. * @param bool $search Whether to search for items
219. * if not found directly. Default is
220. * false.
221. *
222. * @throws ezcBaseFilePermissionException
223. * If an already existsing cache file could not be unlinked.
224. * This exception means most likely that your cache directory
225. * has been corrupted by external influences (file permission
226. * change).
227. */
228. abstract public function delete ( $id = null, $attributes = array(), $search = false );
230. /**
231. * Return the number of items in the cache matching a certain criteria.
232. * This method determines if cache data described by the given ID and/or
233. * attributes exists. It returns the number of cache data items found.
234. *
235. * @param string $id The item ID.
236. * @param array(string=>string) $attributes Attributes that describe the item
237. * @return int The number of cache data items found matching the criteria
238. */
239. abstract public function countDataItems ( $id = null, $attributes = array() );
241. /**
242. * Returns the time ( in seconds ) that remains for a cache object,
243. * before it gets outdated. In case the cache object is already
244. * outdated or does not exist, this method returns 0.
245. *
246. * @param string $id The item ID.
247. * @param array(string=>string) $attributes Attributes that describe the
248. * @access public
249. * @return int The remaining lifetime ( 0 if nonexists or outdated ).
250. */
251. abstract public function getRemainingLifetime ( $id, $attributes = array() );
253. /**
254. * Checks if the location property is valid.
255. */
256. abstract protected function validateLocation ();
258. /**
259. * Returns the location.
260. *
261. * Returns the location the current storage resides in. The
262. * $location attribute has no setter, since it can only be set during
263. * construction.
264. *
265. * @return string The location of this storage.
266. *
267. * @apichange Use $stack->location instead.
268. */
269. public function getLocation ()
270. {
271. return $this-> properties ['location'];
272. }
274. /**
275. * Return the currently set options.
276. *
277. * Return the currently set options. The options are returned on an array
278. * that has the same format as the one passed to
279. * {@link ezcCacheStorage::setOptions()}. The possible options for a storage
280. * depend on its implementation.
281. *
282. * @return ezcCacheStorageOptions The options
283. *
284. * @apichange Use $storage->options instead.
285. */
286. public function getOptions ()
287. {
288. return $this-> properties ['options'];
289. }
291. /**
292. * Set new options.
293. *
294. * This method allows you to change the options of a cache storage. Change
295. * of options take effect directly after this method has been called. The
296. * available options depend on the ezcCacheStorage implementation. All
297. * implementations have to offer the following options:
298. *
299. * - ttl The time-to-life. After this time span, a cache item becomes
300. * invalid and will be purged. The
301. * {@link ezcCacheStorage::restore()} method will then return
302. * false.
303. * - extension The "extension" for your cache items. This is usually the
304. * file name extension, when you deal with file system based
305. * caches or e.g. a database ID extension.
306. *
307. * @param ezcCacheStorageOptions $options The options to set.
308. *
309. * @throws ezcBasePropertyNotFoundException
310. * If you tried to set a non-existent option value. The accepted
311. * options depend on the ezcCacheStorage implementation and may
312. * vary.
313. * @throws ezcBaseValueException
314. * If the value is not valid for the desired option.
315. * @throws ezcBaseValueException
316. * If you submit neither an array nor an instance of
317. * ezcCacheStorageOptions.
318. *
319. * @apichange Use $storage->options instead.
320. */
321. public function setOptions ( $options )
322. {
323. if ( is_array ( $options ) )
324. {
325. $this-> properties ['options']->merge( $options );
326. }
327. else if ( $options instanceof ezcCacheStorageOptions )
328. {
329. $this-> properties ['options'] = $options;
330. }
331. else
332. {
333. throw new ezcBaseValueException ( "options", $options, "instance of ezcCacheStorageOptions" );
334. }
335. }
338. /**
339. * Property read access.
340. *
341. * @throws ezcBasePropertyNotFoundException
342. * If the the desired property is not found.
343. *
344. * @param string $propertyName Name of the property.
345. * @return mixed Value of the property or null.
346. * @ignore
347. */
348. public function __get( $propertyName )
349. {
350. if ( $this->__isset( $propertyName ) )
351. {
352. return $this-> properties [$propertyName];
353. }
354. throw new ezcBasePropertyNotFoundException ( $propertyName );
355. }
357. /**
358. * Property write access.
359. *
360. * @param string $propertyName Name of the property.
361. * @param mixed $val The value for the property.
362. *
363. * @throws ezcBaseValueException
364. * If the value for the property options is not an instance of
365. * ezcCacheStorageOptions.
366. * @ignore
367. */
368. public function __set( $propertyName, $val )
369. {
370. switch ( $propertyName )
371. {
372. case 'options':
373. if ( !( $val instanceof ezcCacheStorageOptions ) )
374. {
375. throw new ezcBaseValueException ( $propertyName, $val, 'instance of ezcCacheStorageOptions' );
376. }
377. break;
378. case 'location':
379. throw new ezcBasePropertyPermissionException (
380. $propertyName,
381. ezcBasePropertyPermissionException ::READ
382. );
383. default:
384. throw new ezcBasePropertyNotFoundException ( $propertyName );
385. }
386. $this-> properties [$propertyName] = $val;
387. }
389. /**
390. * Property isset access.
391. *
392. * @param string $propertyName Name of the property.
393. * @return bool True is the property is set, otherwise false.
394. * @ignore
395. */
396. public function __isset( $propertyName )
397. {
398. return array_key_exists ( $propertyName, $this-> properties );
399. }
400. }
401. ?>

Documentation generated by phpDocumentor 1.4.3