551e62c16955c9ec33c90d0521c5f7100b3f67ec
[moodle.git] / cache / classes / administration_helper.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 administration helper.
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  * @author     Peter Burnett <peterburnett@catalyst-au.net>
26  * @copyright  2020 Catalyst IT
27  * @copyright  2012 Sam Hemelryk
28  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
29  */
31 namespace core_cache;
33 defined('MOODLE_INTERNAL') || die();
34 use cache_helper, cache_store, cache_config, cache_factory, cache_definition;
36 /**
37  * Administration helper base class.
38  *
39  * Defines abstract methods for a subclass to define the admin page.
40  *
41  * @package     core
42  * @category    cache
43  * @author      Peter Burnett <peterburnett@catalyst-au.net>
44  * @copyright   2020 Catalyst IT
45  * @copyright  2012 Sam Hemelryk
46  * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
47  */
48 abstract class administration_helper extends cache_helper {
50     /**
51      * Returns an array containing all of the information about stores a renderer needs.
52      * @return array
53      */
54     public static function get_store_instance_summaries(): array {
55         $return = array();
56         $default = array();
57         $instance = \cache_config::instance();
58         $stores = $instance->get_all_stores();
59         $locks = $instance->get_locks();
60         foreach ($stores as $name => $details) {
61             $class = $details['class'];
62             $store = false;
63             if ($class::are_requirements_met()) {
64                 $store = new $class($details['name'], $details['configuration']);
65             }
66             $lock = (isset($details['lock'])) ? $locks[$details['lock']] : $instance->get_default_lock();
67             $record = array(
68                 'name' => $name,
69                 'plugin' => $details['plugin'],
70                 'default' => $details['default'],
71                 'isready' => $store ? $store->is_ready() : false,
72                 'requirementsmet' => $class::are_requirements_met(),
73                 'mappings' => 0,
74                 'lock' => $lock,
75                 'modes' => array(
76                     cache_store::MODE_APPLICATION =>
77                         ($class::get_supported_modes($return) & cache_store::MODE_APPLICATION) == cache_store::MODE_APPLICATION,
78                     cache_store::MODE_SESSION =>
79                         ($class::get_supported_modes($return) & cache_store::MODE_SESSION) == cache_store::MODE_SESSION,
80                     cache_store::MODE_REQUEST =>
81                         ($class::get_supported_modes($return) & cache_store::MODE_REQUEST) == cache_store::MODE_REQUEST,
82                 ),
83                 'supports' => array(
84                     'multipleidentifiers' => $store ? $store->supports_multiple_identifiers() : false,
85                     'dataguarantee' => $store ? $store->supports_data_guarantee() : false,
86                     'nativettl' => $store ? $store->supports_native_ttl() : false,
87                     'nativelocking' => ($store instanceof \cache_is_lockable),
88                     'keyawareness' => ($store instanceof \cache_is_key_aware),
89                     'searchable' => ($store instanceof \cache_is_searchable)
90                 ),
91                 'warnings' => $store ? $store->get_warnings() : array()
92             );
93             if (empty($details['default'])) {
94                 $return[$name] = $record;
95             } else {
96                 $default[$name] = $record;
97             }
98         }
100         ksort($return);
101         ksort($default);
102         $return = $return + $default;
104         foreach ($instance->get_definition_mappings() as $mapping) {
105             if (!array_key_exists($mapping['store'], $return)) {
106                 continue;
107             }
108             $return[$mapping['store']]['mappings']++;
109         }
111         return $return;
112     }
114     /**
115      * Returns an array of information about plugins, everything a renderer needs.
116      *
117      * @return array for each store, an array containing various information about each store.
118      *     See the code below for details
119      */
120     public static function get_store_plugin_summaries(): array {
121         $return = array();
122         $plugins = \core_component::get_plugin_list_with_file('cachestore', 'lib.php', true);
123         foreach ($plugins as $plugin => $path) {
124             $class = 'cachestore_'.$plugin;
125             $return[$plugin] = array(
126                 'name' => get_string('pluginname', 'cachestore_'.$plugin),
127                 'requirementsmet' => $class::are_requirements_met(),
128                 'instances' => 0,
129                 'modes' => array(
130                     cache_store::MODE_APPLICATION => ($class::get_supported_modes() & cache_store::MODE_APPLICATION),
131                     cache_store::MODE_SESSION => ($class::get_supported_modes() & cache_store::MODE_SESSION),
132                     cache_store::MODE_REQUEST => ($class::get_supported_modes() & cache_store::MODE_REQUEST),
133                 ),
134                 'supports' => array(
135                     'multipleidentifiers' => ($class::get_supported_features() & cache_store::SUPPORTS_MULTIPLE_IDENTIFIERS),
136                     'dataguarantee' => ($class::get_supported_features() & cache_store::SUPPORTS_DATA_GUARANTEE),
137                     'nativettl' => ($class::get_supported_features() & cache_store::SUPPORTS_NATIVE_TTL),
138                     'nativelocking' => (in_array('cache_is_lockable', class_implements($class))),
139                     'keyawareness' => (array_key_exists('cache_is_key_aware', class_implements($class))),
140                 ),
141                 'canaddinstance' => ($class::can_add_instance() && $class::are_requirements_met())
142             );
143         }
145         $instance = cache_config::instance();
146         $stores = $instance->get_all_stores();
147         foreach ($stores as $store) {
148             $plugin = $store['plugin'];
149             if (array_key_exists($plugin, $return)) {
150                 $return[$plugin]['instances']++;
151             }
152         }
154         return $return;
155     }
157     /**
158      * Returns an array about the definitions. All the information a renderer needs.
159      *
160      * @return array for each store, an array containing various information about each store.
161      *     See the code below for details
162      */
163     public static function get_definition_summaries(): array {
164         $factory = cache_factory::instance();
165         $config = $factory->create_config_instance();
166         $storenames = array();
167         foreach ($config->get_all_stores() as $key => $store) {
168             if (!empty($store['default'])) {
169                 $storenames[$key] = new \lang_string('store_'.$key, 'cache');
170             } else {
171                 $storenames[$store['name']] = $store['name'];
172             }
173         }
174         /* @var cache_definition[] $definitions */
175         $definitions = [];
176         $return = [];
177         foreach ($config->get_definitions() as $key => $definition) {
178             $definitions[$key] = cache_definition::load($definition['component'].'/'.$definition['area'], $definition);
179         }
180         foreach ($definitions as $id => $definition) {
181             $mappings = array();
182             foreach (cache_helper::get_stores_suitable_for_definition($definition) as $store) {
183                 $mappings[] = $storenames[$store->my_name()];
184             }
185             $return[$id] = array(
186                 'id' => $id,
187                 'name' => $definition->get_name(),
188                 'mode' => $definition->get_mode(),
189                 'component' => $definition->get_component(),
190                 'area' => $definition->get_area(),
191                 'mappings' => $mappings,
192                 'canuselocalstore' => $definition->can_use_localstore(),
193                 'sharingoptions' => self::get_definition_sharing_options($definition->get_sharing_options(), false),
194                 'selectedsharingoption' => self::get_definition_sharing_options($definition->get_selected_sharing_option(), true),
195                 'userinputsharingkey' => $definition->get_user_input_sharing_key()
196             );
197         }
198         return $return;
199     }
201     /**
202      * Get the default stores for all modes.
203      *
204      * @return array An array containing sub-arrays, one for each mode.
205      */
206     public static function get_default_mode_stores(): array {
207         global $OUTPUT;
208         $instance = cache_config::instance();
209         $adequatestores = cache_helper::get_stores_suitable_for_mode_default();
210         $icon = new \pix_icon('i/warning', new \lang_string('inadequatestoreformapping', 'cache'));
211         $storenames = array();
212         foreach ($instance->get_all_stores() as $key => $store) {
213             if (!empty($store['default'])) {
214                 $storenames[$key] = new \lang_string('store_'.$key, 'cache');
215             }
216         }
217         $modemappings = array(
218             cache_store::MODE_APPLICATION => array(),
219             cache_store::MODE_SESSION => array(),
220             cache_store::MODE_REQUEST => array(),
221         );
222         foreach ($instance->get_mode_mappings() as $mapping) {
223             $mode = $mapping['mode'];
224             if (!array_key_exists($mode, $modemappings)) {
225                 debugging('Unknown mode in cache store mode mappings', DEBUG_DEVELOPER);
226                 continue;
227             }
228             if (array_key_exists($mapping['store'], $storenames)) {
229                 $modemappings[$mode][$mapping['store']] = $storenames[$mapping['store']];
230             } else {
231                 $modemappings[$mode][$mapping['store']] = $mapping['store'];
232             }
233             if (!array_key_exists($mapping['store'], $adequatestores)) {
234                 $modemappings[$mode][$mapping['store']] = $modemappings[$mode][$mapping['store']].' '.$OUTPUT->render($icon);
235             }
236         }
237         return $modemappings;
238     }
240     /**
241      * Returns an array summarising the locks available in the system.
242      *
243      * @return array array of lock summaries.
244      */
245     public static function get_lock_summaries(): array {
246         $locks = array();
247         $instance = cache_config::instance();
248         $stores = $instance->get_all_stores();
249         foreach ($instance->get_locks() as $lock) {
250             $default = !empty($lock['default']);
251             if ($default) {
252                 $name = new \lang_string($lock['name'], 'cache');
253             } else {
254                 $name = $lock['name'];
255             }
256             $uses = 0;
257             foreach ($stores as $store) {
258                 if (!empty($store['lock']) && $store['lock'] === $lock['name']) {
259                     $uses++;
260                 }
261             }
262             $lockdata = array(
263                 'name' => $name,
264                 'default' => $default,
265                 'uses' => $uses,
266                 'type' => get_string('pluginname', $lock['type'])
267             );
268             $locks[$lock['name']] = $lockdata;
269         }
270         return $locks;
271     }
273     /**
274      * Given a sharing option hash this function returns an array of strings that can be used to describe it.
275      *
276      * @param int $sharingoption The sharing option hash to get strings for.
277      * @param bool $isselectedoptions Set to true if the strings will be used to view the selected options.
278      * @return array An array of lang_string's.
279      */
280     public static function get_definition_sharing_options(int $sharingoption, bool $isselectedoptions = true): array {
281         $options = array();
282         $prefix = ($isselectedoptions) ? 'sharingselected' : 'sharing';
283         if ($sharingoption & cache_definition::SHARING_ALL) {
284             $options[cache_definition::SHARING_ALL] = new \lang_string($prefix.'_all', 'cache');
285         }
286         if ($sharingoption & cache_definition::SHARING_SITEID) {
287             $options[cache_definition::SHARING_SITEID] = new \lang_string($prefix.'_siteid', 'cache');
288         }
289         if ($sharingoption & cache_definition::SHARING_VERSION) {
290             $options[cache_definition::SHARING_VERSION] = new \lang_string($prefix.'_version', 'cache');
291         }
292         if ($sharingoption & cache_definition::SHARING_INPUT) {
293             $options[cache_definition::SHARING_INPUT] = new \lang_string($prefix.'_input', 'cache');
294         }
295         return $options;
296     }
298     /**
299      * Get an array of stores that are suitable to be used for a given definition.
300      *
301      * @param string $component
302      * @param string $area
303      * @return array Array containing 3 elements
304      *      1. An array of currently used stores
305      *      2. An array of suitable stores
306      *      3. An array of default stores
307      */
308     public static function get_definition_store_options(string $component, string $area): array {
309         $factory = cache_factory::instance();
310         $definition = $factory->create_definition($component, $area);
311         $config = cache_config::instance();
312         $currentstores = $config->get_stores_for_definition($definition);
313         $possiblestores = $config->get_stores($definition->get_mode(), $definition->get_requirements_bin());
315         $defaults = array();
316         foreach ($currentstores as $key => $store) {
317             if (!empty($store['default'])) {
318                 $defaults[] = $key;
319                 unset($currentstores[$key]);
320             }
321         }
322         foreach ($possiblestores as $key => $store) {
323             if ($store['default']) {
324                 unset($possiblestores[$key]);
325                 $possiblestores[$key] = $store;
326             }
327         }
328         return array($currentstores, $possiblestores, $defaults);
329     }
331     /**
332      * This function must be implemented to display options for store plugins.
333      *
334      * @param string $name the name of the store plugin.
335      * @param array $plugindetails array of store plugin details.
336      * @return array array of actions.
337      */
338     public function get_store_plugin_actions(string $name, array $plugindetails): array {
339         return array();
340     }
342     /**
343      * This function must be implemented to display options for store instances.
344      *
345      * @param string $name the store instance name.
346      * @param array $storedetails array of store instance details.
347      * @return array array of actions.
348      */
349     public function get_store_instance_actions(string $name, array $storedetails): array {
350         return array();
351     }
353     /**
354      * This function must be implemented to display options for definition mappings.
355      *
356      * @param context $context the context for the definition.
357      * @param array $definitionsummary the definition summary.
358      * @return array array of actions.
359      */
360     public function get_definition_actions(\context $context, array $definitionsummary): array {
361         return array();
362     }
364     /**
365      * This function must be implemented to get addable locks.
366      *
367      * @return array array of locks that are addable.
368      */
369     public function get_addable_lock_options(): array {
370         return array();
371     }
373     /**
374      * This function must be implemented to perform any page actions by a child class.
375      *
376      * @param string $action the action to perform.
377      * @param array $forminfo empty array to be set by actions.
378      * @return array array of form info.
379      */
380     public abstract function perform_cache_actions(string $action, array $forminfo): array;
382     /**
383      * This function must be implemented to display the cache admin page.
384      *
385      * @param core_cache_renderer $renderer the renderer used to generate the page.
386      * @return string the HTML for the page.
387      */
388     public abstract function generate_admin_page(\core_cache_renderer $renderer): string;