1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
11: * @link http://cakephp.org CakePHP(tm) Project
12: * @package Cake.Cache
13: * @since CakePHP(tm) v 1.2.0.4933
14: * @license http://www.opensource.org/licenses/mit-license.php MIT License
15: */
16:
17: App::uses('Inflector', 'Utility');
18: App::uses('CacheEngine', 'Cache');
19:
20: /**
21: * Cache provides a consistent interface to Caching in your application. It allows you
22: * to use several different Cache engines, without coupling your application to a specific
23: * implementation. It also allows you to change out cache storage or configuration without effecting
24: * the rest of your application.
25: *
26: * You can configure Cache engines in your application's `bootstrap.php` file. A sample configuration would
27: * be
28: *
29: * ```
30: * Cache::config('shared', array(
31: * 'engine' => 'Apc',
32: * 'prefix' => 'my_app_'
33: * ));
34: * ```
35: *
36: * This would configure an APC cache engine to the 'shared' alias. You could then read and write
37: * to that cache alias by using it for the `$config` parameter in the various Cache methods. In
38: * general all Cache operations are supported by all cache engines. However, Cache::increment() and
39: * Cache::decrement() are not supported by File caching.
40: *
41: * @package Cake.Cache
42: */
43: class Cache {
44:
45: /**
46: * Cache configuration stack
47: * Keeps the permanent/default settings for each cache engine.
48: * These settings are used to reset the engines after temporary modification.
49: *
50: * @var array
51: */
52: protected static $_config = array();
53:
54: /**
55: * Group to Config mapping
56: *
57: * @var array
58: */
59: protected static $_groups = array();
60:
61: /**
62: * Whether to reset the settings with the next call to Cache::set();
63: *
64: * @var array
65: */
66: protected static $_reset = false;
67:
68: /**
69: * Engine instances keyed by configuration name.
70: *
71: * @var array
72: */
73: protected static $_engines = array();
74:
75: /**
76: * Set the cache configuration to use. config() can
77: * both create new configurations, return the settings for already configured
78: * configurations.
79: *
80: * To create a new configuration, or to modify an existing configuration permanently:
81: *
82: * `Cache::config('my_config', array('engine' => 'File', 'path' => TMP));`
83: *
84: * If you need to modify a configuration temporarily, use Cache::set().
85: * To get the settings for a configuration:
86: *
87: * `Cache::config('default');`
88: *
89: * There are 5 built-in caching engines:
90: *
91: * - `FileEngine` - Uses simple files to store content. Poor performance, but good for
92: * storing large objects, or things that are not IO sensitive.
93: * - `ApcEngine` - Uses the APC object cache, one of the fastest caching engines.
94: * - `MemcacheEngine` - Uses the PECL::Memcache extension and Memcached for storage.
95: * Fast reads/writes, and benefits from memcache being distributed.
96: * - `XcacheEngine` - Uses the Xcache extension, an alternative to APC.
97: * - `WincacheEngine` - Uses Windows Cache Extension for PHP. Supports wincache 1.1.0 and higher.
98: *
99: * The following keys are used in core cache engines:
100: *
101: * - `duration` Specify how long items in this cache configuration last.
102: * - `groups` List of groups or 'tags' associated to every key stored in this config.
103: * handy for deleting a complete group from cache.
104: * - `prefix` Prefix appended to all entries. Good for when you need to share a keyspace
105: * with either another cache config or another application.
106: * - `probability` Probability of hitting a cache gc cleanup. Setting to 0 will disable
107: * cache::gc from ever being called automatically.
108: * - `servers' Used by memcache. Give the address of the memcached servers to use.
109: * - `compress` Used by memcache. Enables memcache's compressed format.
110: * - `serialize` Used by FileCache. Should cache objects be serialized first.
111: * - `path` Used by FileCache. Path to where cachefiles should be saved.
112: * - `lock` Used by FileCache. Should files be locked before writing to them?
113: * - `user` Used by Xcache. Username for XCache
114: * - `password` Used by Xcache/Redis. Password for XCache/Redis
115: *
116: * @param string $name Name of the configuration
117: * @param array $settings Optional associative array of settings passed to the engine
118: * @return array array(engine, settings) on success, false on failure
119: * @throws CacheException
120: * @see app/Config/core.php for configuration settings
121: */
122: public static function config($name = null, $settings = array()) {
123: if (is_array($name)) {
124: $settings = $name;
125: }
126:
127: $current = array();
128: if (isset(self::$_config[$name])) {
129: $current = self::$_config[$name];
130: }
131:
132: if (!empty($settings)) {
133: self::$_config[$name] = $settings + $current;
134: }
135:
136: if (empty(self::$_config[$name]['engine'])) {
137: return false;
138: }
139:
140: if (!empty(self::$_config[$name]['groups'])) {
141: foreach (self::$_config[$name]['groups'] as $group) {
142: self::$_groups[$group][] = $name;
143: sort(self::$_groups[$group]);
144: self::$_groups[$group] = array_unique(self::$_groups[$group]);
145: }
146: }
147:
148: $engine = self::$_config[$name]['engine'];
149:
150: if (!isset(self::$_engines[$name])) {
151: self::_buildEngine($name);
152: $settings = self::$_config[$name] = self::settings($name);
153: } elseif ($settings = self::set(self::$_config[$name], null, $name)) {
154: self::$_config[$name] = $settings;
155: }
156: return compact('engine', 'settings');
157: }
158:
159: /**
160: * Finds and builds the instance of the required engine class.
161: *
162: * @param string $name Name of the config array that needs an engine instance built
163: * @return bool
164: * @throws CacheException
165: */
166: protected static function _buildEngine($name) {
167: $config = self::$_config[$name];
168:
169: list($plugin, $class) = pluginSplit($config['engine'], true);
170: $cacheClass = $class . 'Engine';
171: App::uses($cacheClass, $plugin . 'Cache/Engine');
172: if (!class_exists($cacheClass)) {
173: throw new CacheException(__d('cake_dev', 'Cache engine %s is not available.', $name));
174: }
175: $cacheClass = $class . 'Engine';
176: if (!is_subclass_of($cacheClass, 'CacheEngine')) {
177: throw new CacheException(__d('cake_dev', 'Cache engines must use %s as a base class.', 'CacheEngine'));
178: }
179: self::$_engines[$name] = new $cacheClass();
180: if (!self::$_engines[$name]->init($config)) {
181: $msg = __d(
182: 'cake_dev',
183: 'Cache engine "%s" is not properly configured. Ensure required extensions are installed, and credentials/permissions are correct',
184: $name
185: );
186: throw new CacheException($msg);
187: }
188: if (self::$_engines[$name]->settings['probability'] && time() % self::$_engines[$name]->settings['probability'] === 0) {
189: self::$_engines[$name]->gc();
190: }
191: return true;
192: }
193:
194: /**
195: * Returns an array containing the currently configured Cache settings.
196: *
197: * @return array Array of configured Cache config names.
198: */
199: public static function configured() {
200: return array_keys(self::$_config);
201: }
202:
203: /**
204: * Drops a cache engine. Deletes the cache configuration information
205: * If the deleted configuration is the last configuration using a certain engine,
206: * the Engine instance is also unset.
207: *
208: * @param string $name A currently configured cache config you wish to remove.
209: * @return bool success of the removal, returns false when the config does not exist.
210: */
211: public static function drop($name) {
212: if (!isset(self::$_config[$name])) {
213: return false;
214: }
215: unset(self::$_config[$name], self::$_engines[$name]);
216: return true;
217: }
218:
219: /**
220: * Temporarily change the settings on a cache config. The settings will persist for the next write
221: * operation (write, decrement, increment, clear). Any reads that are done before the write, will
222: * use the modified settings. If `$settings` is empty, the settings will be reset to the
223: * original configuration.
224: *
225: * Can be called with 2 or 3 parameters. To set multiple values at once.
226: *
227: * `Cache::set(array('duration' => '+30 minutes'), 'my_config');`
228: *
229: * Or to set one value.
230: *
231: * `Cache::set('duration', '+30 minutes', 'my_config');`
232: *
233: * To reset a config back to the originally configured values.
234: *
235: * `Cache::set(null, 'my_config');`
236: *
237: * @param string|array $settings Optional string for simple name-value pair or array
238: * @param string $value Optional for a simple name-value pair
239: * @param string $config The configuration name you are changing. Defaults to 'default'
240: * @return array Array of settings.
241: */
242: public static function set($settings = array(), $value = null, $config = 'default') {
243: if (is_array($settings) && $value !== null) {
244: $config = $value;
245: }
246: if (!isset(self::$_config[$config]) || !isset(self::$_engines[$config])) {
247: return false;
248: }
249: if (!empty($settings)) {
250: self::$_reset = true;
251: }
252:
253: if (self::$_reset === true) {
254: if (empty($settings)) {
255: self::$_reset = false;
256: $settings = self::$_config[$config];
257: } else {
258: if (is_string($settings) && $value !== null) {
259: $settings = array($settings => $value);
260: }
261: $settings += self::$_config[$config];
262: if (isset($settings['duration']) && !is_numeric($settings['duration'])) {
263: $settings['duration'] = strtotime($settings['duration']) - time();
264: }
265: }
266: self::$_engines[$config]->settings = $settings;
267: }
268: return self::settings($config);
269: }
270:
271: /**
272: * Garbage collection
273: *
274: * Permanently remove all expired and deleted data
275: *
276: * @param string $config [optional] The config name you wish to have garbage collected. Defaults to 'default'
277: * @param int $expires [optional] An expires timestamp. Defaults to NULL
278: * @return void
279: */
280: public static function gc($config = 'default', $expires = null) {
281: self::$_engines[$config]->gc($expires);
282: }
283:
284: /**
285: * Write data for key into a cache engine.
286: *
287: * ### Usage:
288: *
289: * Writing to the active cache config:
290: *
291: * `Cache::write('cached_data', $data);`
292: *
293: * Writing to a specific cache config:
294: *
295: * `Cache::write('cached_data', $data, 'long_term');`
296: *
297: * @param string $key Identifier for the data
298: * @param mixed $value Data to be cached - anything except a resource
299: * @param string $config Optional string configuration name to write to. Defaults to 'default'
300: * @return bool True if the data was successfully cached, false on failure
301: */
302: public static function write($key, $value, $config = 'default') {
303: $settings = self::settings($config);
304:
305: if (empty($settings)) {
306: return false;
307: }
308: if (!self::isInitialized($config)) {
309: return false;
310: }
311: $key = self::$_engines[$config]->key($key);
312:
313: if (!$key || is_resource($value)) {
314: return false;
315: }
316:
317: $success = self::$_engines[$config]->write($settings['prefix'] . $key, $value, $settings['duration']);
318: self::set(null, $config);
319: if ($success === false && $value !== '') {
320: trigger_error(
321: __d('cake_dev',
322: "%s cache was unable to write '%s' to %s cache",
323: $config,
324: $key,
325: self::$_engines[$config]->settings['engine']
326: ),
327: E_USER_WARNING
328: );
329: }
330: return $success;
331: }
332:
333: /**
334: * Read a key from a cache config.
335: *
336: * ### Usage:
337: *
338: * Reading from the active cache configuration.
339: *
340: * `Cache::read('my_data');`
341: *
342: * Reading from a specific cache configuration.
343: *
344: * `Cache::read('my_data', 'long_term');`
345: *
346: * @param string $key Identifier for the data
347: * @param string $config optional name of the configuration to use. Defaults to 'default'
348: * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
349: */
350: public static function read($key, $config = 'default') {
351: $settings = self::settings($config);
352:
353: if (empty($settings)) {
354: return false;
355: }
356: if (!self::isInitialized($config)) {
357: return false;
358: }
359: $key = self::$_engines[$config]->key($key);
360: if (!$key) {
361: return false;
362: }
363: return self::$_engines[$config]->read($settings['prefix'] . $key);
364: }
365:
366: /**
367: * Increment a number under the key and return incremented value.
368: *
369: * @param string $key Identifier for the data
370: * @param int $offset How much to add
371: * @param string $config Optional string configuration name. Defaults to 'default'
372: * @return mixed new value, or false if the data doesn't exist, is not integer,
373: * or if there was an error fetching it.
374: */
375: public static function increment($key, $offset = 1, $config = 'default') {
376: $settings = self::settings($config);
377:
378: if (empty($settings)) {
379: return false;
380: }
381: if (!self::isInitialized($config)) {
382: return false;
383: }
384: $key = self::$_engines[$config]->key($key);
385:
386: if (!$key || !is_int($offset) || $offset < 0) {
387: return false;
388: }
389: $success = self::$_engines[$config]->increment($settings['prefix'] . $key, $offset);
390: self::set(null, $config);
391: return $success;
392: }
393:
394: /**
395: * Decrement a number under the key and return decremented value.
396: *
397: * @param string $key Identifier for the data
398: * @param int $offset How much to subtract
399: * @param string $config Optional string configuration name. Defaults to 'default'
400: * @return mixed new value, or false if the data doesn't exist, is not integer,
401: * or if there was an error fetching it
402: */
403: public static function decrement($key, $offset = 1, $config = 'default') {
404: $settings = self::settings($config);
405:
406: if (empty($settings)) {
407: return false;
408: }
409: if (!self::isInitialized($config)) {
410: return false;
411: }
412: $key = self::$_engines[$config]->key($key);
413:
414: if (!$key || !is_int($offset) || $offset < 0) {
415: return false;
416: }
417: $success = self::$_engines[$config]->decrement($settings['prefix'] . $key, $offset);
418: self::set(null, $config);
419: return $success;
420: }
421:
422: /**
423: * Delete a key from the cache.
424: *
425: * ### Usage:
426: *
427: * Deleting from the active cache configuration.
428: *
429: * `Cache::delete('my_data');`
430: *
431: * Deleting from a specific cache configuration.
432: *
433: * `Cache::delete('my_data', 'long_term');`
434: *
435: * @param string $key Identifier for the data
436: * @param string $config name of the configuration to use. Defaults to 'default'
437: * @return bool True if the value was successfully deleted, false if it didn't exist or couldn't be removed
438: */
439: public static function delete($key, $config = 'default') {
440: $settings = self::settings($config);
441:
442: if (empty($settings)) {
443: return false;
444: }
445: if (!self::isInitialized($config)) {
446: return false;
447: }
448: $key = self::$_engines[$config]->key($key);
449: if (!$key) {
450: return false;
451: }
452:
453: $success = self::$_engines[$config]->delete($settings['prefix'] . $key);
454: self::set(null, $config);
455: return $success;
456: }
457:
458: /**
459: * Delete all keys from the cache.
460: *
461: * @param bool $check if true will check expiration, otherwise delete all
462: * @param string $config name of the configuration to use. Defaults to 'default'
463: * @return bool True if the cache was successfully cleared, false otherwise
464: */
465: public static function clear($check = false, $config = 'default') {
466: if (!self::isInitialized($config)) {
467: return false;
468: }
469: $success = self::$_engines[$config]->clear($check);
470: self::set(null, $config);
471: return $success;
472: }
473:
474: /**
475: * Delete all keys from the cache belonging to the same group.
476: *
477: * @param string $group name of the group to be cleared
478: * @param string $config name of the configuration to use. Defaults to 'default'
479: * @return bool True if the cache group was successfully cleared, false otherwise
480: */
481: public static function clearGroup($group, $config = 'default') {
482: if (!self::isInitialized($config)) {
483: return false;
484: }
485: $success = self::$_engines[$config]->clearGroup($group);
486: self::set(null, $config);
487: return $success;
488: }
489:
490: /**
491: * Check if Cache has initialized a working config for the given name.
492: *
493: * @param string $config name of the configuration to use. Defaults to 'default'
494: * @return bool Whether or not the config name has been initialized.
495: */
496: public static function isInitialized($config = 'default') {
497: if (Configure::read('Cache.disable')) {
498: return false;
499: }
500: return isset(self::$_engines[$config]);
501: }
502:
503: /**
504: * Return the settings for the named cache engine.
505: *
506: * @param string $name Name of the configuration to get settings for. Defaults to 'default'
507: * @return array list of settings for this engine
508: * @see Cache::config()
509: */
510: public static function settings($name = 'default') {
511: if (!empty(self::$_engines[$name])) {
512: return self::$_engines[$name]->settings();
513: }
514: return array();
515: }
516:
517: /**
518: * Retrieve group names to config mapping.
519: *
520: * ```
521: * Cache::config('daily', array(
522: * 'duration' => '1 day', 'groups' => array('posts')
523: * ));
524: * Cache::config('weekly', array(
525: * 'duration' => '1 week', 'groups' => array('posts', 'archive')
526: * ));
527: * $configs = Cache::groupConfigs('posts');
528: * ```
529: *
530: * $config will equal to `array('posts' => array('daily', 'weekly'))`
531: *
532: * @param string $group group name or null to retrieve all group mappings
533: * @return array map of group and all configuration that has the same group
534: * @throws CacheException
535: */
536: public static function groupConfigs($group = null) {
537: if ($group === null) {
538: return self::$_groups;
539: }
540: if (isset(self::$_groups[$group])) {
541: return array($group => self::$_groups[$group]);
542: }
543: throw new CacheException(__d('cake_dev', 'Invalid cache group %s', $group));
544: }
545:
546: /**
547: * Provides the ability to easily do read-through caching.
548: *
549: * When called if the $key is not set in $config, the $callable function
550: * will be invoked. The results will then be stored into the cache config
551: * at key.
552: *
553: * Examples:
554: *
555: * Using a Closure to provide data, assume $this is a Model:
556: *
557: * ```
558: * $model = $this;
559: * $results = Cache::remember('all_articles', function() use ($model) {
560: * return $model->find('all');
561: * });
562: * ```
563: *
564: * @param string $key The cache key to read/store data at.
565: * @param callable $callable The callable that provides data in the case when
566: * the cache key is empty. Can be any callable type supported by your PHP.
567: * @param string $config The cache configuration to use for this operation.
568: * Defaults to default.
569: * @return mixed The results of the callable or unserialized results.
570: */
571: public static function remember($key, $callable, $config = 'default') {
572: $existing = self::read($key, $config);
573: if ($existing !== false) {
574: return $existing;
575: }
576: $results = call_user_func($callable);
577: self::write($key, $results, $config);
578: return $results;
579: }
580:
581: }
582: