Merge branch 'MDL-70037' of git://github.com/paulholden/moodle
[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         }
698         // Clean up calculations table.
699         $calclifetime = get_config('analytics', 'calclifetime');
700         if (!empty($calclifetime)) {
701             $lifetime = time() - ($calclifetime * DAYSECS); // Value in days.
702             $DB->delete_records_select('analytics_indicator_calc', 'timecreated < ?', [$lifetime]);
703         }
704     }
706     /**
707      * Default system backend.
708      *
709      * @return string
710      */
711     public static function default_mlbackend() {
712         return self::DEFAULT_MLBACKEND;
713     }
715     /**
716      * Returns the provided element classes in the site.
717      *
718      * @param string $element
719      * @return string[] Array keys are the FQCN and the values the class path.
720      */
721     private static function get_analytics_classes($element) {
723         // Just in case...
724         $element = clean_param($element, PARAM_ALPHANUMEXT);
726         $classes = \core_component::get_component_classes_in_namespace(null, 'analytics\\' . $element);
728         return $classes;
729     }
731     /**
732      * Check that all the models declared by the component are up to date.
733      *
734      * This is intended to be called during the installation / upgrade to automatically create missing models.
735      *
736      * @param string $componentname The name of the component to load models for.
737      * @return array \core_analytics\model[] List of actually created models.
738      */
739     public static function update_default_models_for_component(string $componentname): array {
741         $result = [];
743         foreach (static::load_default_models_for_component($componentname) as $definition) {
744             if (!\core_analytics\model::exists(static::get_target($definition['target']))) {
745                 $result[] = static::create_declared_model($definition);
746             }
747         }
749         return $result;
750     }
752     /**
753      * Return the list of models declared by the given component.
754      *
755      * @param string $componentname The name of the component to load models for.
756      * @throws \coding_exception Exception thrown in case of invalid syntax.
757      * @return array The $models description array.
758      */
759     public static function load_default_models_for_component(string $componentname): array {
761         $dir = \core_component::get_component_directory($componentname);
763         if (!$dir) {
764             // This is either an invalid component, or a core subsystem without its own root directory.
765             return [];
766         }
768         $file = $dir . '/' . self::ANALYTICS_FILENAME;
770         if (!is_readable($file)) {
771             return [];
772         }
774         $models = null;
775         include($file);
777         if (!isset($models) || !is_array($models) || empty($models)) {
778             return [];
779         }
781         foreach ($models as &$model) {
782             if (!isset($model['enabled'])) {
783                 $model['enabled'] = false;
784             } else {
785                 $model['enabled'] = clean_param($model['enabled'], PARAM_BOOL);
786             }
787         }
789         static::validate_models_declaration($models);
791         return $models;
792     }
794     /**
795      * Return the list of all the models declared anywhere in this Moodle installation.
796      *
797      * Models defined by the core and core subsystems come first, followed by those provided by plugins.
798      *
799      * @return array indexed by the frankenstyle component
800      */
801     public static function load_default_models_for_all_components(): array {
803         $tmp = [];
805         foreach (\core_component::get_component_list() as $type => $components) {
806             foreach (array_keys($components) as $component) {
807                 if ($loaded = static::load_default_models_for_component($component)) {
808                     $tmp[$type][$component] = $loaded;
809                 }
810             }
811         }
813         $result = [];
815         if ($loaded = static::load_default_models_for_component('core')) {
816             $result['core'] = $loaded;
817         }
819         if (!empty($tmp['core'])) {
820             $result += $tmp['core'];
821             unset($tmp['core']);
822         }
824         foreach ($tmp as $components) {
825             $result += $components;
826         }
828         return $result;
829     }
831     /**
832      * Validate the declaration of prediction models according the syntax expected in the component's db folder.
833      *
834      * The expected structure looks like this:
835      *
836      *  [
837      *      [
838      *          'target' => '\fully\qualified\name\of\the\target\class',
839      *          'indicators' => [
840      *              '\fully\qualified\name\of\the\first\indicator',
841      *              '\fully\qualified\name\of\the\second\indicator',
842      *          ],
843      *          'timesplitting' => '\optional\name\of\the\time_splitting\class',
844      *          'enabled' => true,
845      *      ],
846      *  ];
847      *
848      * @param array $models List of declared models.
849      * @throws \coding_exception Exception thrown in case of invalid syntax.
850      */
851     public static function validate_models_declaration(array $models) {
853         foreach ($models as $model) {
854             if (!isset($model['target'])) {
855                 throw new \coding_exception('Missing target declaration');
856             }
858             if (!static::is_valid($model['target'], '\core_analytics\local\target\base')) {
859                 throw new \coding_exception('Invalid target classname', $model['target']);
860             }
862             if (empty($model['indicators']) || !is_array($model['indicators'])) {
863                 throw new \coding_exception('Missing indicators declaration');
864             }
866             foreach ($model['indicators'] as $indicator) {
867                 if (!static::is_valid($indicator, '\core_analytics\local\indicator\base')) {
868                     throw new \coding_exception('Invalid indicator classname', $indicator);
869                 }
870             }
872             if (isset($model['timesplitting'])) {
873                 if (substr($model['timesplitting'], 0, 1) !== '\\') {
874                     throw new \coding_exception('Expecting fully qualified time splitting classname', $model['timesplitting']);
875                 }
876                 if (!static::is_valid($model['timesplitting'], '\core_analytics\local\time_splitting\base')) {
877                     throw new \coding_exception('Invalid time splitting classname', $model['timesplitting']);
878                 }
879             }
881             if (!empty($model['enabled']) && !isset($model['timesplitting'])) {
882                 throw new \coding_exception('Cannot enable a model without time splitting method specified');
883             }
884         }
885     }
887     /**
888      * Create the defined model.
889      *
890      * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
891      * @return \core_analytics\model
892      */
893     public static function create_declared_model(array $definition): \core_analytics\model {
895         list($target, $indicators) = static::get_declared_target_and_indicators_instances($definition);
897         if (isset($definition['timesplitting'])) {
898             $timesplitting = $definition['timesplitting'];
899         } else {
900             $timesplitting = false;
901         }
903         $created = \core_analytics\model::create($target, $indicators, $timesplitting);
905         if (!empty($definition['enabled'])) {
906             $created->enable();
907         }
909         return $created;
910     }
912     /**
913      * Returns a string uniquely representing the given model declaration.
914      *
915      * @param array $model Model declaration
916      * @return string complying with PARAM_ALPHANUM rules and starting with an 'id' prefix
917      */
918     public static function model_declaration_identifier(array $model) : string {
919         return 'id'.sha1(serialize($model));
920     }
922     /**
923      * Given a model definition, return actual target and indicators instances.
924      *
925      * @param array $definition See {@link self::validate_models_declaration()} for the syntax.
926      * @return array [0] => target instance, [1] => array of indicators instances
927      */
928     public static function get_declared_target_and_indicators_instances(array $definition): array {
930         $target = static::get_target($definition['target']);
932         $indicators = [];
934         foreach ($definition['indicators'] as $indicatorname) {
935             $indicator = static::get_indicator($indicatorname);
936             $indicators[$indicator->get_id()] = $indicator;
937         }
939         return [$target, $indicators];
940     }
942     /**
943      * Return the context restrictions that can be applied to the provided context levels.
944      *
945      * @throws \coding_exception
946      * @param  array|null $contextlevels The list of context levels provided by the analyser. Null if all of them.
947      * @param  string|null $query
948      * @return array Associative array with contextid as key and the short version of the context name as value.
949      */
950     public static function get_potential_context_restrictions(?array $contextlevels = null, string $query = null) {
951         global $DB;
953         if (empty($contextlevels) && !is_null($contextlevels)) {
954             return false;
955         }
957         if (!is_null($contextlevels)) {
958             foreach ($contextlevels as $contextlevel) {
959                 if ($contextlevel !== CONTEXT_COURSE && $contextlevel !== CONTEXT_COURSECAT) {
960                     throw new \coding_exception('Only CONTEXT_COURSE and CONTEXT_COURSECAT are supported at the moment.');
961                 }
962             }
963         }
965         $contexts = [];
967         // We have a separate process for each context level for performance reasons (to iterate through mdl_context calling
968         // get_context_name() would be too slow).
969         $contextsystem = \context_system::instance();
970         if (is_null($contextlevels) || in_array(CONTEXT_COURSECAT, $contextlevels)) {
972             $sql = "SELECT cc.id, cc.name, ctx.id AS contextid
973                       FROM {course_categories} cc
974                       JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = cc.id";
975             $params = ['ctxlevel' => CONTEXT_COURSECAT];
977             if ($query) {
978                 $sql .= " WHERE " . $DB->sql_like('cc.name', ':query', false, false);
979                 $params['query'] = '%' . $query . '%';
980             }
982             $coursecats = $DB->get_recordset_sql($sql, $params);
983             foreach ($coursecats as $record) {
984                 $contexts[$record->contextid] = get_string('category') . ': ' .
985                     format_string($record->name, true, array('context' => $contextsystem));
986             }
987             $coursecats->close();
988         }
990         if (is_null($contextlevels) || in_array(CONTEXT_COURSE, $contextlevels)) {
992             $sql = "SELECT c.id, c.shortname, ctx.id AS contextid
993                       FROM {course} c
994                       JOIN {context} ctx ON ctx.contextlevel = :ctxlevel AND ctx.instanceid = c.id
995                       WHERE c.id != :siteid";
996             $params = ['ctxlevel' => CONTEXT_COURSE, 'siteid' => SITEID];
998             if ($query) {
999                 $sql .= ' AND (' . $DB->sql_like('c.fullname', ':query1', false, false) . ' OR ' .
1000                     $DB->sql_like('c.shortname', ':query2', false, false) . ')';
1001                 $params['query1'] = '%' . $query . '%';
1002                 $params['query2'] = '%' . $query . '%';
1003             }
1005             $courses = $DB->get_recordset_sql($sql, $params);
1006             foreach ($courses as $record) {
1007                 $contexts[$record->contextid] = get_string('course') . ': ' .
1008                     format_string($record->shortname, true, array('context' => $contextsystem));
1009             }
1010             $courses->close();
1011         }
1013         return $contexts;
1014     }