90ed0e496878cd992cfbd30a062c68e64e44811e
[moodle.git] / cache / stores / file / lib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * The library file for the file cache store.
19  *
20  * This file is part of the file cache store, it contains the API for interacting with an instance of the store.
21  * This is used as a default cache store within the Cache API. It should never be deleted.
22  *
23  * @package    cachestore_file
24  * @category   cache
25  * @copyright  2012 Sam Hemelryk
26  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
29 /**
30  * The file store class.
31  *
32  * Configuration options
33  *      path:           string: path to the cache directory, if left empty one will be created in the cache directory
34  *      autocreate:     true, false
35  *      prescan:        true, false
36  *
37  * @copyright  2012 Sam Hemelryk
38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  */
40 class cachestore_file implements cache_store, cache_is_key_aware {
42     /**
43      * The name of the store.
44      * @var string
45      */
46     protected $name;
48     /**
49      * The path to use for the file storage.
50      * @var string
51      */
52     protected $path = null;
54     /**
55      * Set to true when a prescan has been performed.
56      * @var bool
57      */
58     protected $prescan = false;
60     /**
61      * Set to true when the path should be automatically created if it does not yet exist.
62      * @var bool
63      */
64     protected $autocreate = false;
66     /**
67      * Set to true if a custom path is being used.
68      * @var bool
69      */
70     protected $custompath = false;
72     /**
73      * An array of keys we are sure about presently.
74      * @var array
75      */
76     protected $keys = array();
78     /**
79      * True when the store is ready to be initialised.
80      * @var bool
81      */
82     protected $isready = false;
84     /**
85      * The cache definition this instance has been initialised with.
86      * @var cache_definition
87      */
88     protected $definition;
90     /**
91      * Constructs the store instance.
92      *
93      * Noting that this function is not an initialisation. It is used to prepare the store for use.
94      * The store will be initialised when required and will be provided with a cache_definition at that time.
95      *
96      * @param string $name
97      * @param array $configuration
98      */
99     public function __construct($name, array $configuration = array()) {
100         $this->name = $name;
101         if (array_key_exists('path', $configuration) && $configuration['path'] !== '') {
102             $this->custompath = true;
103             $this->autocreate = !empty($configuration['autocreate']);
104             $path = (string)$configuration['path'];
105             if (!is_dir($path)) {
106                 if ($this->autocreate) {
107                     if (!make_writable_directory($path, false)) {
108                         $path = false;
109                         debugging('Error trying to autocreate file store path. '.$path, DEBUG_DEVELOPER);
110                     }
111                 } else {
112                     $path = false;
113                     debugging('The given file cache store path does not exist. '.$path, DEBUG_DEVELOPER);
114                 }
115             }
116             if ($path !== false && !is_writable($path)) {
117                 $path = false;
118                 debugging('The given file cache store path is not writable. '.$path, DEBUG_DEVELOPER);
119             }
120         } else {
121             $path = make_cache_directory('cachestore_file/'.preg_replace('#[^a-zA-Z0-9\.\-_]+#', '', $name));
122         }
123         $this->isready = $path !== false;
124         $this->path = $path;
125         $this->prescan = array_key_exists('prescan', $configuration) ? (bool)$configuration['prescan'] : false;
126     }
128     /**
129      * Returns true if this store instance is ready to be used.
130      * @return bool
131      */
132     public function is_ready() {
133         return ($this->path !== null);
134     }
136     /**
137      * Returns true once this instance has been initialised.
138      *
139      * @return bool
140      */
141     public function is_initialised() {
142         return true;
143     }
145     /**
146      * Returns the supported features as a combined int.
147      *
148      * @param array $configuration
149      * @return int
150      */
151     public static function get_supported_features(array $configuration = array()) {
152         $supported = self::SUPPORTS_DATA_GUARANTEE +
153                      self::SUPPORTS_NATIVE_TTL;
154         return $supported;
155     }
157     /**
158      * Returns the supported modes as a combined int.
159      *
160      * @param array $configuration
161      * @return int
162      */
163     public static function get_supported_modes(array $configuration = array()) {
164         return self::MODE_APPLICATION + self::MODE_SESSION;
165     }
167     /**
168      * Returns true if the store requirements are met.
169      *
170      * @return bool
171      */
172     public static function are_requirements_met() {
173         return true;
174     }
176     /**
177      * Returns true if the given mode is supported by this store.
178      *
179      * @param int $mode One of cache_store::MODE_*
180      * @return bool
181      */
182     public static function is_supported_mode($mode) {
183         return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
184     }
186     /**
187      * Returns true if the store instance supports multiple identifiers.
188      *
189      * @return bool
190      */
191     public function supports_multiple_indentifiers() {
192         return false;
193     }
195     /**
196      * Returns true if the store instance guarantees data.
197      *
198      * @return bool
199      */
200     public function supports_data_guarantee() {
201         return true;
202     }
204     /**
205      * Returns true if the store instance supports native ttl.
206      *
207      * @return bool
208      */
209     public function supports_native_ttl() {
210         return true;
211     }
213     /**
214      * Initialises the cache.
215      *
216      * Once this has been done the cache is all set to be used.
217      *
218      * @param cache_definition $definition
219      */
220     public function initialise(cache_definition $definition) {
221         $this->definition = $definition;
222         $hash = preg_replace('#[^a-zA-Z0-9]+#', '_', $this->definition->get_id());
223         $this->path .= '/'.$hash;
224         make_writable_directory($this->path);
225         if ($this->prescan && $definition->get_mode() !== self::MODE_REQUEST) {
226             $this->prescan = false;
227         }
228         if ($this->prescan) {
229             $pattern = $this->path.'/*.cache';
230             foreach (glob($pattern, GLOB_MARK | GLOB_NOSORT) as $filename) {
231                 $this->keys[basename($filename)] = filemtime($filename);
232             }
233         }
234     }
236     /**
237      * Retrieves an item from the cache store given its key.
238      *
239      * @param string $key The key to retrieve
240      * @return mixed The data that was associated with the key, or false if the key did not exist.
241      */
242     public function get($key) {
243         $filename = $key.'.cache';
244         $file = $this->path.'/'.$filename;
245         $ttl = $this->definition->get_ttl();
246         if ($ttl) {
247             $maxtime = cache::now() - $ttl;
248         }
249         $readfile = false;
250         if ($this->prescan && array_key_exists($key, $this->keys)) {
251             if (!$ttl || $this->keys[$filename] >= $maxtime && file_exists($file)) {
252                 $readfile = true;
253             } else {
254                 $this->delete($key);
255             }
256         } else if (file_exists($file) && (!$ttl || filemtime($file) >= $maxtime)) {
257             $readfile = true;
258         }
259         if (!$readfile) {
260             return false;
261         }
262         // Check the filesize first, likely not needed but important none the less.
263         $filesize = filesize($file);
264         if (!$filesize) {
265             return false;
266         }
267         // Open ensuring the file for writing, truncating it and setting the pointer to the start.
268         if (!$handle = fopen($file, 'rb')) {
269             return false;
270         }
271         // Lock it up!
272         // We don't care if this succeeds or not, on some systems it will, on some it won't, meah either way.
273         flock($handle, LOCK_SH);
274         // HACK ALERT
275         // There is a problem when reading from the file during PHPUNIT tests. For one reason or another the filesize is not correct
276         // Doesn't happen during normal operation, just during unit tests.
277         // Read it.
278         $data = fread($handle, $filesize+128);
279         // Unlock it.
280         flock($handle, LOCK_UN);
281         // Return it unserialised.
282         return $this->prep_data_after_read($data);
283     }
285     /**
286      * Retrieves several items from the cache store in a single transaction.
287      *
288      * If not all of the items are available in the cache then the data value for those that are missing will be set to false.
289      *
290      * @param array $keys The array of keys to retrieve
291      * @return array An array of items from the cache. There will be an item for each key, those that were not in the store will
292      *      be set to false.
293      */
294     public function get_many($keys) {
295         $result = array();
296         foreach ($keys as $key) {
297             $result[$key] = $this->get($key);
298         }
299         return $result;
300     }
302     /**
303      * Deletes an item from the cache store.
304      *
305      * @param string $key The key to delete.
306      * @return bool Returns true if the operation was a success, false otherwise.
307      */
308     public function delete($key) {
309         $filename = $key.'.cache';
310         $file = $this->path.'/'.$filename;
312         if (@unlink($file)) {
313             unset($this->keys[$filename]);
314             return true;
315         }
317         return false;
318     }
320     /**
321      * Deletes several keys from the cache in a single action.
322      *
323      * @param array $keys The keys to delete
324      * @return int The number of items successfully deleted.
325      */
326     public function delete_many(array $keys) {
327         $count = 0;
328         foreach ($keys as $key) {
329             if ($this->delete($key)) {
330                 $count++;
331             }
332         }
333         return $count;
334     }
336     /**
337      * Sets an item in the cache given its key and data value.
338      *
339      * @param string $key The key to use.
340      * @param mixed $data The data to set.
341      * @return bool True if the operation was a success false otherwise.
342      */
343     public function set($key, $data) {
344         $this->ensure_path_exists();
345         $filename = $key.'.cache';
346         $file = $this->path.'/'.$filename;
347         $result = $this->write_file($file, $this->prep_data_before_save($data));
348         if (!$result) {
349             // Couldn't write the file.
350             return false;
351         }
352         // Record the key if required.
353         if ($this->prescan) {
354             $this->keys[$filename] = cache::now() + 1;
355         }
356         // Return true.. it all worked **miracles**.
357         return true;
358     }
360     /**
361      * Prepares data to be stored in a file.
362      *
363      * @param mixed $data
364      * @return string
365      */
366     protected function prep_data_before_save($data) {
367         return serialize($data);
368     }
370     /**
371      * Prepares the data it has been read from the cache. Undoing what was done in prep_data_before_save.
372      *
373      * @param string $data
374      * @return mixed
375      * @throws coding_exception
376      */
377     protected function prep_data_after_read($data) {
378         $result = @unserialize($data);
379         if ($result === false) {
380             throw new coding_exception('Failed to unserialise data from file. Either failed to read, or failed to write.');
381         }
382         return $result;
383     }
385     /**
386      * Sets many items in the cache in a single transaction.
387      *
388      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
389      *      keys, 'key' and 'value'.
390      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
391      *      sent ... if they care that is.
392      */
393     public function set_many(array $keyvaluearray) {
394         $count = 0;
395         foreach ($keyvaluearray as $pair) {
396             if ($this->set($pair['key'], $pair['value'])) {
397                 $count++;
398             }
399         }
400         return $count;
401     }
403     /**
404      * Checks if the store has a record for the given key and returns true if so.
405      *
406      * @param string $key
407      * @return bool
408      */
409     public function has($key) {
410         $filename = $key.'.cache';
411         $file = $this->path.'/'.$key.'.cache';
412         $maxtime = cache::now() - $this->definition->get_ttl();
413         if ($this->prescan) {
414             return array_key_exists($filename, $this->keys) && $this->keys[$filename] >= $maxtime;
415         }
416         return (file_exists($file) && ($this->definition->get_ttl() == 0 || filemtime($file) >= $maxtime));
417     }
419     /**
420      * Returns true if the store contains records for all of the given keys.
421      *
422      * @param array $keys
423      * @return bool
424      */
425     public function has_all(array $keys) {
426         foreach ($keys as $key) {
427             if (!$this->has($key)) {
428                 return false;
429             }
430         }
431         return true;
432     }
434     /**
435      * Returns true if the store contains records for any of the given keys.
436      *
437      * @param array $keys
438      * @return bool
439      */
440     public function has_any(array $keys) {
441         foreach ($keys as $key) {
442             if ($this->has($key)) {
443                 return true;
444             }
445         }
446         return false;
447     }
449     /**
450      * Purges the cache deleting all items within it.
451      *
452      * @return boolean True on success. False otherwise.
453      */
454     public function purge() {
455         $pattern = $this->path.'/*.cache';
456         foreach (glob($pattern, GLOB_MARK | GLOB_NOSORT) as $filename) {
457             @unlink($filename);
458         }
459         $this->keys = array();
460         return true;
461     }
463     /**
464      * Checks to make sure that the path for the file cache exists.
465      *
466      * @return bool
467      * @throws coding_exception
468      */
469     protected function ensure_path_exists() {
470         if (!is_writable($this->path)) {
471             if ($this->custompath && !$this->autocreate) {
472                 throw new coding_exception('File store path does not exist. It must exist and be writable by the web server.');
473             }
474             if (!make_writable_directory($this->path, false)) {
475                 throw new coding_exception('File store path does not exist and can not be created.');
476             }
477         }
478         return true;
479     }
481     /**
482      * Returns true if the user can add an instance of the store plugin.
483      *
484      * @return bool
485      */
486     public static function can_add_instance() {
487         return true;
488     }
490     /**
491      * Performs any necessary clean up when the store instance is being deleted.
492      *
493      * 1. Purges the cache directory.
494      * 2. Deletes the directory we created for this cache instances data.
495      */
496     public function cleanup() {
497         $this->purge();
498         @rmdir($this->path);
499     }
501     /**
502      * Generates an instance of the cache store that can be used for testing.
503      *
504      * Returns an instance of the cache store, or false if one cannot be created.
505      *
506      * @param cache_definition $definition
507      * @return cachestore_file
508      */
509     public static function initialise_test_instance(cache_definition $definition) {
510         $name = 'File test';
511         $path = make_cache_directory('cachestore_file_test');
512         $cache = new cachestore_file($name, array('path' => $path));
513         $cache->initialise($definition);
514         return $cache;
515     }
517     /**
518      * Writes your madness to a file.
519      *
520      * There are several things going on in this function to try to ensure what we don't end up with partial writes etc.
521      *   1. Files for writing are opened with the mode xb, the file must be created and can not already exist.
522      *   2. Renaming, data is written to a temporary file, where it can be verified using md5 and is then renamed.
523      *
524      * @param string $file Absolute file path
525      * @param string $content The content to write.
526      * @return bool
527      */
528     protected function write_file($file, $content) {
529         // Generate a temp file that is going to be unique. We'll rename it at the end to the desired file name.
530         // in this way we avoid partial writes.
531         $path = dirname($file);
532         while (true) {
533             $tempfile = $path.'/'.uniqid(sesskey().'.', true) . '.temp';
534             if (!file_exists($tempfile)) {
535                 break;
536             }
537         }
539         // Open the file with mode=x. This acts to create and open the file for writing only.
540         // If the file already exists this will return false.
541         // We also force binary.
542         $handle = @fopen($tempfile, 'xb+');
543         if ($handle === false) {
544             // File already exists... lock already exists, return false.
545             return false;
546         }
547         fwrite($handle, $content);
548         fflush($handle);
549         // Close the handle, we're done.
550         fclose($handle);
552         if (md5_file($tempfile) !== md5($content)) {
553             // The md5 of the content of the file must match the md5 of the content given to be written.
554             @unlink($tempfile);
555             return false;
556         }
558         // Finally rename the temp file to the desired file, returning the true|false result.
559         $result = rename($tempfile, $file);
560         if (!$result) {
561             // Failed to rename, don't leave files lying around.
562             @unlink($tempfile);
563         }
564         return $result;
565     }
567     /**
568      * Returns the name of this instance.
569      * @return string
570      */
571     public function my_name() {
572         return $this->name;
573     }