MDL-64739 analytics: Contexts autocomplete with ajax
[moodle.git] / analytics / classes / manager.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  * Analytics basic actions manager.
19  *
20  * @package   core_analytics
21  * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core_analytics;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Analytics basic actions manager.
31  *
32  * @package   core_analytics
33  * @copyright 2017 David Monllao {@link http://www.davidmonllao.com}
34  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35  */
36 class manager {
38     /**
39      * Default mlbackend
40      */
41     const DEFAULT_MLBACKEND = '\mlbackend_php\processor';
43     /**
44      * Name of the file where components declare their models.
45      */
46     const ANALYTICS_FILENAME = 'db/analytics.php';
48     /**
49      * @var \core_analytics\predictor[]
50      */
51     protected static $predictionprocessors = [];
53     /**
54      * @var \core_analytics\local\target\base[]
55      */
56     protected static $alltargets = null;
58     /**
59      * @var \core_analytics\local\indicator\base[]
60      */
61     protected static $allindicators = null;
63     /**
64      * @var \core_analytics\local\time_splitting\base[]
65      */
66     protected static $alltimesplittings = null;
68     /**
69      * Checks that the user can manage models
70      *
71      * @throws \required_capability_exception
72      * @return void
73      */
74     public static function check_can_manage_models() {
75         require_capability('moodle/analytics:managemodels', \context_system::instance());
76     }
78     /**
79      * Checks that the user can list that context insights
80      *
81      * @throws \required_capability_exception
82      * @param \context $context
83      * @param  bool $return The method returns a bool if true.
84      * @return void
85      */
86     public static function check_can_list_insights(\context $context, bool $return = false) {
87         global $USER;
89         if ($context->contextlevel === CONTEXT_USER && $context->instanceid == $USER->id) {
90             $capability = 'moodle/analytics:listowninsights';
91         } else {
92             $capability = 'moodle/analytics:listinsights';
93         }
95         if ($return) {
96             return has_capability($capability, $context);
97         } else {
98             require_capability($capability, $context);
99         }
100     }
102     /**
103      * Is analytics enabled globally?
104      *
105      * return bool
106      */
107     public static function is_analytics_enabled(): bool {
108         global $CFG;
110         if (isset($CFG->enableanalytics)) {
111             return $CFG->enableanalytics;
112         }
114         // Enabled by default.
115         return true;
116     }
118     /**
119      * Returns all system models that match the provided filters.
120      *
121      * @param bool $enabled
122      * @param bool $trained
123      * @param \context|false $predictioncontext
124      * @return \core_analytics\model[]
125      */
126     public static function get_all_models($enabled = false, $trained = false, $predictioncontext = false) {
127         global $DB;
129         $params = array();
131         $sql = "SELECT am.* FROM {analytics_models} am";
133         if ($enabled || $trained || $predictioncontext) {
134             $conditions = [];
135             if ($enabled) {
136                 $conditions[] = 'am.enabled = :enabled';
137                 $params['enabled'] = 1;
138             }
139             if ($trained) {
140                 $conditions[] = 'am.trained = :trained';
141                 $params['trained'] = 1;
142             }
143             if ($predictioncontext) {
144                 $conditions[] = "EXISTS (SELECT 'x'
145                                            FROM {analytics_predictions} ap
146                                           WHERE ap.modelid = am.id AND ap.contextid = :contextid)";
147                 $params['contextid'] = $predictioncontext->id;
148             }
149             $sql .= ' WHERE ' . implode(' AND ', $conditions);
150         }
151         $sql .= ' ORDER BY am.enabled DESC, am.timemodified DESC';
153         $modelobjs = $DB->get_records_sql($sql, $params);
155         $models = array();
156         foreach ($modelobjs as $modelobj) {
157             $model = new \core_analytics\model($modelobj);
158             if ($model->is_available()) {
159                 $models[$modelobj->id] = $model;
160             }
161         }
163         // Sort the models by the model name using the current session language.
164         \core_collator::asort_objects_by_method($models, 'get_name');
166         return $models;
167     }
169     /**
170      * Returns the provided predictions processor class.
171      *
172      * @param false|string $predictionclass Returns the system default processor if false
173      * @param bool $checkisready
174      * @return \core_analytics\predictor
175      */
176     public static function get_predictions_processor($predictionclass = false, $checkisready = true) {
178         // We want 0 or 1 so we can use it as an array key for caching.
179         $checkisready = intval($checkisready);
181         if (!$predictionclass) {
182             $predictionclass = get_config('analytics', 'predictionsprocessor');
183         }
185         if (empty($predictionclass)) {
186             // Use the default one if nothing set.
187             $predictionclass = self::default_mlbackend();
188         }
190         if (!class_exists($predictionclass)) {
191             throw new \coding_exception('Invalid predictions processor ' . $predictionclass . '.');
192         }
194         $interfaces = class_implements($predictionclass);
195         if (empty($interfaces['core_analytics\predictor'])) {
196             throw new \coding_exception($predictionclass . ' should implement \core_analytics\predictor.');
197         }
199         // Return it from the cached list.
200         if (!isset(self::$predictionprocessors[$checkisready][$predictionclass])) {
202             $instance = new $predictionclass();
203             if ($checkisready) {
204                 $isready = $instance->is_ready();
205                 if ($isready !== true) {
206                     throw new \moodle_exception('errorprocessornotready', 'analytics', '', $isready);
207                 }
208             }
209             self::$predictionprocessors[$checkisready][$predictionclass] = $instance;
210         }
212         return self::$predictionprocessors[$checkisready][$predictionclass];
213     }
215     /**
216      * Return all system predictions processors.
217      *
218      * @return \core_analytics\predictor[]
219      */
220     public static function get_all_prediction_processors() {
222         $mlbackends = \core_component::get_plugin_list('mlbackend');
224         $predictionprocessors = array();
225         foreach ($mlbackends as $mlbackend => $unused) {
226             $classfullpath = '\mlbackend_' . $mlbackend . '\processor';
227             $predictionprocessors[$classfullpath] = self::get_predictions_processor($classfullpath, false);
228         }
229         return $predictionprocessors;
230     }
232     /**
233      * Resets the cached prediction processors.
234      * @return null
235      */
236     public static function reset_prediction_processors() {
237         self::$predictionprocessors = [];
238     }
240     /**
241      * Returns the name of the provided predictions processor.
242      *
243      * @param \core_analytics\predictor $predictionsprocessor
244      * @return string
245      */
246     public static function get_predictions_processor_name(\core_analytics\predictor $predictionsprocessor) {
247             $component = substr(get_class($predictionsprocessor), 0, strpos(get_class($predictionsprocessor), '\\', 1));
248         return get_string('pluginname', $component);
249     }
251     /**
252      * Whether the provided plugin is used by any model.
253      *
254      * @param string $plugin
255      * @return bool
256      */
257     public static function is_mlbackend_used($plugin) {
258         $models = self::get_all_models();
259         foreach ($models as $model) {
260             $processor = $model->get_predictions_processor();
261             $noprefixnamespace = ltrim(get_class($processor), '\\');
262             $processorplugin = substr($noprefixnamespace, 0, strpos($noprefixnamespace, '\\'));
263             if ($processorplugin == $plugin) {
264                 return true;
265             }
266         }
268         // Default predictions processor.
269         $defaultprocessorclass = get_config('analytics', 'predictionsprocessor');
270         $pluginclass = '\\' . $plugin . '\\processor';
271         if ($pluginclass === $defaultprocessorclass) {
272             return true;
273         }
275         return false;
276     }
278     /**
279      * Get all available time splitting methods.
280      *
281      * @return \core_analytics\local\time_splitting\base[]
282      */
283     public static function get_all_time_splittings() {
284         if (self::$alltimesplittings !== null) {
285             return self::$alltimesplittings;
286         }
288         $classes = self::get_analytics_classes('time_splitting');
290         self::$alltimesplittings = [];
291         foreach ($classes as $fullclassname => $classpath) {
292             $instance = self::get_time_splitting($fullclassname);
293             // We need to check that it is a valid time splitting method, it may be an abstract class.
294             if ($instance) {
295                 self::$alltimesplittings[$instance->get_id()] = $instance;
296             }
297         }
299         return self::$alltimesplittings;
300     }
302     /**
303      * Returns the enabled time splitting methods.
304      *
305      * @deprecated since Moodle 3.7
306      * @todo MDL-65086 This will be deleted in Moodle 4.1
307      * @see \core_analytics\manager::get_time_splitting_methods_for_evaluation
308      * @return \core_analytics\local\time_splitting\base[]
309      */
310     public static function get_enabled_time_splitting_methods() {
311         debugging('This function has been deprecated. You can use self::get_time_splitting_methods_for_evaluation if ' .
312             'you want to get the default time splitting methods for evaluation, or you can use self::get_all_time_splittings if ' .
313             'you want to get all the time splitting methods available on this site.');
314         return self::get_time_splitting_methods_for_evaluation();
315     }
317     /**
318      * Returns the time-splitting methods for model evaluation.
319      *
320      * @param  bool $all Return all the time-splitting methods that can potentially be used for evaluation or the default ones.
321      * @return \core_analytics\local\time_splitting\base[]
322      */
323     public static function get_time_splitting_methods_for_evaluation(bool $all = false) {
325         if ($all === false) {
326             if ($enabledtimesplittings = get_config('analytics', 'defaulttimesplittingsevaluation')) {
327                 $enabledtimesplittings = array_flip(explode(',', $enabledtimesplittings));
328             }
329         }
331         $timesplittings = self::get_all_time_splittings();
332         foreach ($timesplittings as $key => $timesplitting) {
334             if (!$timesplitting->valid_for_evaluation()) {
335                 unset($timesplittings[$key]);
336             }
338             if ($all === false) {
339                 // We remove the ones that are not enabled. This also respects the default value (all methods enabled).
340                 if (!empty($enabledtimesplittings) && !isset($enabledtimesplittings[$key])) {
341                     unset($timesplittings[$key]);
342                 }
343             }
344         }
345         return $timesplittings;
346     }
348     /**
349      * Returns a time splitting method by its classname.
350      *
351      * @param string $fullclassname
352      * @return \core_analytics\local\time_splitting\base|false False if it is not valid.
353      */
354     public static function get_time_splitting($fullclassname) {
355         if (!self::is_valid($fullclassname, '\core_analytics\local\time_splitting\base')) {
356             return false;
357         }
358         return new $fullclassname();
359     }
361     /**
362      * Return all targets in the system.
363      *
364      * @return \core_analytics\local\target\base[]
365      */
366     public static function get_all_targets() : array {
367         if (self::$alltargets !== null) {
368             return self::$alltargets;
369         }
371         $classes = self::get_analytics_classes('target');
373         self::$alltargets = [];
374         foreach ($classes as $fullclassname => $classpath) {
375             $instance = self::get_target($fullclassname);
376             if ($instance) {
377                 self::$alltargets[$instance->get_id()] = $instance;
378             }
379         }
381         return self::$alltargets;
382     }
383     /**
384      * Return all system indicators.
385      *
386      * @return \core_analytics\local\indicator\base[]
387      */
388     public static function get_all_indicators() {
389         if (self::$allindicators !== null) {
390             return self::$allindicators;
391         }
393         $classes = self::get_analytics_classes('indicator');
395         self::$allindicators = [];
396         foreach ($classes as $fullclassname => $classpath) {
397             $instance = self::get_indicator($fullclassname);
398             if ($instance) {
399                 self::$allindicators[$instance->get_id()] = $instance;
400             }
401         }
403         return self::$allindicators;
404     }
406     /**
407      * Returns the specified target
408      *
409      * @param mixed $fullclassname
410      * @return \core_analytics\local\target\base|false False if it is not valid
411      */
412     public static function get_target($fullclassname) {
413         if (!self::is_valid($fullclassname, 'core_analytics\local\target\base')) {
414             return false;
415         }
416         return new $fullclassname();
417     }
419     /**
420      * Returns an instance of the provided indicator.
421      *
422      * @param string $fullclassname
423      * @return \core_analytics\local\indicator\base|false False if it is not valid.
424      */
425     public static function get_indicator($fullclassname) {
426         if (!self::is_valid($fullclassname, 'core_analytics\local\indicator\base')) {
427             return false;
428         }
429         return new $fullclassname();
430     }
432     /**
433      * Returns whether a time splitting method is valid or not.
434      *
435      * @param string $fullclassname
436      * @param string $baseclass
437      * @return bool
438      */
439     public static function is_valid($fullclassname, $baseclass) {
440         if (is_subclass_of($fullclassname, $baseclass)) {
441             if ((new \ReflectionClass($fullclassname))->isInstantiable()) {
442                 return true;
443             }
444         }
445         return false;
446     }
448     /**
449      * Returns the logstore used for analytics.
450      *
451      * @return \core\log\sql_reader|false False if no log stores are enabled.
452      */
453     public static function get_analytics_logstore() {
454         $readers = get_log_manager()->get_readers('core\log\sql_reader');
455         $analyticsstore = get_config('analytics', 'logstore');
457         if (!empty($analyticsstore) && !empty($readers[$analyticsstore])) {
458             $logstore = $readers[$analyticsstore];
459         } else if (empty($analyticsstore) && !empty($readers)) {
460             // The first one, it is the same default than in settings.
461             $logstore = reset($readers);
462         } else if (!empty($readers)) {
463             $logstore = reset($readers);
464             debugging('The selected log store for analytics is not available anymore. Using "' .
465                 $logstore->get_name() . '"', DEBUG_DEVELOPER);
466         }
468         if (empty($logstore)) {
469             debugging('No system log stores available to use for analytics', DEBUG_DEVELOPER);
470             return false;
471         }
473         if (!$logstore->is_logging()) {
474             debugging('The selected log store for analytics "' . $logstore->get_name() .
475                 '" is not logging activity logs', DEBUG_DEVELOPER);
476         }
478         return $logstore;
479     }
481     /**
482      * Returns this analysable calculations during the provided period.
483      *
484      * @param \core_analytics\analysable $analysable
485      * @param int $starttime
486      * @param int $endtime
487      * @param string $samplesorigin The samples origin as sampleid is not unique across models.
488      * @return array
489      */
490     public static function get_indicator_calculations($analysable, $starttime, $endtime, $samplesorigin) {
491         global $DB;
493         $params = array('starttime' => $starttime, 'endtime' => $endtime, 'contextid' => $analysable->get_context()->id,
494             'sampleorigin' => $samplesorigin);
495         $calculations = $DB->get_recordset('analytics_indicator_calc', $params, '', 'indicator, sampleid, value');
497         $existingcalculations = array();
498         foreach ($calculations as $calculation) {
499             if (empty($existingcalculations[$calculation->indicator])) {
500                 $existingcalculations[$calculation->indicator] = array();
501             }
502             $existingcalculations[$calculation->indicator][$calculation->sampleid] = $calculation->value;
503         }
504         $calculations->close();
505         return $existingcalculations;
506     }
508     /**
509      * Returns the models with insights at the provided context.
510      *
511      * Note that this method is used for display purposes. It filters out models whose insights
512      * are not linked from the reports page.
513      *
514      * @param \context $context
515      * @return \core_analytics\model[]
516      */
517     public static function get_models_with_insights(\context $context) {
519         self::check_can_list_insights($context);
521         $models = self::get_all_models(true, true, $context);
522         foreach ($models as $key => $model) {
523             // Check that it not only have predictions but also generates insights from them.
524             if (!$model->uses_insights() || !$model->get_target()->link_insights_report()) {
525                 unset($models[$key]);
526             }
527         }
528         return $models;
529     }
531     /**
532      * Returns the models that generated insights in the provided context. It can also be used to add new models to the context.
533      *
534      * Note that if you use this function with $newmodelid is the caller responsibility to ensure that the
535      * provided model id generated insights for the provided context.
536      *
537      * @throws \coding_exception
538      * @param  \context $context
539      * @param  int|null $newmodelid A new model to add to the list of models with insights in the provided context.
540      * @return int[]
541      */
542     public static function cached_models_with_insights(\context $context, int $newmodelid = null) {
544         $cache = \cache::make('core', 'contextwithinsights');
545         $modelids = $cache->get($context->id);
546         if ($modelids === false) {
547             // The cache is empty, but we don't know if it is empty because there are no insights
548             // in this context or because cache/s have been purged, we need to be conservative and
549             // "pay" 1 db read to fill up the cache.
551             $models = \core_analytics\manager::get_models_with_insights($context);
553             if ($newmodelid && empty($models[$newmodelid])) {
554                 throw new \coding_exception('The provided modelid ' . $newmodelid . ' did not generate any insights');
555             }
557             $modelids = array_keys($models);
558             $cache->set($context->id, $modelids);
560         } else if ($newmodelid && !in_array($newmodelid, $modelids)) {
561             // We add the context we got as an argument to the cache.
563             array_push($modelids, $newmodelid);
564             $cache->set($context->id, $modelids);
565         }
567         return $modelids;
568     }
570     /**
571      * Returns a prediction
572      *
573      * @param int $predictionid
574      * @param bool $requirelogin
575      * @return array array($model, $prediction, $context)
576      */
577     public static function get_prediction($predictionid, $requirelogin = false) {
578         global $DB;
580         if (!$predictionobj = $DB->get_record('analytics_predictions', array('id' => $predictionid))) {
581             throw new \moodle_exception('errorpredictionnotfound', 'analytics');
582         }
584         $context = \context::instance_by_id($predictionobj->contextid, IGNORE_MISSING);
585         if (!$context) {
586             throw new \moodle_exception('errorpredictioncontextnotavailable', 'analytics');
587         }
589         if ($requirelogin) {
590             list($context, $course, $cm) = get_context_info_array($predictionobj->contextid);
591             require_login($course, false, $cm);
592         }
594         self::check_can_list_insights($context);
596         $model = new \core_analytics\model($predictionobj->modelid);
597         $sampledata = $model->prediction_sample_data($predictionobj);
598         $prediction = new \core_analytics\prediction($predictionobj, $sampledata);
600         return array($model, $prediction, $context);
601     }
603     /**
604      * Used to be used to add models included with the Moodle core.
605      *
606      * @deprecated Deprecated since Moodle 3.7 (MDL-61667) - Use lib/db/analytics.php instead.
607      * @todo Remove this method in Moodle 4.1 (MDL-65186).
608      * @return void
609      */
610     public static function add_builtin_models() {
612         debugging('core_analytics\manager::add_builtin_models() has been deprecated. Core models are now automatically '.
613             'updated according to their declaration in the lib/db/analytics.php file.', DEBUG_DEVELOPER);
614     }
616     /**
617      * Cleans up analytics db tables that do not directly depend on analysables that may have been deleted.
618      */
619     public static function cleanup() {
620         global $DB;
622         $DB->execute("DELETE FROM {analytics_prediction_actions} WHERE predictionid IN
623                           (SELECT ap.id FROM {analytics_predictions} ap
624                         LEFT JOIN {context} ctx ON ap.contextid = ctx.id
625                             WHERE ctx.id IS NULL)");
627         $contextsql = "SELECT id FROM {context} ctx";
628         $DB->delete_records_select('analytics_predictions', "contextid NOT IN ($contextsql)");
629         $DB->delete_records_select('analytics_indicator_calc', "contextid NOT IN ($contextsql)");
631         // Clean up stuff that depends on analysable ids that do not exist anymore.
633         $models = self::get_all_models();
634         foreach ($models as $model) {
636             // We first dump into memory the list of analysables we have in the database (we could probably do this with 1 single
637             // query for the 3 tables, but it may be safer to do it separately).
638             $predictsamplesanalysableids = $DB->get_fieldset_select('analytics_predict_samples', 'DISTINCT analysableid',
639                 'modelid = :modelid', ['modelid' => $model->get_id()]);
640             $predictsamplesanalysableids = array_flip($predictsamplesanalysableids);
641             $trainsamplesanalysableids = $DB->get_fieldset_select('analytics_train_samples', 'DISTINCT analysableid',
642                 'modelid = :modelid', ['modelid' => $model->get_id()]);
643             $trainsamplesanalysableids = array_flip($trainsamplesanalysableids);
644             $usedanalysablesanalysableids = $DB->get_fieldset_select('analytics_used_analysables', 'DISTINCT analysableid',
645                 'modelid = :modelid', ['modelid' => $model->get_id()]);
646             $usedanalysablesanalysableids = array_flip($usedanalysablesanalysableids);
648             $analyser = $model->get_analyser(array('notimesplitting' => true));
650             // We do not honour the list of contexts in this model as it can contain stale records.
651             $analysables = $analyser->get_analysables_iterator();
653             $analysableids = [];
654             foreach ($analysables as $analysable) {
655                 if (!$analysable) {
656                     continue;
657                 }
658                 unset($predictsamplesanalysableids[$analysable->get_id()]);
659                 unset($trainsamplesanalysableids[$analysable->get_id()]);
660                 unset($usedanalysablesanalysableids[$analysable->get_id()]);
661             }
663             $param = ['modelid' => $model->get_id()];
665             if ($predictsamplesanalysableids) {
666                 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($predictsamplesanalysableids), SQL_PARAMS_NAMED);
667                 $DB->delete_records_select('analytics_predict_samples', "modelid = :modelid AND analysableid $idssql",
668                     $param + $idsparams);
669             }
670             if ($trainsamplesanalysableids) {
671                 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($trainsamplesanalysableids), SQL_PARAMS_NAMED);
672                 $DB->delete_records_select('analytics_train_samples', "modelid = :modelid AND analysableid $idssql",
673                     $param + $idsparams);
674             }
675             if ($usedanalysablesanalysableids) {
676                 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($usedanalysablesanalysableids), SQL_PARAMS_NAMED);
677                 $DB->delete_records_select('analytics_used_analysables', "modelid = :modelid AND analysableid $idssql",
678                     $param + $idsparams);
679             }
680         }
681     }
683     /**
684      * Default system backend.
685      *
686      * @return string
687      */
688     public static function default_mlbackend() {
689         return self::DEFAULT_MLBACKEND;
690     }
692     /**
693      * Returns the provided element classes in the site.
694      *
695      * @param string $element
696      * @return string[] Array keys are the FQCN and the values the class path.
697      */
698     private static function get_analytics_classes($element) {
700         // Just in case...
701         $element = clean_param($element, PARAM_ALPHANUMEXT);
703         $classes = \core_component::get_component_classes_in_namespace(null, 'analytics\\' . $element);
705         return $classes;
706     }
708     /**
709      * Check that all the models declared by the component are up to date.
710      *
711      * This is intended to be called during the installation / upgrade to automatically create missing models.
712      *
713      * @param string $componentname The name of the component to load models for.
714      * @return array \core_analytics\model[] List of actually created models.
715      */
716     public static function update_default_models_for_component(string $componentname): array {
718         $result = [];
720         foreach (static::load_default_models_for_component($componentname) as $definition) {
721             if (!\core_analytics\model::exists(static::get_target($definition['target']))) {
722                 $result[] = static::create_declared_model($definition);
723             }
724         }
726         return $result;
727     }
729     /**
730      * Return the list of models declared by the given component.
731      *
732      * @param string $componentname The name of the component to load models for.
733      * @throws \coding_exception Exception thrown in case of invalid syntax.
734      * @return array The $models description array.
735      */
736     public static function load_default_models_for_component(string $componentname): array {
738         $dir = \core_component::get_component_directory($componentname);
740         if (!$dir) {
741             // This is either an invalid component, or a core subsystem without its own root directory.
742             return [];
743         }
745         $file = $dir . '/' . self::ANALYTICS_FILENAME;
747         if (!is_readable($file)) {
748             return [];
749         }
751         $models = null;
752         include($file);
754         if (!isset($models) || !is_array($models) || empty($models)) {
755             return [];
756         }
758         foreach ($models as &$model) {
759             if (!isset($model['enabled'])) {
760                 $model['enabled'] = false;
761             } else {
762                 $model['enabled'] = clean_param($model['enabled'], PARAM_BOOL);
763             }
764         }
766         static::validate_models_declaration($models);
768         return $models;
769     }
771     /**
772      * Return the list of all the models declared anywhere in this Moodle installation.
773      *
774      * Models defined by the core and core subsystems come first, followed by those provided by plugins.
775      *
776      * @return array indexed by the frankenstyle component
777      */
778     public static function load_default_models_for_all_components(): array {
780         $tmp = [];
782         foreach (\core_component::get_component_list() as $type => $components) {
783             foreach (array_keys($components) as $component) {
784                 if ($loaded = static::load_default_models_for_component($component)) {
785                     $tmp[$type][$component] = $loaded;
786                 }
787             }
788         }
790         $result = [];
792         if ($loaded = static::load_default_models_for_component('core')) {
793             $result['core'] = $loaded;
794         }
796         if (!empty($tmp['core'])) {
797             $result += $tmp['core'];
798             unset($tmp['core']);
799         }
801         foreach ($tmp as $components) {
802             $result += $components;
803         }
805         return $result;
806     }
808     /**
809      * Validate the declaration of prediction models according the syntax expected in the component's db folder.
810      *
811      * The expected structure looks like this:
812      *
813      *  [
814      *      [
815      *          'target' => '\fully\qualified\name\of\the\target\class',
816      *          'indicators' => [
817      *              '\fully\qualified\name\of\the\first\indicator',
818      *              '\fully\qualified\name\of\the\second\indicator',
819      *          ],
820      *          'timesplitting' => '\optional\name\of\the\time_splitting\class',
821      *          'enabled' => true,
822      *      ],
823      *  ];
824      *
825      * @param array $models List of declared models.
826      * @throws \coding_exception Exception thrown in case of invalid syntax.
827      */
828     public static function validate_models_declaration(array $models) {
830         foreach ($models as $model) {
831             if (!isset($model['target'])) {
832                 throw new \coding_exception('Missing target declaration');
833             }
835             if (!static::is_valid($model['target'], '\core_analytics\local\target\base')) {
836                 throw new \coding_exception('Invalid target classname', $model['target']);
837             }
839             if (empty($model['indicators']) || !is_array($model['indicators'])) {
840                 throw new \coding_exception('Missing indicators declaration');
841             }
843             foreach ($model['indicators'] as $indicator) {
844                 if (!static::is_valid($indicator, '\core_analytics\local\indicator\base')) {
845                     throw new \coding_exception('Invalid indicator classname', $indicator);
846                 }
847             }
849             if (isset($model['timesplitting'])) {
850                 if (substr($model['timesplitting'], 0, 1) !== '\\') {
851                     throw new \coding_exception('Expecting fully qualified time splitting classname', $model['timesplitting']);
852                 }
853                 if (!static::is_valid($model['timesplitting'], '\core_analytics\local\time_splitting\base')) {
854                     throw new \coding_exception('Invalid time splitting classname', $model['timesplitting']);
855                 }
856             }
858             if (!empty($model['enabled']) && !isset($model['timesplitting'])) {
859                 throw new \coding_exception('Cannot enable a model without time splitting method specified');
860             }
861         }
862     }
864     /**
865      * Create the defined model.
866      *
867      * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
868      * @return \core_analytics\model
869      */
870     public static function create_declared_model(array $definition): \core_analytics\model {
872         list($target, $indicators) = static::get_declared_target_and_indicators_instances($definition);
874         if (isset($definition['timesplitting'])) {
875             $timesplitting = $definition['timesplitting'];
876         } else {
877             $timesplitting = false;
878         }
880         $created = \core_analytics\model::create($target, $indicators, $timesplitting);
882         if (!empty($definition['enabled'])) {
883             $created->enable();
884         }
886         return $created;
887     }
889     /**
890      * Returns a string uniquely representing the given model declaration.
891      *
892      * @param array $model Model declaration
893      * @return string complying with PARAM_ALPHANUM rules and starting with an 'id' prefix
894      */
895     public static function model_declaration_identifier(array $model) : string {
896         return 'id'.sha1(serialize($model));
897     }
899     /**
900      * Given a model definition, return actual target and indicators instances.
901      *
902      * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
903      * @return array [0] => target instance, [1] => array of indicators instances
904      */
905     public static function get_declared_target_and_indicators_instances(array $definition): array {
907         $target = static::get_target($definition['target']);
909         $indicators = [];
911         foreach ($definition['indicators'] as $indicatorname) {
912             $indicator = static::get_indicator($indicatorname);
913             $indicators[$indicator->get_id()] = $indicator;
914         }
916         return [$target, $indicators];
917     }
919     /**
920      * Return the context restrictions that can be applied to the provided context levels.
921      *
922      * @throws \coding_exception
923      * @param  array|null $contextlevels The list of context levels provided by the analyser. Null if all of them.
924      * @param  string|null $query
925      * @return array Associative array with contextid as key and the short version of the context name as value.
926      */
927     public static function get_potential_context_restrictions(?array $contextlevels = null, string $query = null) {
928         global $DB;
930         if (empty($contextlevels) && !is_null($contextlevels)) {
931             return false;
932         }
934         if (!is_null($contextlevels)) {
935             foreach ($contextlevels as $contextlevel) {
936                 if ($contextlevel !== CONTEXT_COURSE && $contextlevel !== CONTEXT_COURSECAT) {
937                     throw new \coding_exception('Only CONTEXT_COURSE and CONTEXT_COURSECAT are supported at the moment.');
938                 }
939             }
940         }
942         $contexts = [];
944         // We have a separate process for each context level for performance reasons (to iterate through mdl_context calling
945         // get_context_name() would be too slow).
946         $contextsystem = \context_system::instance();
947         if (is_null($contextlevels) || in_array(CONTEXT_COURSECAT, $contextlevels)) {
949             $sql = "SELECT cc.id, cc.name, ctx.id AS contextid
950                       FROM {course_categories} cc
951                       JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = cc.id";
952             $params = ['ctxlevel' => CONTEXT_COURSECAT];
954             if ($query) {
955                 $sql .= " WHERE " . $DB->sql_like('cc.name', ':query', false, false);
956                 $params['query'] = '%' . $query . '%';
957             }
959             $coursecats = $DB->get_recordset_sql($sql, $params);
960             foreach ($coursecats as $record) {
961                 $contexts[$record->contextid] = get_string('category') . ': ' .
962                     format_string($record->name, true, array('context' => $contextsystem));
963             }
964             $coursecats->close();
965         }
967         if (is_null($contextlevels) || in_array(CONTEXT_COURSE, $contextlevels)) {
969             $sql = "SELECT c.id, c.shortname, ctx.id AS contextid
970                       FROM {course} c
971                       JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = c.id
972                       WHERE c.id != :siteid";
973             $params = ['ctxlevel' => CONTEXT_COURSE, 'siteid' => SITEID];
975             if ($query) {
976                 $sql .= ' AND (' . $DB->sql_like('c.fullname', ':query1', false, false) . ' OR ' .
977                     $DB->sql_like('c.shortname', ':query2', false, false) . ')';
978                 $params['query1'] = '%' . $query . '%';
979                 $params['query2'] = '%' . $query . '%';
980             }
982             $courses = $DB->get_recordset_sql($sql, $params);
983             foreach ($courses as $record) {
984                 $contexts[$record->contextid] = get_string('course') . ': ' .
985                     format_string($record->shortname, true, array('context' => $contextsystem));
986             }
987             $courses->close();
988         }
990         return $contexts;
991     }