FileCache.php 8.27 KB
Newer Older
Qiang Xue committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
Qiang Xue committed
5 6 7
 * @license http://www.yiiframework.com/license/
 */

Qiang Xue committed
8 9
namespace yii\caching;

10
use Yii;
11
use yii\helpers\FileHelper;
12

Qiang Xue committed
13
/**
14
 * FileCache implements a cache component using files.
Qiang Xue committed
15
 *
16 17 18
 * For each data value being cached, FileCache will store it in a separate file.
 * The cache files are placed under [[cachePath]]. FileCache will perform garbage collection
 * automatically to remove expired cache files.
Qiang Xue committed
19
 *
20
 * Please refer to [[Cache]] for common cache operations that are supported by FileCache.
Qiang Xue committed
21 22
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
Qiang Xue committed
23
 * @since 2.0
Qiang Xue committed
24
 */
25
class FileCache extends Cache
Qiang Xue committed
26
{
27 28 29 30 31 32 33 34
	/**
	 * @var string a string prefixed to every cache key. This is needed when you store
	 * cache data under the same [[cachePath]] for different applications to avoid
	 * conflict.
	 *
	 * To ensure interoperability, only alphanumeric characters should be used.
	 */
	public $keyPrefix = '';
Qiang Xue committed
35
	/**
36
	 * @var string the directory to store cache files. You may use path alias here.
Qiang Xue committed
37
	 * If not set, it will use the "cache" subdirectory under the application runtime path.
Qiang Xue committed
38
	 */
39
	public $cachePath = '@runtime/cache';
Qiang Xue committed
40 41 42
	/**
	 * @var string cache file suffix. Defaults to '.bin'.
	 */
43
	public $cacheFileSuffix = '.bin';
Qiang Xue committed
44
	/**
45 46 47 48
	 * @var integer the level of sub-directories to store cache files. Defaults to 1.
	 * If the system has huge number of cache files (e.g. one million), you may use a bigger value
	 * (usually no bigger than 3). Using sub-directories is mainly to ensure the file system
	 * is not over burdened with a single directory having too many files.
Qiang Xue committed
49
	 */
50
	public $directoryLevel = 1;
Qiang Xue committed
51
	/**
52
	 * @var integer the probability (parts per million) that garbage collection (GC) should be performed
53 54
	 * when storing a piece of data in the cache. Defaults to 10, meaning 0.001% chance.
	 * This number should be between 0 and 1000000. A value 0 means no GC will be performed at all.
55
	 **/
56
	public $gcProbability = 10;
57 58 59 60 61 62 63 64 65 66 67 68 69 70
	/**
	 * @var integer the permission to be set for newly created cache files.
	 * This value will be used by PHP chmod() function. No umask will be applied.
	 * If not set, the permission will be determined by the current environment.
	 */
	public $fileMode;
	/**
	 * @var integer the permission to be set for newly created directories.
	 * This value will be used by PHP chmod() function. No umask will be applied.
	 * Defaults to 0775, meaning the directory is read-writable by owner and group,
	 * but read-only for other users.
	 */
	public $dirMode = 0775;

Qiang Xue committed
71 72

	/**
73
	 * Initializes this component by ensuring the existence of the cache path.
Qiang Xue committed
74
	 */
75
	public function init()
Qiang Xue committed
76
	{
77
		parent::init();
78
		$this->cachePath = Yii::getAlias($this->cachePath);
79
		if (!is_dir($this->cachePath)) {
80
			FileHelper::createDirectory($this->cachePath, $this->dirMode, true);
81
		}
Qiang Xue committed
82 83
	}

84 85 86 87 88 89 90 91 92 93 94 95 96
	/**
	 * Checks whether a specified key exists in the cache.
	 * This can be faster than getting the value from the cache if the data is big.
	 * Note that this method does not check whether the dependency associated
	 * with the cached data, if there is any, has changed. So a call to [[get]]
	 * may return false while exists returns true.
	 * @param mixed $key a key identifying the cached value. This can be a simple string or
	 * a complex data structure consisting of factors representing the key.
	 * @return boolean true if a value exists in cache, false if the value is not in the cache or expired.
	 */
	public function exists($key)
	{
		$cacheFile = $this->getCacheFile($this->buildKey($key));
Qiang Xue committed
97
		return @filemtime($cacheFile) > time();
98 99
	}

Qiang Xue committed
100 101 102 103
	/**
	 * Retrieves a value from cache with a specified key.
	 * This is the implementation of the method declared in the parent class.
	 * @param string $key a unique key identifying the cached value
104
	 * @return string|boolean the value stored in cache, false if the value is not in the cache or expired.
Qiang Xue committed
105 106 107
	 */
	protected function getValue($key)
	{
108
		$cacheFile = $this->getCacheFile($key);
Qiang Xue committed
109
		if (@filemtime($cacheFile) > time()) {
Qiang Xue committed
110
			return @file_get_contents($cacheFile);
111 112 113
		} else {
			return false;
		}
Qiang Xue committed
114 115 116 117 118 119 120 121 122 123 124
	}

	/**
	 * Stores a value identified by a key in cache.
	 * This is the implementation of the method declared in the parent class.
	 *
	 * @param string $key the key identifying the value to be cached
	 * @param string $value the value to be cached
	 * @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
	 * @return boolean true if the value is successfully stored into cache, false otherwise
	 */
125
	protected function setValue($key, $value, $expire)
Qiang Xue committed
126
	{
127 128
		if ($expire <= 0) {
			$expire = 31536000; // 1 year
Qiang Xue committed
129
		}
130
		$expire += time();
Qiang Xue committed
131

132 133
		$cacheFile = $this->getCacheFile($key);
		if ($this->directoryLevel > 0) {
134
			@FileHelper::createDirectory(dirname($cacheFile), $this->dirMode, true);
Qiang Xue committed
135
		}
136
		if (@file_put_contents($cacheFile, $value, LOCK_EX) !== false) {
137 138 139
			if ($this->fileMode !== null) {
				@chmod($cacheFile, $this->fileMode);
			}
140 141
			return @touch($cacheFile, $expire);
		} else {
Qiang Xue committed
142
			return false;
143
		}
Qiang Xue committed
144 145 146 147 148 149 150 151 152 153 154
	}

	/**
	 * Stores a value identified by a key into cache if the cache does not contain this key.
	 * This is the implementation of the method declared in the parent class.
	 *
	 * @param string $key the key identifying the value to be cached
	 * @param string $value the value to be cached
	 * @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
	 * @return boolean true if the value is successfully stored into cache, false otherwise
	 */
155
	protected function addValue($key, $value, $expire)
Qiang Xue committed
156
	{
157 158
		$cacheFile = $this->getCacheFile($key);
		if (@filemtime($cacheFile) > time()) {
Qiang Xue committed
159
			return false;
160 161
		}
		return $this->setValue($key, $value, $expire);
Qiang Xue committed
162 163 164 165 166 167 168 169 170 171
	}

	/**
	 * Deletes a value with the specified key from cache
	 * This is the implementation of the method declared in the parent class.
	 * @param string $key the key of the value to be deleted
	 * @return boolean if no error happens during deletion
	 */
	protected function deleteValue($key)
	{
172
		$cacheFile = $this->getCacheFile($key);
Qiang Xue committed
173 174 175 176 177 178 179 180 181 182
		return @unlink($cacheFile);
	}

	/**
	 * Returns the cache file path given the cache key.
	 * @param string $key cache key
	 * @return string the cache file path
	 */
	protected function getCacheFile($key)
	{
183 184 185 186 187 188
		if ($this->directoryLevel > 0) {
			$base = $this->cachePath;
			for ($i = 0; $i < $this->directoryLevel; ++$i) {
				if (($prefix = substr($key, $i + $i, 2)) !== false) {
					$base .= DIRECTORY_SEPARATOR . $prefix;
				}
Qiang Xue committed
189
			}
190 191 192
			return $base . DIRECTORY_SEPARATOR . $key . $this->cacheFileSuffix;
		} else {
			return $this->cachePath . DIRECTORY_SEPARATOR . $key . $this->cacheFileSuffix;
Qiang Xue committed
193
		}
194 195 196 197 198 199 200 201 202 203 204
	}

	/**
	 * Deletes all values from cache.
	 * This is the implementation of the method declared in the parent class.
	 * @return boolean whether the flush operation was successful.
	 */
	protected function flushValues()
	{
		$this->gc(true, false);
		return true;
Qiang Xue committed
205 206 207 208
	}

	/**
	 * Removes expired cache files.
209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
	 * @param boolean $force whether to enforce the garbage collection regardless of [[gcProbability]].
	 * Defaults to false, meaning the actual deletion happens with the probability as specified by [[gcProbability]].
	 * @param boolean $expiredOnly whether to removed expired cache files only.
	 * If true, all cache files under [[cachePath]] will be removed.
	 */
	public function gc($force = false, $expiredOnly = true)
	{
		if ($force || mt_rand(0, 1000000) < $this->gcProbability) {
			$this->gcRecursive($this->cachePath, $expiredOnly);
		}
	}

	/**
	 * Recursively removing expired cache files under a directory.
	 * This method is mainly used by [[gc()]].
	 * @param string $path the directory under which expired cache files are removed.
	 * @param boolean $expiredOnly whether to only remove expired cache files. If false, all files
	 * under `$path` will be removed.
Qiang Xue committed
227
	 */
228
	protected function gcRecursive($path, $expiredOnly)
Qiang Xue committed
229
	{
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
		if (($handle = opendir($path)) !== false) {
			while (($file = readdir($handle)) !== false) {
				if ($file[0] === '.') {
					continue;
				}
				$fullPath = $path . DIRECTORY_SEPARATOR . $file;
				if (is_dir($fullPath)) {
					$this->gcRecursive($fullPath, $expiredOnly);
					if (!$expiredOnly) {
						@rmdir($fullPath);
					}
				} elseif (!$expiredOnly || $expiredOnly && @filemtime($fullPath) < time()) {
					@unlink($fullPath);
				}
			}
			closedir($handle);
Qiang Xue committed
246 247 248
		}
	}
}