MDL-40903 cache: fixed up event invalidation
[moodle.git] / cache / classes / config.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  * Cache configuration reader
19  *
20  * This file is part of Moodle's cache API, affectionately called MUC.
21  * It contains the components that are requried in order to use caching.
22  *
23  * @package    core
24  * @category   cache
25  * @copyright  2012 Sam Hemelryk
26  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
29 defined('MOODLE_INTERNAL') || die();
31 /**
32  * Cache configuration reader.
33  *
34  * This class is used to interact with the cache's configuration.
35  * The configuration is stored in the Moodle data directory.
36  *
37  * @package    core
38  * @category   cache
39  * @copyright  2012 Sam Hemelryk
40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  */
42 class cache_config {
44     /**
45      * The configured stores
46      * @var array
47      */
48     protected $configstores = array();
50     /**
51      * The configured mode mappings
52      * @var array
53      */
54     protected $configmodemappings = array();
56     /**
57      * The configured definitions as picked up from cache.php files
58      * @var array
59      */
60     protected $configdefinitions = array();
62     /**
63      * The definition mappings that have been configured.
64      * @var array
65      */
66     protected $configdefinitionmappings = array();
68     /**
69      * An array of configured cache lock instances.
70      * @var array
71      */
72     protected $configlocks = array();
74     /**
75      * The site identifier used when the cache config was last saved.
76      * @var string
77      */
78     protected $siteidentifier = null;
80     /**
81      * Please use cache_config::instance to get an instance of the cache config that is ready to be used.
82      */
83     public function __construct() {
84         // Nothing to do here but look pretty.
85     }
87     /**
88      * Gets an instance of the cache_configuration class.
89      *
90      * @return cache_config
91      */
92     public static function instance() {
93         $factory = cache_factory::instance();
94         return $factory->create_config_instance();
95     }
97     /**
98      * Checks if the configuration file exists.
99      *
100      * @return bool True if it exists
101      */
102     public static function config_file_exists() {
103         // Allow for late static binding.
104         return file_exists(self::get_config_file_path());
105     }
107     /**
108      * Returns the expected path to the configuration file.
109      *
110      * @return string The absolute path
111      */
112     protected static function get_config_file_path() {
113         global $CFG;
114         if (!empty($CFG->altcacheconfigpath)) {
115             $path = $CFG->altcacheconfigpath;
116             if (is_dir($path) && is_writable($path)) {
117                 // Its a writable directory, thats fine.
118                 return $path.'/cacheconfig.php';
119             } else if (is_writable(dirname($path)) && (!file_exists($path) || is_writable($path))) {
120                 // Its a file, either it doesn't exist and the directory is writable or the file exists and is writable.
121                 return $path;
122             }
123         }
124         // Return the default location within dataroot.
125         return $CFG->dataroot.'/muc/config.php';
126     }
128     /**
129      * Loads the configuration file and parses its contents into the expected structure.
130      *
131      * @param array|false $configuration Can be used to force a configuration. Should only be used when truly required.
132      * @return boolean
133      */
134     public function load($configuration = false) {
135         global $CFG;
137         if ($configuration === false) {
138             $configuration = $this->include_configuration();
139         }
141         $this->configstores = array();
142         $this->configdefinitions = array();
143         $this->configlocks = array();
144         $this->configmodemappings = array();
145         $this->configdefinitionmappings = array();
146         $this->configlockmappings = array();
148         $siteidentifier = 'unknown';
149         if (array_key_exists('siteidentifier', $configuration)) {
150             $siteidentifier = $configuration['siteidentifier'];
151         }
152         $this->siteidentifier = $siteidentifier;
154         // Filter the lock instances.
155         $defaultlock = null;
156         foreach ($configuration['locks'] as $conf) {
157             if (!is_array($conf)) {
158                 // Something is very wrong here.
159                 continue;
160             }
161             if (!array_key_exists('name', $conf)) {
162                 // Not a valid definition configuration.
163                 continue;
164             }
165             $name = $conf['name'];
166             if (array_key_exists($name, $this->configlocks)) {
167                 debugging('Duplicate cache lock detected. This should never happen.', DEBUG_DEVELOPER);
168                 continue;
169             }
170             $conf['default'] = (!empty($conf['default']));
171             if ($defaultlock === null || $conf['default']) {
172                 $defaultlock = $name;
173             }
174             $this->configlocks[$name] = $conf;
175         }
177         // Filter the stores.
178         $availableplugins = cache_helper::early_get_cache_plugins();
179         foreach ($configuration['stores'] as $store) {
180             if (!is_array($store) || !array_key_exists('name', $store) || !array_key_exists('plugin', $store)) {
181                 // Not a valid instance configuration.
182                 debugging('Invalid cache store in config. Missing name or plugin.', DEBUG_DEVELOPER);
183                 continue;
184             }
185             $plugin = $store['plugin'];
186             $class = 'cachestore_'.$plugin;
187             $exists = array_key_exists($plugin, $availableplugins);
188             if (!$exists) {
189                 // Not a valid plugin, or has been uninstalled, just skip it an carry on.
190                 debugging('Invalid cache store in config. Not an available plugin.', DEBUG_DEVELOPER);
191                 continue;
192             }
193             $file = $CFG->dirroot.'/cache/stores/'.$plugin.'/lib.php';
194             if (!class_exists($class) && file_exists($file)) {
195                 require_once($file);
196             }
197             if (!class_exists($class)) {
198                 continue;
199             }
200             if (!array_key_exists('cache_store', class_parents($class))) {
201                 continue;
202             }
203             if (!array_key_exists('configuration', $store) || !is_array($store['configuration'])) {
204                 $store['configuration'] = array();
205             }
206             $store['class'] = $class;
207             $store['default'] = !empty($store['default']);
208             if (!array_key_exists('lock', $store) || !array_key_exists($store['lock'], $this->configlocks)) {
209                 $store['lock'] = $defaultlock;
210             }
212             $this->configstores[$store['name']] = $store;
213         }
215         // Filter the definitions.
216         foreach ($configuration['definitions'] as $id => $conf) {
217             if (!is_array($conf)) {
218                 // Something is very wrong here.
219                 continue;
220             }
221             if (!array_key_exists('mode', $conf) || !array_key_exists('component', $conf) || !array_key_exists('area', $conf)) {
222                 // Not a valid definition configuration.
223                 continue;
224             }
225             if (array_key_exists($id, $this->configdefinitions)) {
226                 debugging('Duplicate cache definition detected. This should never happen.', DEBUG_DEVELOPER);
227                 continue;
228             }
229             $conf['mode'] = (int)$conf['mode'];
230             if ($conf['mode'] < cache_store::MODE_APPLICATION || $conf['mode'] > cache_store::MODE_REQUEST) {
231                 // Invalid cache mode used for the definition.
232                 continue;
233             }
234             if ($conf['mode'] === cache_store::MODE_SESSION || $conf['mode'] === cache_store::MODE_REQUEST) {
235                 // We force this for session and request caches.
236                 // They are only allowed to use the default as we don't want people changing them.
237                 $conf['sharingoptions'] = cache_definition::SHARING_DEFAULT;
238                 $conf['selectedsharingoption'] = cache_definition::SHARING_DEFAULT;
239                 $conf['userinputsharingkey'] = '';
240             } else {
241                 // Default the sharing option as it was added for 2.5.
242                 // This can be removed sometime after 2.5 is the minimum version someone can upgrade from.
243                 if (!isset($conf['sharingoptions'])) {
244                     $conf['sharingoptions'] = cache_definition::SHARING_DEFAULTOPTIONS;
245                 }
246                 // Default the selected sharing option as it was added for 2.5.
247                 // This can be removed sometime after 2.5 is the minimum version someone can upgrade from.
248                 if (!isset($conf['selectedsharingoption'])) {
249                     $conf['selectedsharingoption'] = cache_definition::SHARING_DEFAULT;
250                 }
251                 // Default the user input sharing key as it was added for 2.5.
252                 // This can be removed sometime after 2.5 is the minimum version someone can upgrade from.
253                 if (!isset($conf['userinputsharingkey'])) {
254                     $conf['userinputsharingkey'] = '';
255                 }
256             }
257             $this->configdefinitions[$id] = $conf;
258         }
260         // Filter the mode mappings.
261         foreach ($configuration['modemappings'] as $mapping) {
262             if (!is_array($mapping) || !array_key_exists('mode', $mapping) || !array_key_exists('store', $mapping)) {
263                 // Not a valid mapping configuration.
264                 debugging('A cache mode mapping entry is invalid.', DEBUG_DEVELOPER);
265                 continue;
266             }
267             if (!array_key_exists($mapping['store'], $this->configstores)) {
268                 // Mapped array instance doesn't exist.
269                 debugging('A cache mode mapping exists for a mode or store that does not exist.', DEBUG_DEVELOPER);
270                 continue;
271             }
272             $mapping['mode'] = (int)$mapping['mode'];
273             if ($mapping['mode'] < 0 || $mapping['mode'] > 4) {
274                 // Invalid cache type used for the mapping.
275                 continue;
276             }
277             if (!array_key_exists('sort', $mapping)) {
278                 $mapping['sort'] = 0;
279             }
280             $this->configmodemappings[] = $mapping;
281         }
283         // Filter the definition mappings.
284         foreach ($configuration['definitionmappings'] as $mapping) {
285             if (!is_array($mapping) || !array_key_exists('definition', $mapping) || !array_key_exists('store', $mapping)) {
286                 // Not a valid mapping configuration.
287                 continue;
288             }
289             if (!array_key_exists($mapping['store'], $this->configstores)) {
290                 // Mapped array instance doesn't exist.
291                 continue;
292             }
293             if (!array_key_exists($mapping['definition'], $this->configdefinitions)) {
294                 // Mapped array instance doesn't exist.
295                 continue;
296             }
297             if (!array_key_exists('sort', $mapping)) {
298                 $mapping['sort'] = 0;
299             }
300             $this->configdefinitionmappings[] = $mapping;
301         }
303         usort($this->configmodemappings, array($this, 'sort_mappings'));
304         usort($this->configdefinitionmappings, array($this, 'sort_mappings'));
306         return true;
307     }
309     /**
310      * Returns the site identifier used by the cache API.
311      * @return string
312      */
313     public function get_site_identifier() {
314         return $this->siteidentifier;
315     }
317     /**
318      * Includes the configuration file and makes sure it contains the expected bits.
319      *
320      * You need to ensure that the config file exists before this is called.
321      *
322      * @return array
323      * @throws cache_exception
324      */
325     protected function include_configuration() {
326         $configuration = array();
327         $cachefile = self::get_config_file_path();
329         if (!file_exists($cachefile)) {
330             throw new cache_exception('Default cache config could not be found. It should have already been created by now.');
331         }
332         include($cachefile);
333         if (!is_array($configuration)) {
334             throw new cache_exception('Invalid cache configuration file');
335         }
336         if (!array_key_exists('stores', $configuration) || !is_array($configuration['stores'])) {
337             $configuration['stores'] = array();
338         }
339         if (!array_key_exists('modemappings', $configuration) || !is_array($configuration['modemappings'])) {
340             $configuration['modemappings'] = array();
341         }
342         if (!array_key_exists('definitions', $configuration) || !is_array($configuration['definitions'])) {
343             $configuration['definitions'] = array();
344         }
345         if (!array_key_exists('definitionmappings', $configuration) || !is_array($configuration['definitionmappings'])) {
346             $configuration['definitionmappings'] = array();
347         }
348         if (!array_key_exists('locks', $configuration) || !is_array($configuration['locks'])) {
349             $configuration['locks'] = array();
350         }
352         return $configuration;
353     }
355     /**
356      * Used to sort cache config arrays based upon a sort key.
357      *
358      * Highest number at the top.
359      *
360      * @param array $a
361      * @param array $b
362      * @return int
363      */
364     protected function sort_mappings(array $a, array $b) {
365         if ($a['sort'] == $b['sort']) {
366             return 0;
367         }
368         return ($a['sort'] < $b['sort']) ? 1 : -1;
369     }
371     /**
372      * Gets a definition from the config given its name.
373      *
374      * @param string $id
375      * @return bool
376      */
377     public function get_definition_by_id($id) {
378         if (array_key_exists($id, $this->configdefinitions)) {
379             return $this->configdefinitions[$id];
380         }
381         return false;
382     }
384     /**
385      * Returns all the known definitions.
386      *
387      * @return array
388      */
389     public function get_definitions() {
390         return $this->configdefinitions;
391     }
393     /**
394      * Returns the definitions mapped into the given store name.
395      *
396      * @param string $storename
397      * @return array Associative array of definitions, id=>definition
398      */
399     public function get_definitions_by_store($storename) {
400         $definitions = array();
402         // This function was accidentally made static at some stage in the past.
403         // It was converted to an instance method but to be backwards compatible
404         // we must step around this in code.
405         if (!isset($this)) {
406             $config = cache_config::instance();
407         } else {
408             $config = $this;
409         }
411         $stores = $config->get_all_stores();
412         if (!array_key_exists($storename, $stores)) {
413             // The store does not exist.
414             return false;
415         }
417         $defmappings = $config->get_definition_mappings();
418         // Create an associative array for the definition mappings.
419         $thedefmappings = array();
420         foreach ($defmappings as $defmapping) {
421             $thedefmappings[$defmapping['definition']] = $defmapping;
422         }
424         // Search for matches in default mappings.
425         $defs = $config->get_definitions();
426         foreach($config->get_mode_mappings() as $modemapping) {
427             if ($modemapping['store'] !== $storename) {
428                 continue;
429             }
430             foreach($defs as $id => $definition) {
431                 if ($definition['mode'] !== $modemapping['mode']) {
432                     continue;
433                 }
434                 // Exclude custom definitions mapping: they will be managed few lines below.
435                 if (array_key_exists($id, $thedefmappings)) {
436                     continue;
437                 }
438                 $definitions[$id] = $definition;
439             }
440         }
442         // Search for matches in the custom definitions mapping
443         foreach ($defmappings as $defmapping) {
444             if ($defmapping['store'] !== $storename) {
445                 continue;
446             }
447             $definition = $config->get_definition_by_id($defmapping['definition']);
448             if ($definition) {
449                 $definitions[$defmapping['definition']] = $definition;
450             }
451         }
453         return $definitions;
454     }
456     /**
457      * Returns all of the stores that are suitable for the given mode and requirements.
458      *
459      * @param int $mode One of cache_store::MODE_*
460      * @param int $requirements The requirements of the cache as a binary flag
461      * @return array An array of suitable stores.
462      */
463     public function get_stores($mode, $requirements = 0) {
464         $stores = array();
465         foreach ($this->configstores as $name => $store) {
466             // If the mode is supported and all of the requirements are provided features.
467             if (($store['modes'] & $mode) && ($store['features'] & $requirements) === $requirements) {
468                 $stores[$name] = $store;
469             }
470         }
471         return $stores;
472     }
474     /**
475      * Gets all of the stores that are to be used for the given definition.
476      *
477      * @param cache_definition $definition
478      * @return array
479      */
480     public function get_stores_for_definition(cache_definition $definition) {
481         // Check if MUC has been disabled.
482         $factory = cache_factory::instance();
483         if ($factory->stores_disabled()) {
484             // Yip its been disabled.
485             // To facilitate this we are going to always return an empty array of stores to use.
486             // This will force all cache instances to use the cachestore_dummy.
487             // MUC will still be used essentially so that code using it will still continue to function but because no cache stores
488             // are being used interaction with MUC will be purely based around a static var.
489             return array();
490         }
492         $availablestores = $this->get_stores($definition->get_mode(), $definition->get_requirements_bin());
493         $stores = array();
494         $id = $definition->get_id();
496         // Now get any mappings and give them priority.
497         foreach ($this->configdefinitionmappings as $mapping) {
498             if ($mapping['definition'] !== $id) {
499                 continue;
500             }
501             $storename = $mapping['store'];
502             if (!array_key_exists($storename, $availablestores)) {
503                 continue;
504             }
505             if (array_key_exists($storename, $stores)) {
506                 $store = $stores[$storename];
507                 unset($stores[$storename]);
508                 $stores[$storename] = $store;
509             } else {
510                 $stores[$storename] = $availablestores[$storename];
511             }
512         }
514         if (empty($stores) && !$definition->is_for_mappings_only()) {
515             $mode = $definition->get_mode();
516             // Load the default stores.
517             foreach ($this->configmodemappings as $mapping) {
518                 if ($mapping['mode'] === $mode && array_key_exists($mapping['store'], $availablestores)) {
519                     $store = $availablestores[$mapping['store']];
520                     if (empty($store['mappingsonly'])) {
521                         $stores[$mapping['store']] = $store;
522                     }
523                 }
524             }
525         }
527         return $stores;
528     }
530     /**
531      * Returns all of the configured stores
532      * @return array
533      */
534     public function get_all_stores() {
535         return $this->configstores;
536     }
538     /**
539      * Returns all of the configured mode mappings
540      * @return array
541      */
542     public function get_mode_mappings() {
543         return $this->configmodemappings;
544     }
546     /**
547      * Returns all of the known definition mappings.
548      * @return array
549      */
550     public function get_definition_mappings() {
551         return $this->configdefinitionmappings;
552     }
554     /**
555      * Returns an array of the configured locks.
556      * @return array Array of name => config
557      */
558     public function get_locks() {
559         return $this->configlocks;
560     }
562     /**
563      * Returns the lock store configuration to use with a given store.
564      * @param string $storename
565      * @return array
566      * @throws cache_exception
567      */
568     public function get_lock_for_store($storename) {
569         if (array_key_exists($storename, $this->configstores)) {
570             if (array_key_exists($this->configstores[$storename]['lock'], $this->configlocks)) {
571                 $lock = $this->configstores[$storename]['lock'];
572                 return $this->configlocks[$lock];
573             }
574         }
575         return $this->get_default_lock();
576     }
578     /**
579      * Gets the default lock instance.
580      *
581      * @return array
582      * @throws cache_exception
583      */
584     public function get_default_lock() {
585         foreach ($this->configlocks as $lockconf) {
586             if (!empty($lockconf['default'])) {
587                 return $lockconf;
588             }
589         }
590         throw new cache_exception('ex_nodefaultlock');
591     }