MDL-69521 core: Move all comments in code from 4.1 to 3.11
[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 3.11
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 3.11 (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         // Cleanup analaytics predictions/calcs with MySQL friendly sub-select.
628         $DB->execute("DELETE FROM {analytics_predictions} WHERE id IN (
629                         SELECT oldpredictions.id
630                         FROM (
631                             SELECT p.id
632                             FROM {analytics_predictions} p
633                             LEFT JOIN {context} ctx ON p.contextid = ctx.id
634                             WHERE ctx.id IS NULL
635                         ) oldpredictions
636                     )");
638         $DB->execute("DELETE FROM {analytics_indicator_calc} WHERE id IN (
639                         SELECT oldcalcs.id FROM (
640                             SELECT c.id
641                             FROM {analytics_indicator_calc} c
642                             LEFT JOIN {context} ctx ON c.contextid = ctx.id
643                             WHERE ctx.id IS NULL
644                         ) oldcalcs
645                     )");
647         // Clean up stuff that depends on analysable ids that do not exist anymore.
649         $models = self::get_all_models();
650         foreach ($models as $model) {
652             // We first dump into memory the list of analysables we have in the database (we could probably do this with 1 single
653             // query for the 3 tables, but it may be safer to do it separately).
654             $predictsamplesanalysableids = $DB->get_fieldset_select('analytics_predict_samples', 'DISTINCT analysableid',
655                 'modelid = :modelid', ['modelid' => $model->get_id()]);
656             $predictsamplesanalysableids = array_flip($predictsamplesanalysableids);
657             $trainsamplesanalysableids = $DB->get_fieldset_select('analytics_train_samples', 'DISTINCT analysableid',
658                 'modelid = :modelid', ['modelid' => $model->get_id()]);
659             $trainsamplesanalysableids = array_flip($trainsamplesanalysableids);
660             $usedanalysablesanalysableids = $DB->get_fieldset_select('analytics_used_analysables', 'DISTINCT analysableid',
661                 'modelid = :modelid', ['modelid' => $model->get_id()]);
662             $usedanalysablesanalysableids = array_flip($usedanalysablesanalysableids);
664             $analyser = $model->get_analyser(array('notimesplitting' => true));
666             // We do not honour the list of contexts in this model as it can contain stale records.
667             $analysables = $analyser->get_analysables_iterator();
669             $analysableids = [];
670             foreach ($analysables as $analysable) {
671                 if (!$analysable) {
672                     continue;
673                 }
674                 unset($predictsamplesanalysableids[$analysable->get_id()]);
675                 unset($trainsamplesanalysableids[$analysable->get_id()]);
676                 unset($usedanalysablesanalysableids[$analysable->get_id()]);
677             }
679             $param = ['modelid' => $model->get_id()];
681             if ($predictsamplesanalysableids) {
682                 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($predictsamplesanalysableids), SQL_PARAMS_NAMED);
683                 $DB->delete_records_select('analytics_predict_samples', "modelid = :modelid AND analysableid $idssql",
684                     $param + $idsparams);
685             }
686             if ($trainsamplesanalysableids) {
687                 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($trainsamplesanalysableids), SQL_PARAMS_NAMED);
688                 $DB->delete_records_select('analytics_train_samples', "modelid = :modelid AND analysableid $idssql",
689                     $param + $idsparams);
690             }
691             if ($usedanalysablesanalysableids) {
692                 list($idssql, $idsparams) = $DB->get_in_or_equal(array_flip($usedanalysablesanalysableids), SQL_PARAMS_NAMED);
693                 $DB->delete_records_select('analytics_used_analysables', "modelid = :modelid AND analysableid $idssql",
694                     $param + $idsparams);
695             }
696         }
697     }
699     /**
700      * Default system backend.
701      *
702      * @return string
703      */
704     public static function default_mlbackend() {
705         return self::DEFAULT_MLBACKEND;
706     }
708     /**
709      * Returns the provided element classes in the site.
710      *
711      * @param string $element
712      * @return string[] Array keys are the FQCN and the values the class path.
713      */
714     private static function get_analytics_classes($element) {
716         // Just in case...
717         $element = clean_param($element, PARAM_ALPHANUMEXT);
719         $classes = \core_component::get_component_classes_in_namespace(null, 'analytics\\' . $element);
721         return $classes;
722     }
724     /**
725      * Check that all the models declared by the component are up to date.
726      *
727      * This is intended to be called during the installation / upgrade to automatically create missing models.
728      *
729      * @param string $componentname The name of the component to load models for.
730      * @return array \core_analytics\model[] List of actually created models.
731      */
732     public static function update_default_models_for_component(string $componentname): array {
734         $result = [];
736         foreach (static::load_default_models_for_component($componentname) as $definition) {
737             if (!\core_analytics\model::exists(static::get_target($definition['target']))) {
738                 $result[] = static::create_declared_model($definition);
739             }
740         }
742         return $result;
743     }
745     /**
746      * Return the list of models declared by the given component.
747      *
748      * @param string $componentname The name of the component to load models for.
749      * @throws \coding_exception Exception thrown in case of invalid syntax.
750      * @return array The $models description array.
751      */
752     public static function load_default_models_for_component(string $componentname): array {
754         $dir = \core_component::get_component_directory($componentname);
756         if (!$dir) {
757             // This is either an invalid component, or a core subsystem without its own root directory.
758             return [];
759         }
761         $file = $dir . '/' . self::ANALYTICS_FILENAME;
763         if (!is_readable($file)) {
764             return [];
765         }
767         $models = null;
768         include($file);
770         if (!isset($models) || !is_array($models) || empty($models)) {
771             return [];
772         }
774         foreach ($models as &$model) {
775             if (!isset($model['enabled'])) {
776                 $model['enabled'] = false;
777             } else {
778                 $model['enabled'] = clean_param($model['enabled'], PARAM_BOOL);
779             }
780         }
782         static::validate_models_declaration($models);
784         return $models;
785     }
787     /**
788      * Return the list of all the models declared anywhere in this Moodle installation.
789      *
790      * Models defined by the core and core subsystems come first, followed by those provided by plugins.
791      *
792      * @return array indexed by the frankenstyle component
793      */
794     public static function load_default_models_for_all_components(): array {
796         $tmp = [];
798         foreach (\core_component::get_component_list() as $type => $components) {
799             foreach (array_keys($components) as $component) {
800                 if ($loaded = static::load_default_models_for_component($component)) {
801                     $tmp[$type][$component] = $loaded;
802                 }
803             }
804         }
806         $result = [];
808         if ($loaded = static::load_default_models_for_component('core')) {
809             $result['core'] = $loaded;
810         }
812         if (!empty($tmp['core'])) {
813             $result += $tmp['core'];
814             unset($tmp['core']);
815         }
817         foreach ($tmp as $components) {
818             $result += $components;
819         }
821         return $result;
822     }
824     /**
825      * Validate the declaration of prediction models according the syntax expected in the component's db folder.
826      *
827      * The expected structure looks like this:
828      *
829      *  [
830      *      [
831      *          'target' => '\fully\qualified\name\of\the\target\class',
832      *          'indicators' => [
833      *              '\fully\qualified\name\of\the\first\indicator',
834      *              '\fully\qualified\name\of\the\second\indicator',
835      *          ],
836      *          'timesplitting' => '\optional\name\of\the\time_splitting\class',
837      *          'enabled' => true,
838      *      ],
839      *  ];
840      *
841      * @param array $models List of declared models.
842      * @throws \coding_exception Exception thrown in case of invalid syntax.
843      */
844     public static function validate_models_declaration(array $models) {
846         foreach ($models as $model) {
847             if (!isset($model['target'])) {
848                 throw new \coding_exception('Missing target declaration');
849             }
851             if (!static::is_valid($model['target'], '\core_analytics\local\target\base')) {
852                 throw new \coding_exception('Invalid target classname', $model['target']);
853             }
855             if (empty($model['indicators']) || !is_array($model['indicators'])) {
856                 throw new \coding_exception('Missing indicators declaration');
857             }
859             foreach ($model['indicators'] as $indicator) {
860                 if (!static::is_valid($indicator, '\core_analytics\local\indicator\base')) {
861                     throw new \coding_exception('Invalid indicator classname', $indicator);
862                 }
863             }
865             if (isset($model['timesplitting'])) {
866                 if (substr($model['timesplitting'], 0, 1) !== '\\') {
867                     throw new \coding_exception('Expecting fully qualified time splitting classname', $model['timesplitting']);
868                 }
869                 if (!static::is_valid($model['timesplitting'], '\core_analytics\local\time_splitting\base')) {
870                     throw new \coding_exception('Invalid time splitting classname', $model['timesplitting']);
871                 }
872             }
874             if (!empty($model['enabled']) && !isset($model['timesplitting'])) {
875                 throw new \coding_exception('Cannot enable a model without time splitting method specified');
876             }
877         }
878     }
880     /**
881      * Create the defined model.
882      *
883      * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
884      * @return \core_analytics\model
885      */
886     public static function create_declared_model(array $definition): \core_analytics\model {
888         list($target, $indicators) = static::get_declared_target_and_indicators_instances($definition);
890         if (isset($definition['timesplitting'])) {
891             $timesplitting = $definition['timesplitting'];
892         } else {
893             $timesplitting = false;
894         }
896         $created = \core_analytics\model::create($target, $indicators, $timesplitting);
898         if (!empty($definition['enabled'])) {
899             $created->enable();
900         }
902         return $created;
903     }
905     /**
906      * Returns a string uniquely representing the given model declaration.
907      *
908      * @param array $model Model declaration
909      * @return string complying with PARAM_ALPHANUM rules and starting with an 'id' prefix
910      */
911     public static function model_declaration_identifier(array $model) : string {
912         return 'id'.sha1(serialize($model));
913     }
915     /**
916      * Given a model definition, return actual target and indicators instances.
917      *
918      * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
919      * @return array [0] => target instance, [1] => array of indicators instances
920      */
921     public static function get_declared_target_and_indicators_instances(array $definition): array {
923         $target = static::get_target($definition['target']);
925         $indicators = [];
927         foreach ($definition['indicators'] as $indicatorname) {
928             $indicator = static::get_indicator($indicatorname);
929             $indicators[$indicator->get_id()] = $indicator;
930         }
932         return [$target, $indicators];
933     }
935     /**
936      * Return the context restrictions that can be applied to the provided context levels.
937      *
938      * @throws \coding_exception
939      * @param  array|null $contextlevels The list of context levels provided by the analyser. Null if all of them.
940      * @param  string|null $query
941      * @return array Associative array with contextid as key and the short version of the context name as value.
942      */
943     public static function get_potential_context_restrictions(?array $contextlevels = null, string $query = null) {
944         global $DB;
946         if (empty($contextlevels) && !is_null($contextlevels)) {
947             return false;
948         }
950         if (!is_null($contextlevels)) {
951             foreach ($contextlevels as $contextlevel) {
952                 if ($contextlevel !== CONTEXT_COURSE && $contextlevel !== CONTEXT_COURSECAT) {
953                     throw new \coding_exception('Only CONTEXT_COURSE and CONTEXT_COURSECAT are supported at the moment.');
954                 }
955             }
956         }
958         $contexts = [];
960         // We have a separate process for each context level for performance reasons (to iterate through mdl_context calling
961         // get_context_name() would be too slow).
962         $contextsystem = \context_system::instance();
963         if (is_null($contextlevels) || in_array(CONTEXT_COURSECAT, $contextlevels)) {
965             $sql = "SELECT cc.id, cc.name, ctx.id AS contextid
966                       FROM {course_categories} cc
967                       JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = cc.id";
968             $params = ['ctxlevel' => CONTEXT_COURSECAT];
970             if ($query) {
971                 $sql .= " WHERE " . $DB->sql_like('cc.name', ':query', false, false);
972                 $params['query'] = '%' . $query . '%';
973             }
975             $coursecats = $DB->get_recordset_sql($sql, $params);
976             foreach ($coursecats as $record) {
977                 $contexts[$record->contextid] = get_string('category') . ': ' .
978                     format_string($record->name, true, array('context' => $contextsystem));
979             }
980             $coursecats->close();
981         }
983         if (is_null($contextlevels) || in_array(CONTEXT_COURSE, $contextlevels)) {
985             $sql = "SELECT c.id, c.shortname, ctx.id AS contextid
986                       FROM {course} c
987                       JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = c.id
988                       WHERE c.id != :siteid";
989             $params = ['ctxlevel' => CONTEXT_COURSE, 'siteid' => SITEID];
991             if ($query) {
992                 $sql .= ' AND (' . $DB->sql_like('c.fullname', ':query1', false, false) . ' OR ' .
993                     $DB->sql_like('c.shortname', ':query2', false, false) . ')';
994                 $params['query1'] = '%' . $query . '%';
995                 $params['query2'] = '%' . $query . '%';
996             }
998             $courses = $DB->get_recordset_sql($sql, $params);
999             foreach ($courses as $record) {
1000                 $contexts[$record->contextid] = get_string('course') . ': ' .
1001                     format_string($record->shortname, true, array('context' => $contextsystem));
1002             }
1003             $courses->close();
1004         }
1006         return $contexts;
1007     }