Merge branch 'MDL-38505' of git://github.com/jmvedrine/moodle
[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, cache_is_searchable  {
42     /**
43      * The name of the store.
44      * @var string
45      */
46     protected $name;
48     /**
49      * The path used to store files for this store and the definition it was initialised with.
50      * @var string
51      */
52     protected $path = false;
54     /**
55      * The path in which definition specific sub directories will be created for caching.
56      * @var string
57      */
58     protected $filestorepath = false;
60     /**
61      * Set to true when a prescan has been performed.
62      * @var bool
63      */
64     protected $prescan = false;
66     /**
67      * Set to true if we should store files within a single directory.
68      * By default we use a nested structure in order to reduce the chance of conflicts and avoid any file system
69      * limitations such as maximum files per directory.
70      * @var bool
71      */
72     protected $singledirectory = false;
74     /**
75      * Set to true when the path should be automatically created if it does not yet exist.
76      * @var bool
77      */
78     protected $autocreate = false;
80     /**
81      * Set to true if a custom path is being used.
82      * @var bool
83      */
84     protected $custompath = false;
86     /**
87      * An array of keys we are sure about presently.
88      * @var array
89      */
90     protected $keys = array();
92     /**
93      * True when the store is ready to be initialised.
94      * @var bool
95      */
96     protected $isready = false;
98     /**
99      * The cache definition this instance has been initialised with.
100      * @var cache_definition
101      */
102     protected $definition;
104     /**
105      * A reference to the global $CFG object.
106      *
107      * You may be asking yourself why on earth this is here, but there is a good reason.
108      * By holding onto a reference of the $CFG object we can be absolutely sure that it won't be destroyed before
109      * we are done with it.
110      * This makes it possible to use a cache within a destructor method for the purposes of
111      * delayed writes. Like how the session mechanisms work.
112      *
113      * @var stdClass
114      */
115     private $cfg = null;
117     /**
118      * Constructs the store instance.
119      *
120      * Noting that this function is not an initialisation. It is used to prepare the store for use.
121      * The store will be initialised when required and will be provided with a cache_definition at that time.
122      *
123      * @param string $name
124      * @param array $configuration
125      */
126     public function __construct($name, array $configuration = array()) {
127         global $CFG;
129         if (isset($CFG)) {
130             // Hold onto a reference of the global $CFG object.
131             $this->cfg = $CFG;
132         }
134         $this->name = $name;
135         if (array_key_exists('path', $configuration) && $configuration['path'] !== '') {
136             $this->custompath = true;
137             $this->autocreate = !empty($configuration['autocreate']);
138             $path = (string)$configuration['path'];
139             if (!is_dir($path)) {
140                 if ($this->autocreate) {
141                     if (!make_writable_directory($path, false)) {
142                         $path = false;
143                         debugging('Error trying to autocreate file store path. '.$path, DEBUG_DEVELOPER);
144                     }
145                 } else {
146                     $path = false;
147                     debugging('The given file cache store path does not exist. '.$path, DEBUG_DEVELOPER);
148                 }
149             }
150             if ($path !== false && !is_writable($path)) {
151                 $path = false;
152                 debugging('The file cache store path is not writable for `'.$name.'`', DEBUG_DEVELOPER);
153             }
154         } else {
155             $path = make_cache_directory('cachestore_file/'.preg_replace('#[^a-zA-Z0-9\.\-_]+#', '', $name));
156         }
157         $this->isready = $path !== false;
158         $this->filestorepath = $path;
159         // This will be updated once the store has been initialised for a definition.
160         $this->path = $path;
162         // Check if we should prescan the directory.
163         if (array_key_exists('prescan', $configuration)) {
164             $this->prescan = (bool)$configuration['prescan'];
165         } else {
166             // Default is no, we should not prescan.
167             $this->prescan = false;
168         }
169         // Check if we should be storing in a single directory.
170         if (array_key_exists('singledirectory', $configuration)) {
171             $this->singledirectory = (bool)$configuration['singledirectory'];
172         } else {
173             // Default: No, we will use multiple directories.
174             $this->singledirectory = false;
175         }
176     }
178     /**
179      * Performs any necessary operation when the file store instance has been created.
180      */
181     public function instance_created() {
182         if ($this->isready && !$this->prescan) {
183             // It is supposed the store instance to expect an empty folder.
184             $this->purge_all_definitions();
185         }
186     }
188     /**
189      * Returns true if this store instance is ready to be used.
190      * @return bool
191      */
192     public function is_ready() {
193         return $this->isready;
194     }
196     /**
197      * Returns true once this instance has been initialised.
198      *
199      * @return bool
200      */
201     public function is_initialised() {
202         return true;
203     }
205     /**
206      * Returns the supported features as a combined int.
207      *
208      * @param array $configuration
209      * @return int
210      */
211     public static function get_supported_features(array $configuration = array()) {
212         $supported = self::SUPPORTS_DATA_GUARANTEE +
213                      self::SUPPORTS_NATIVE_TTL +
214                      self::IS_SEARCHABLE;
215         return $supported;
216     }
218     /**
219      * Returns false as this store does not support multiple identifiers.
220      * (This optional function is a performance optimisation; it must be
221      * consistent with the value from get_supported_features.)
222      *
223      * @return bool False
224      */
225     public function supports_multiple_identifiers() {
226         return false;
227     }
229     /**
230      * Returns the supported modes as a combined int.
231      *
232      * @param array $configuration
233      * @return int
234      */
235     public static function get_supported_modes(array $configuration = array()) {
236         return self::MODE_APPLICATION + self::MODE_SESSION;
237     }
239     /**
240      * Returns true if the store requirements are met.
241      *
242      * @return bool
243      */
244     public static function are_requirements_met() {
245         return true;
246     }
248     /**
249      * Returns true if the given mode is supported by this store.
250      *
251      * @param int $mode One of cache_store::MODE_*
252      * @return bool
253      */
254     public static function is_supported_mode($mode) {
255         return ($mode === self::MODE_APPLICATION || $mode === self::MODE_SESSION);
256     }
258     /**
259      * Initialises the cache.
260      *
261      * Once this has been done the cache is all set to be used.
262      *
263      * @param cache_definition $definition
264      */
265     public function initialise(cache_definition $definition) {
266         $this->definition = $definition;
267         $hash = preg_replace('#[^a-zA-Z0-9]+#', '_', $this->definition->get_id());
268         $this->path = $this->filestorepath.'/'.$hash;
269         make_writable_directory($this->path, false);
270         if ($this->prescan && $definition->get_mode() !== self::MODE_REQUEST) {
271             $this->prescan = false;
272         }
273         if ($this->prescan) {
274             $this->prescan_keys();
275         }
276     }
278     /**
279      * Pre-scan the cache to see which keys are present.
280      */
281     protected function prescan_keys() {
282         $files = glob($this->glob_keys_pattern(), GLOB_MARK | GLOB_NOSORT);
283         if (is_array($files)) {
284             foreach ($files as $filename) {
285                 $this->keys[basename($filename)] = filemtime($filename);
286             }
287         }
288     }
290     /**
291      * Gets a pattern suitable for use with glob to find all keys in the cache.
292      *
293      * @param string $prefix A prefix to use.
294      * @return string The pattern.
295      */
296     protected function glob_keys_pattern($prefix = '') {
297         if ($this->singledirectory) {
298             return $this->path . '/'.$prefix.'*.cache';
299         } else {
300             return $this->path . '/*/'.$prefix.'*.cache';
301         }
302     }
304     /**
305      * Returns the file path to use for the given key.
306      *
307      * @param string $key The key to generate a file path for.
308      * @param bool $create If set to the true the directory structure the key requires will be created.
309      * @return string The full path to the file that stores a particular cache key.
310      */
311     protected function file_path_for_key($key, $create = false) {
312         if ($this->singledirectory) {
313             // Its a single directory, easy, just the store instances path + the file name.
314             return $this->path . '/' . $key . '.cache';
315         } else {
316             // We are using a single subdirectory to achieve 1 level.
317            // We suffix the subdir so it does not clash with any windows
318            // reserved filenames like 'con'.
319             $subdir = substr($key, 0, 3) . '-cache';
320             $dir = $this->path . '/' . $subdir;
321             if ($create) {
322                 // Create the directory. This function does it recursivily!
323                 make_writable_directory($dir, false);
324             }
325             return $dir . '/' . $key . '.cache';
326         }
327     }
329     /**
330      * Retrieves an item from the cache store given its key.
331      *
332      * @param string $key The key to retrieve
333      * @return mixed The data that was associated with the key, or false if the key did not exist.
334      */
335     public function get($key) {
336         $filename = $key.'.cache';
337         $file = $this->file_path_for_key($key);
338         $ttl = $this->definition->get_ttl();
339         $maxtime = 0;
340         if ($ttl) {
341             $maxtime = cache::now() - $ttl;
342         }
343         $readfile = false;
344         if ($this->prescan && array_key_exists($key, $this->keys)) {
345             if (!$ttl || $this->keys[$filename] >= $maxtime && file_exists($file)) {
346                 $readfile = true;
347             } else {
348                 $this->delete($key);
349             }
350         } else if (file_exists($file) && (!$ttl || filemtime($file) >= $maxtime)) {
351             $readfile = true;
352         }
353         if (!$readfile) {
354             return false;
355         }
356         // Check the filesize first, likely not needed but important none the less.
357         $filesize = filesize($file);
358         if (!$filesize) {
359             return false;
360         }
361         // Open ensuring the file for writing, truncating it and setting the pointer to the start.
362         if (!$handle = fopen($file, 'rb')) {
363             return false;
364         }
365         // Lock it up!
366         // We don't care if this succeeds or not, on some systems it will, on some it won't, meah either way.
367         flock($handle, LOCK_SH);
368         // HACK ALERT
369         // There is a problem when reading from the file during PHPUNIT tests. For one reason or another the filesize is not correct
370         // Doesn't happen during normal operation, just during unit tests.
371         // Read it.
372         $data = fread($handle, $filesize+128);
373         // Unlock it.
374         flock($handle, LOCK_UN);
375         // Return it unserialised.
376         return $this->prep_data_after_read($data);
377     }
379     /**
380      * Retrieves several items from the cache store in a single transaction.
381      *
382      * 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.
383      *
384      * @param array $keys The array of keys to retrieve
385      * @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
386      *      be set to false.
387      */
388     public function get_many($keys) {
389         $result = array();
390         foreach ($keys as $key) {
391             $result[$key] = $this->get($key);
392         }
393         return $result;
394     }
396     /**
397      * Deletes an item from the cache store.
398      *
399      * @param string $key The key to delete.
400      * @return bool Returns true if the operation was a success, false otherwise.
401      */
402     public function delete($key) {
403         $filename = $key.'.cache';
404         $file = $this->file_path_for_key($key);
405         if (@unlink($file)) {
406             unset($this->keys[$filename]);
407             return true;
408         }
410         return false;
411     }
413     /**
414      * Deletes several keys from the cache in a single action.
415      *
416      * @param array $keys The keys to delete
417      * @return int The number of items successfully deleted.
418      */
419     public function delete_many(array $keys) {
420         $count = 0;
421         foreach ($keys as $key) {
422             if ($this->delete($key)) {
423                 $count++;
424             }
425         }
426         return $count;
427     }
429     /**
430      * Sets an item in the cache given its key and data value.
431      *
432      * @param string $key The key to use.
433      * @param mixed $data The data to set.
434      * @return bool True if the operation was a success false otherwise.
435      */
436     public function set($key, $data) {
437         $this->ensure_path_exists();
438         $filename = $key.'.cache';
439         $file = $this->file_path_for_key($key, true);
440         $result = $this->write_file($file, $this->prep_data_before_save($data));
441         if (!$result) {
442             // Couldn't write the file.
443             return false;
444         }
445         // Record the key if required.
446         if ($this->prescan) {
447             $this->keys[$filename] = cache::now() + 1;
448         }
449         // Return true.. it all worked **miracles**.
450         return true;
451     }
453     /**
454      * Prepares data to be stored in a file.
455      *
456      * @param mixed $data
457      * @return string
458      */
459     protected function prep_data_before_save($data) {
460         return serialize($data);
461     }
463     /**
464      * Prepares the data it has been read from the cache. Undoing what was done in prep_data_before_save.
465      *
466      * @param string $data
467      * @return mixed
468      * @throws coding_exception
469      */
470     protected function prep_data_after_read($data) {
471         $result = @unserialize($data);
472         if ($result === false) {
473             throw new coding_exception('Failed to unserialise data from file. Either failed to read, or failed to write.');
474         }
475         return $result;
476     }
478     /**
479      * Sets many items in the cache in a single transaction.
480      *
481      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
482      *      keys, 'key' and 'value'.
483      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
484      *      sent ... if they care that is.
485      */
486     public function set_many(array $keyvaluearray) {
487         $count = 0;
488         foreach ($keyvaluearray as $pair) {
489             if ($this->set($pair['key'], $pair['value'])) {
490                 $count++;
491             }
492         }
493         return $count;
494     }
496     /**
497      * Checks if the store has a record for the given key and returns true if so.
498      *
499      * @param string $key
500      * @return bool
501      */
502     public function has($key) {
503         $filename = $key.'.cache';
504         $maxtime = cache::now() - $this->definition->get_ttl();
505         if ($this->prescan) {
506             return array_key_exists($filename, $this->keys) && $this->keys[$filename] >= $maxtime;
507         }
508         $file = $this->file_path_for_key($key);
509         return (file_exists($file) && ($this->definition->get_ttl() == 0 || filemtime($file) >= $maxtime));
510     }
512     /**
513      * Returns true if the store contains records for all of the given keys.
514      *
515      * @param array $keys
516      * @return bool
517      */
518     public function has_all(array $keys) {
519         foreach ($keys as $key) {
520             if (!$this->has($key)) {
521                 return false;
522             }
523         }
524         return true;
525     }
527     /**
528      * Returns true if the store contains records for any of the given keys.
529      *
530      * @param array $keys
531      * @return bool
532      */
533     public function has_any(array $keys) {
534         foreach ($keys as $key) {
535             if ($this->has($key)) {
536                 return true;
537             }
538         }
539         return false;
540     }
542     /**
543      * Purges the cache definition deleting all the items within it.
544      *
545      * @return boolean True on success. False otherwise.
546      */
547     public function purge() {
548         if ($this->isready) {
549             $files = glob($this->glob_keys_pattern(), GLOB_MARK | GLOB_NOSORT);
550             if (is_array($files)) {
551                 foreach ($files as $filename) {
552                     @unlink($filename);
553                 }
554             }
555             $this->keys = array();
556         }
557         return true;
558     }
560     /**
561      * Purges all the cache definitions deleting all items within them.
562      *
563      * @return boolean True on success. False otherwise.
564      */
565     protected function purge_all_definitions() {
566         // Warning: limit the deletion to what file store is actually able
567         // to create using the internal {@link purge()} providing the
568         // {@link $path} with a wildcard to perform a purge action over all the definitions.
569         $currpath = $this->path;
570         $this->path = $this->filestorepath.'/*';
571         $result = $this->purge();
572         $this->path = $currpath;
573         return $result;
574     }
576     /**
577      * Given the data from the add instance form this function creates a configuration array.
578      *
579      * @param stdClass $data
580      * @return array
581      */
582     public static function config_get_configuration_array($data) {
583         $config = array();
585         if (isset($data->path)) {
586             $config['path'] = $data->path;
587         }
588         if (isset($data->autocreate)) {
589             $config['autocreate'] = $data->autocreate;
590         }
591         if (isset($data->singledirectory)) {
592             $config['singledirectory'] = $data->singledirectory;
593         }
594         if (isset($data->prescan)) {
595             $config['prescan'] = $data->prescan;
596         }
598         return $config;
599     }
601     /**
602      * Allows the cache store to set its data against the edit form before it is shown to the user.
603      *
604      * @param moodleform $editform
605      * @param array $config
606      */
607     public static function config_set_edit_form_data(moodleform $editform, array $config) {
608         $data = array();
609         if (!empty($config['path'])) {
610             $data['path'] = $config['path'];
611         }
612         if (isset($config['autocreate'])) {
613             $data['autocreate'] = (bool)$config['autocreate'];
614         }
615         if (isset($config['singledirectory'])) {
616             $data['singledirectory'] = (bool)$config['singledirectory'];
617         }
618         if (isset($config['prescan'])) {
619             $data['prescan'] = (bool)$config['prescan'];
620         }
621         $editform->set_data($data);
622     }
624     /**
625      * Checks to make sure that the path for the file cache exists.
626      *
627      * @return bool
628      * @throws coding_exception
629      */
630     protected function ensure_path_exists() {
631         global $CFG;
632         if (!is_writable($this->path)) {
633             if ($this->custompath && !$this->autocreate) {
634                 throw new coding_exception('File store path does not exist. It must exist and be writable by the web server.');
635             }
636             $createdcfg = false;
637             if (!isset($CFG)) {
638                 // This can only happen during destruction of objects.
639                 // A cache is being used within a destructor, php is ending a request and $CFG has
640                 // already being cleaned up.
641                 // Rebuild $CFG with directory permissions just to complete this write.
642                 $CFG = $this->cfg;
643                 $createdcfg = true;
644             }
645             if (!make_writable_directory($this->path, false)) {
646                 throw new coding_exception('File store path does not exist and can not be created.');
647             }
648             if ($createdcfg) {
649                 // We re-created it so we'll clean it up.
650                 unset($CFG);
651             }
652         }
653         return true;
654     }
656     /**
657      * Performs any necessary clean up when the file store instance is being deleted.
658      *
659      * 1. Purges the cache directory.
660      * 2. Deletes the directory we created for the given definition.
661      */
662     public function instance_deleted() {
663         $this->purge_all_definitions();
664         @rmdir($this->filestorepath);
665     }
667     /**
668      * Generates an instance of the cache store that can be used for testing.
669      *
670      * Returns an instance of the cache store, or false if one cannot be created.
671      *
672      * @param cache_definition $definition
673      * @return cachestore_file
674      */
675     public static function initialise_test_instance(cache_definition $definition) {
676         $name = 'File test';
677         $path = make_cache_directory('cachestore_file_test');
678         $cache = new cachestore_file($name, array('path' => $path));
679         $cache->initialise($definition);
680         return $cache;
681     }
683     /**
684      * Writes your madness to a file.
685      *
686      * There are several things going on in this function to try to ensure what we don't end up with partial writes etc.
687      *   1. Files for writing are opened with the mode xb, the file must be created and can not already exist.
688      *   2. Renaming, data is written to a temporary file, where it can be verified using md5 and is then renamed.
689      *
690      * @param string $file Absolute file path
691      * @param string $content The content to write.
692      * @return bool
693      */
694     protected function write_file($file, $content) {
695         // Generate a temp file that is going to be unique. We'll rename it at the end to the desired file name.
696         // in this way we avoid partial writes.
697         $path = dirname($file);
698         while (true) {
699             $tempfile = $path.'/'.uniqid(sesskey().'.', true) . '.temp';
700             if (!file_exists($tempfile)) {
701                 break;
702             }
703         }
705         // Open the file with mode=x. This acts to create and open the file for writing only.
706         // If the file already exists this will return false.
707         // We also force binary.
708         $handle = @fopen($tempfile, 'xb+');
709         if ($handle === false) {
710             // File already exists... lock already exists, return false.
711             return false;
712         }
713         fwrite($handle, $content);
714         fflush($handle);
715         // Close the handle, we're done.
716         fclose($handle);
718         if (md5_file($tempfile) !== md5($content)) {
719             // The md5 of the content of the file must match the md5 of the content given to be written.
720             @unlink($tempfile);
721             return false;
722         }
724         // Finally rename the temp file to the desired file, returning the true|false result.
725         $result = rename($tempfile, $file);
726         @chmod($file, $this->cfg->filepermissions);
727         if (!$result) {
728             // Failed to rename, don't leave files lying around.
729             @unlink($tempfile);
730         }
731         return $result;
732     }
734     /**
735      * Returns the name of this instance.
736      * @return string
737      */
738     public function my_name() {
739         return $this->name;
740     }
742     /**
743      * Finds all of the keys being used by this cache store instance.
744      *
745      * @return array
746      */
747     public function find_all() {
748         $this->ensure_path_exists();
749         $files = glob($this->glob_keys_pattern(), GLOB_MARK | GLOB_NOSORT);
750         $return = array();
751         if ($files === false) {
752             return $return;
753         }
754         foreach ($files as $file) {
755             $return[] = substr(basename($file), 0, -6);
756         }
757         return $return;
758     }
760     /**
761      * Finds all of the keys whose keys start with the given prefix.
762      *
763      * @param string $prefix
764      */
765     public function find_by_prefix($prefix) {
766         $this->ensure_path_exists();
767         $prefix = preg_replace('#(\*|\?|\[)#', '[$1]', $prefix);
768         $files = glob($this->glob_keys_pattern($prefix), GLOB_MARK | GLOB_NOSORT);
769         $return = array();
770         if ($files === false) {
771             return $return;
772         }
773         foreach ($files as $file) {
774             // Trim off ".cache" from the end.
775             $return[] = substr(basename($file), 0, -6);
776         }
777         return $return;
778     }