1d9bb427603cbc83680b7a81a2b91dfb23984a74
[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 extends cache_store implements cache_is_key_aware, cache_is_configurable  {
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 if we should store files within a single directory.
62      * By default we use a nested structure in order to reduce the chance of conflicts and avoid any file system
63      * limitations such as maximum files per directory.
64      * @var bool
65      */
66     protected $singledirectory = false;
68     /**
69      * Set to true when the path should be automatically created if it does not yet exist.
70      * @var bool
71      */
72     protected $autocreate = false;
74     /**
75      * Set to true if a custom path is being used.
76      * @var bool
77      */
78     protected $custompath = false;
80     /**
81      * An array of keys we are sure about presently.
82      * @var array
83      */
84     protected $keys = array();
86     /**
87      * True when the store is ready to be initialised.
88      * @var bool
89      */
90     protected $isready = false;
92     /**
93      * The cache definition this instance has been initialised with.
94      * @var cache_definition
95      */
96     protected $definition;
98     /**
99      * Constructs the store instance.
100      *
101      * Noting that this function is not an initialisation. It is used to prepare the store for use.
102      * The store will be initialised when required and will be provided with a cache_definition at that time.
103      *
104      * @param string $name
105      * @param array $configuration
106      */
107     public function __construct($name, array $configuration = array()) {
108         $this->name = $name;
109         if (array_key_exists('path', $configuration) && $configuration['path'] !== '') {
110             $this->custompath = true;
111             $this->autocreate = !empty($configuration['autocreate']);
112             $path = (string)$configuration['path'];
113             if (!is_dir($path)) {
114                 if ($this->autocreate) {
115                     if (!make_writable_directory($path, false)) {
116                         $path = false;
117                         debugging('Error trying to autocreate file store path. '.$path, DEBUG_DEVELOPER);
118                     }
119                 } else {
120                     $path = false;
121                     debugging('The given file cache store path does not exist. '.$path, DEBUG_DEVELOPER);
122                 }
123             }
124             if ($path !== false && !is_writable($path)) {
125                 $path = false;
126                 debugging('The given file cache store path is not writable. '.$path, DEBUG_DEVELOPER);
127             }
128         } else {
129             $path = make_cache_directory('cachestore_file/'.preg_replace('#[^a-zA-Z0-9\.\-_]+#', '', $name));
130         }
131         $this->isready = $path !== false;
132         $this->path = $path;
133         // Check if we should prescan the directory.
134         if (array_key_exists('prescan', $configuration)) {
135             $this->prescan = (bool)$configuration['prescan'];
136         } else {
137             // Default is no, we should not prescan.
138             $this->prescan = false;
139         }
140         // Check if we should be storing in a single directory.
141         if (array_key_exists('singledirectory', $configuration)) {
142             $this->singledirectory = (bool)$configuration['singledirectory'];
143         } else {
144             // Default: No, we will use multiple directories.
145             $this->singledirectory = false;
146         }
147     }
149     /**
150      * Returns true if this store instance is ready to be used.
151      * @return bool
152      */
153     public function is_ready() {
154         return ($this->path !== null);
155     }
157     /**
158      * Returns true once this instance has been initialised.
159      *
160      * @return bool
161      */
162     public function is_initialised() {
163         return true;
164     }
166     /**
167      * Returns the supported features as a combined int.
168      *
169      * @param array $configuration
170      * @return int
171      */
172     public static function get_supported_features(array $configuration = array()) {
173         $supported = self::SUPPORTS_DATA_GUARANTEE +
174                      self::SUPPORTS_NATIVE_TTL;
175         return $supported;
176     }
178     /**
179      * Returns the supported modes as a combined int.
180      *
181      * @param array $configuration
182      * @return int
183      */
184     public static function get_supported_modes(array $configuration = array()) {
185         return self::MODE_APPLICATION + self::MODE_SESSION;
186     }
188     /**
189      * Returns true if the store requirements are met.
190      *
191      * @return bool
192      */
193     public static function are_requirements_met() {
194         return true;
195     }
197     /**
198      * Returns true if the given mode is supported by this store.
199      *
200      * @param int $mode One of cache_store::MODE_*
201      * @return bool
202      */
203     public static function is_supported_mode($mode) {
204         return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
205     }
207     /**
208      * Initialises the cache.
209      *
210      * Once this has been done the cache is all set to be used.
211      *
212      * @param cache_definition $definition
213      */
214     public function initialise(cache_definition $definition) {
215         $this->definition = $definition;
216         $hash = preg_replace('#[^a-zA-Z0-9]+#', '_', $this->definition->get_id());
217         $this->path .= '/'.$hash;
218         make_writable_directory($this->path);
219         if ($this->prescan && $definition->get_mode() !== self::MODE_REQUEST) {
220             $this->prescan = false;
221         }
222         if ($this->prescan) {
223             $this->prescan_keys();
224         }
225     }
227     /**
228      * Pre-scan the cache to see which keys are present.
229      */
230     protected function prescan_keys() {
231         $files = glob($this->glob_keys_pattern(), GLOB_MARK | GLOB_NOSORT);
232         if (is_array($files)) {
233             foreach ($files as $filename) {
234                 $this->keys[basename($filename)] = filemtime($filename);
235             }
236         }
237     }
239     /**
240      * Gets a pattern suitable for use with glob to find all keys in the cache.
241      * @return string The pattern.
242      */
243     protected function glob_keys_pattern() {
244         if ($this->singledirectory) {
245             return $this->path . '/*.cache';
246         } else {
247             return $this->path . '/*/*.cache';
248         }
249     }
251     /**
252      * Returns the file path to use for the given key.
253      *
254      * @param string $key The key to generate a file path for.
255      * @param bool $create If set to the true the directory structure the key requires will be created.
256      * @return string The full path to the file that stores a particular cache key.
257      */
258     protected function file_path_for_key($key, $create = false) {
259         if ($this->singledirectory) {
260             // Its a single directory, easy, just the store instances path + the file name.
261             return $this->path . '/' . $key . '.cache';
262         } else {
263             // We are using a single subdirectory to achieve 1 level.
264             $subdir = substr($key, 0, 3);
265             $dir = $this->path . '/' . $subdir;
266             if ($create) {
267                 // Create the directory. This function does it recursivily!
268                 make_writable_directory($dir);
269             }
270             return $dir . '/' . $key . '.cache';
271         }
272     }
274     /**
275      * Retrieves an item from the cache store given its key.
276      *
277      * @param string $key The key to retrieve
278      * @return mixed The data that was associated with the key, or false if the key did not exist.
279      */
280     public function get($key) {
281         $filename = $key.'.cache';
282         $file = $this->file_path_for_key($key);
283         $ttl = $this->definition->get_ttl();
284         if ($ttl) {
285             $maxtime = cache::now() - $ttl;
286         }
287         $readfile = false;
288         if ($this->prescan && array_key_exists($key, $this->keys)) {
289             if (!$ttl || $this->keys[$filename] >= $maxtime && file_exists($file)) {
290                 $readfile = true;
291             } else {
292                 $this->delete($key);
293             }
294         } else if (file_exists($file) && (!$ttl || filemtime($file) >= $maxtime)) {
295             $readfile = true;
296         }
297         if (!$readfile) {
298             return false;
299         }
300         // Check the filesize first, likely not needed but important none the less.
301         $filesize = filesize($file);
302         if (!$filesize) {
303             return false;
304         }
305         // Open ensuring the file for writing, truncating it and setting the pointer to the start.
306         if (!$handle = fopen($file, 'rb')) {
307             return false;
308         }
309         // Lock it up!
310         // We don't care if this succeeds or not, on some systems it will, on some it won't, meah either way.
311         flock($handle, LOCK_SH);
312         // HACK ALERT
313         // There is a problem when reading from the file during PHPUNIT tests. For one reason or another the filesize is not correct
314         // Doesn't happen during normal operation, just during unit tests.
315         // Read it.
316         $data = fread($handle, $filesize+128);
317         // Unlock it.
318         flock($handle, LOCK_UN);
319         // Return it unserialised.
320         return $this->prep_data_after_read($data);
321     }
323     /**
324      * Retrieves several items from the cache store in a single transaction.
325      *
326      * 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.
327      *
328      * @param array $keys The array of keys to retrieve
329      * @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
330      *      be set to false.
331      */
332     public function get_many($keys) {
333         $result = array();
334         foreach ($keys as $key) {
335             $result[$key] = $this->get($key);
336         }
337         return $result;
338     }
340     /**
341      * Deletes an item from the cache store.
342      *
343      * @param string $key The key to delete.
344      * @return bool Returns true if the operation was a success, false otherwise.
345      */
346     public function delete($key) {
347         $filename = $key.'.cache';
348         $file = $this->file_path_for_key($key);
350         if (@unlink($file)) {
351             unset($this->keys[$filename]);
352             return true;
353         }
355         return false;
356     }
358     /**
359      * Deletes several keys from the cache in a single action.
360      *
361      * @param array $keys The keys to delete
362      * @return int The number of items successfully deleted.
363      */
364     public function delete_many(array $keys) {
365         $count = 0;
366         foreach ($keys as $key) {
367             if ($this->delete($key)) {
368                 $count++;
369             }
370         }
371         return $count;
372     }
374     /**
375      * Sets an item in the cache given its key and data value.
376      *
377      * @param string $key The key to use.
378      * @param mixed $data The data to set.
379      * @return bool True if the operation was a success false otherwise.
380      */
381     public function set($key, $data) {
382         $this->ensure_path_exists();
383         $filename = $key.'.cache';
384         $file = $this->file_path_for_key($key, true);
385         $result = $this->write_file($file, $this->prep_data_before_save($data));
386         if (!$result) {
387             // Couldn't write the file.
388             return false;
389         }
390         // Record the key if required.
391         if ($this->prescan) {
392             $this->keys[$filename] = cache::now() + 1;
393         }
394         // Return true.. it all worked **miracles**.
395         return true;
396     }
398     /**
399      * Prepares data to be stored in a file.
400      *
401      * @param mixed $data
402      * @return string
403      */
404     protected function prep_data_before_save($data) {
405         return serialize($data);
406     }
408     /**
409      * Prepares the data it has been read from the cache. Undoing what was done in prep_data_before_save.
410      *
411      * @param string $data
412      * @return mixed
413      * @throws coding_exception
414      */
415     protected function prep_data_after_read($data) {
416         $result = @unserialize($data);
417         if ($result === false) {
418             throw new coding_exception('Failed to unserialise data from file. Either failed to read, or failed to write.');
419         }
420         return $result;
421     }
423     /**
424      * Sets many items in the cache in a single transaction.
425      *
426      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
427      *      keys, 'key' and 'value'.
428      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
429      *      sent ... if they care that is.
430      */
431     public function set_many(array $keyvaluearray) {
432         $count = 0;
433         foreach ($keyvaluearray as $pair) {
434             if ($this->set($pair['key'], $pair['value'])) {
435                 $count++;
436             }
437         }
438         return $count;
439     }
441     /**
442      * Checks if the store has a record for the given key and returns true if so.
443      *
444      * @param string $key
445      * @return bool
446      */
447     public function has($key) {
448         $filename = $key.'.cache';
449         $maxtime = cache::now() - $this->definition->get_ttl();
450         if ($this->prescan) {
451             return array_key_exists($filename, $this->keys) && $this->keys[$filename] >= $maxtime;
452         }
453         $file = $this->file_path_for_key($key);
454         return (file_exists($file) && ($this->definition->get_ttl() == 0 || filemtime($file) >= $maxtime));
455     }
457     /**
458      * Returns true if the store contains records for all of the given keys.
459      *
460      * @param array $keys
461      * @return bool
462      */
463     public function has_all(array $keys) {
464         foreach ($keys as $key) {
465             if (!$this->has($key)) {
466                 return false;
467             }
468         }
469         return true;
470     }
472     /**
473      * Returns true if the store contains records for any of the given keys.
474      *
475      * @param array $keys
476      * @return bool
477      */
478     public function has_any(array $keys) {
479         foreach ($keys as $key) {
480             if ($this->has($key)) {
481                 return true;
482             }
483         }
484         return false;
485     }
487     /**
488      * Purges the cache deleting all items within it.
489      *
490      * @return boolean True on success. False otherwise.
491      */
492     public function purge() {
493         $files = glob($this->glob_keys_pattern(), GLOB_MARK | GLOB_NOSORT);
494         if (is_array($files)) {
495             foreach ($files as $filename) {
496                 @unlink($filename);
497             }
498         }
499         $this->keys = array();
500         return true;
501     }
503     /**
504      * Given the data from the add instance form this function creates a configuration array.
505      *
506      * @param stdClass $data
507      * @return array
508      */
509     public static function config_get_configuration_array($data) {
510         $config = array();
512         if (isset($data->path)) {
513             $config['path'] = $data->path;
514         }
515         if (isset($data->autocreate)) {
516             $config['autocreate'] = $data->autocreate;
517         }
518         if (isset($data->singledirectory)) {
519             $config['singledirectory'] = $data->singledirectory;
520         }
521         if (isset($data->prescan)) {
522             $config['prescan'] = $data->prescan;
523         }
525         return $config;
526     }
528     /**
529      * Allows the cache store to set its data against the edit form before it is shown to the user.
530      *
531      * @param moodleform $editform
532      * @param array $config
533      */
534     public static function config_set_edit_form_data(moodleform $editform, array $config) {
535         $data = array();
536         if (!empty($config['path'])) {
537             $data['path'] = $config['path'];
538         }
539         if (isset($config['autocreate'])) {
540             $data['autocreate'] = (bool)$config['autocreate'];
541         }
542         if (isset($config['singledirectory'])) {
543             $data['singledirectory'] = (bool)$config['singledirectory'];
544         }
545         if (isset($config['prescan'])) {
546             $data['prescan'] = (bool)$config['prescan'];
547         }
548         $editform->set_data($data);
549     }
551     /**
552      * Checks to make sure that the path for the file cache exists.
553      *
554      * @return bool
555      * @throws coding_exception
556      */
557     protected function ensure_path_exists() {
558         if (!is_writable($this->path)) {
559             if ($this->custompath && !$this->autocreate) {
560                 throw new coding_exception('File store path does not exist. It must exist and be writable by the web server.');
561             }
562             if (!make_writable_directory($this->path, false)) {
563                 throw new coding_exception('File store path does not exist and can not be created.');
564             }
565         }
566         return true;
567     }
569     /**
570      * Performs any necessary clean up when the store instance is being deleted.
571      *
572      * 1. Purges the cache directory.
573      * 2. Deletes the directory we created for this cache instances data.
574      */
575     public function cleanup() {
576         $this->purge();
577         @rmdir($this->path);
578     }
580     /**
581      * Generates an instance of the cache store that can be used for testing.
582      *
583      * Returns an instance of the cache store, or false if one cannot be created.
584      *
585      * @param cache_definition $definition
586      * @return cachestore_file
587      */
588     public static function initialise_test_instance(cache_definition $definition) {
589         $name = 'File test';
590         $path = make_cache_directory('cachestore_file_test');
591         $cache = new cachestore_file($name, array('path' => $path));
592         $cache->initialise($definition);
593         return $cache;
594     }
596     /**
597      * Writes your madness to a file.
598      *
599      * There are several things going on in this function to try to ensure what we don't end up with partial writes etc.
600      *   1. Files for writing are opened with the mode xb, the file must be created and can not already exist.
601      *   2. Renaming, data is written to a temporary file, where it can be verified using md5 and is then renamed.
602      *
603      * @param string $file Absolute file path
604      * @param string $content The content to write.
605      * @return bool
606      */
607     protected function write_file($file, $content) {
608         // Generate a temp file that is going to be unique. We'll rename it at the end to the desired file name.
609         // in this way we avoid partial writes.
610         $path = dirname($file);
611         while (true) {
612             $tempfile = $path.'/'.uniqid(sesskey().'.', true) . '.temp';
613             if (!file_exists($tempfile)) {
614                 break;
615             }
616         }
618         // Open the file with mode=x. This acts to create and open the file for writing only.
619         // If the file already exists this will return false.
620         // We also force binary.
621         $handle = @fopen($tempfile, 'xb+');
622         if ($handle === false) {
623             // File already exists... lock already exists, return false.
624             return false;
625         }
626         fwrite($handle, $content);
627         fflush($handle);
628         // Close the handle, we're done.
629         fclose($handle);
631         if (md5_file($tempfile) !== md5($content)) {
632             // The md5 of the content of the file must match the md5 of the content given to be written.
633             @unlink($tempfile);
634             return false;
635         }
637         // Finally rename the temp file to the desired file, returning the true|false result.
638         $result = rename($tempfile, $file);
639         if (!$result) {
640             // Failed to rename, don't leave files lying around.
641             @unlink($tempfile);
642         }
643         return $result;
644     }
646     /**
647      * Returns the name of this instance.
648      * @return string
649      */
650     public function my_name() {
651         return $this->name;
652     }