132beebf9b90ed5d43f9f33efcbecb14a96a5bad
[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      * @var \core_analytics\predictor[]
40      */
41     protected static $predictionprocessors = null;
43     /**
44      * @var \core_analytics\local\indicator\base[]
45      */
46     protected static $allindicators = null;
48     /**
49      * @var \core_analytics\local\time_splitting\base[]
50      */
51     protected static $alltimesplittings = null;
53     /**
54      * Checks that the user can manage models
55      *
56      * @throws \required_capability_exception
57      * @return void
58      */
59     public static function check_can_manage_models() {
60         require_capability('moodle/analytics:managemodels', \context_system::instance());
61     }
63     /**
64      * Checks that the user can list that context insights
65      *
66      * @throws \required_capability_exception
67      * @param \context $context
68      * @return void
69      */
70     public static function check_can_list_insights(\context $context) {
71         require_capability('moodle/analytics:listinsights', $context);
72     }
74     /**
75      * Returns all system models that match the provided filters.
76      *
77      * @param bool $enabled
78      * @param bool $trained
79      * @param \context $predictioncontext
80      * @return \core_analytics\model[]
81      */
82     public static function get_all_models($enabled = false, $trained = false, $predictioncontext = false) {
83         global $DB;
85         $params = array();
87         $sql = "SELECT DISTINCT am.* FROM {analytics_models} am";
88         if ($predictioncontext) {
89             $sql .= " JOIN {analytics_predictions} ap ON ap.modelid = am.id AND ap.contextid = :contextid";
90             $params['contextid'] = $predictioncontext->id;
91         }
93         if ($enabled || $trained) {
94             $conditions = [];
95             if ($enabled) {
96                 $conditions[] = 'am.enabled = :enabled';
97                 $params['enabled'] = 1;
98             }
99             if ($trained) {
100                 $conditions[] = 'am.trained = :trained';
101                 $params['trained'] = 1;
102             }
103             $sql .= ' WHERE ' . implode(' AND ', $conditions);
104         }
105         $modelobjs = $DB->get_records_sql($sql, $params);
107         $models = array();
108         foreach ($modelobjs as $modelobj) {
109             $models[$modelobj->id] = new \core_analytics\model($modelobj);
110         }
111         return $models;
112     }
114     /**
115      * Returns the site selected predictions processor.
116      *
117      * @param string $predictionclass
118      * @param bool $checkisready
119      * @return \core_analytics\predictor
120      */
121     public static function get_predictions_processor($predictionclass = false, $checkisready = true) {
123         // We want 0 or 1 so we can use it as an array key for caching.
124         $checkisready = intval($checkisready);
126         if ($predictionclass === false) {
127             $predictionclass = get_config('analytics', 'predictionsprocessor');
128         }
130         if (empty($predictionclass)) {
131             // Use the default one if nothing set.
132             $predictionclass = '\mlbackend_php\processor';
133         }
135         if (!class_exists($predictionclass)) {
136             throw new \coding_exception('Invalid predictions processor ' . $predictionclass . '.');
137         }
139         $interfaces = class_implements($predictionclass);
140         if (empty($interfaces['core_analytics\predictor'])) {
141             throw new \coding_exception($predictionclass . ' should implement \core_analytics\predictor.');
142         }
144         // Return it from the cached list.
145         if (!isset(self::$predictionprocessors[$checkisready][$predictionclass])) {
147             $instance = new $predictionclass();
148             if ($checkisready) {
149                 $isready = $instance->is_ready();
150                 if ($isready !== true) {
151                     throw new \moodle_exception('errorprocessornotready', 'analytics', '', $isready);
152                 }
153             }
154             self::$predictionprocessors[$checkisready][$predictionclass] = $instance;
155         }
157         return self::$predictionprocessors[$checkisready][$predictionclass];
158     }
160     /**
161      * Return all system predictions processors.
162      *
163      * @return \core_analytics\predictor
164      */
165     public static function get_all_prediction_processors() {
167         $mlbackends = \core_component::get_plugin_list('mlbackend');
169         $predictionprocessors = array();
170         foreach ($mlbackends as $mlbackend => $unused) {
171             $classfullpath = '\\mlbackend_' . $mlbackend . '\\processor';
172             $predictionprocessors[$classfullpath] = self::get_predictions_processor($classfullpath, false);
173         }
174         return $predictionprocessors;
175     }
177     /**
178      * Get all available time splitting methods.
179      *
180      * @return \core_analytics\local\time_splitting\base[]
181      */
182     public static function get_all_time_splittings() {
183         if (self::$alltimesplittings !== null) {
184             return self::$alltimesplittings;
185         }
187         $classes = self::get_analytics_classes('time_splitting');
189         self::$alltimesplittings = [];
190         foreach ($classes as $fullclassname => $classpath) {
191             $instance = self::get_time_splitting($fullclassname);
192             // We need to check that it is a valid time splitting method, it may be an abstract class.
193             if ($instance) {
194                 self::$alltimesplittings[$instance->get_id()] = $instance;
195             }
196         }
198         return self::$alltimesplittings;
199     }
201     /**
202      * Returns the enabled time splitting methods.
203      *
204      * @return \core_analytics\local\time_splitting\base[]
205      */
206     public static function get_enabled_time_splitting_methods() {
208         if ($enabledtimesplittings = get_config('analytics', 'timesplittings')) {
209             $enabledtimesplittings = array_flip(explode(',', $enabledtimesplittings));
210         }
212         $timesplittings = self::get_all_time_splittings();
213         foreach ($timesplittings as $key => $timesplitting) {
215             // We remove the ones that are not enabled. This also respects the default value (all methods enabled).
216             if (!empty($enabledtimesplittings) && !isset($enabledtimesplittings[$key])) {
217                 unset($timesplittings[$key]);
218             }
219         }
220         return $timesplittings;
221     }
223     /**
224      * Returns a time splitting method by its classname.
225      *
226      * @param string $fullclassname
227      * @return \core_analytics\local\time_splitting\base|false False if it is not valid.
228      */
229     public static function get_time_splitting($fullclassname) {
230         if (!self::is_valid($fullclassname, '\core_analytics\local\time_splitting\base')) {
231             return false;
232         }
233         return new $fullclassname();
234     }
236     /**
237      * Return all system indicators.
238      *
239      * @return \core_analytics\local\indicator\base[]
240      */
241     public static function get_all_indicators() {
242         if (self::$allindicators !== null) {
243             return self::$allindicators;
244         }
246         $classes = self::get_analytics_classes('indicator');
248         self::$allindicators = [];
249         foreach ($classes as $fullclassname => $classpath) {
250             $instance = self::get_indicator($fullclassname);
251             if ($instance) {
252                 // Using get_class as get_component_classes_in_namespace returns double escaped fully qualified class names.
253                 self::$allindicators[$instance->get_id()] = $instance;
254             }
255         }
257         return self::$allindicators;
258     }
260     /**
261      * Returns the specified target
262      *
263      * @param mixed $fullclassname
264      * @return \core_analytics\local\target\base|false False if it is not valid
265      */
266     public static function get_target($fullclassname) {
267         if (!self::is_valid($fullclassname, 'core_analytics\local\target\base')) {
268             return false;
269         }
270         return new $fullclassname();
271     }
273     /**
274      * Returns an instance of the provided indicator.
275      *
276      * @param string $fullclassname
277      * @return \core_analytics\local\indicator\base|false False if it is not valid.
278      */
279     public static function get_indicator($fullclassname) {
280         if (!self::is_valid($fullclassname, 'core_analytics\local\indicator\base')) {
281             return false;
282         }
283         return new $fullclassname();
284     }
286     /**
287      * Returns whether a time splitting method is valid or not.
288      *
289      * @param string $fullclassname
290      * @param string $baseclass
291      * @return bool
292      */
293     public static function is_valid($fullclassname, $baseclass) {
294         if (is_subclass_of($fullclassname, $baseclass)) {
295             if ((new \ReflectionClass($fullclassname))->isInstantiable()) {
296                 return true;
297             }
298         }
299         return false;
300     }
302     /**
303      * Returns the logstore used for analytics.
304      *
305      * @return \core\log\sql_reader
306      */
307     public static function get_analytics_logstore() {
308         $readers = get_log_manager()->get_readers('core\log\sql_reader');
309         $analyticsstore = get_config('analytics', 'logstore');
310         if (empty($analyticsstore)) {
311             $logstore = reset($readers);
312         } else if (!empty($readers[$analyticsstore])) {
313             $logstore = $readers[$analyticsstore];
314         } else {
315             $logstore = reset($readers);
316             debugging('The selected log store for analytics is not available anymore. Using "' .
317                 $logstore->get_name() . '"', DEBUG_DEVELOPER);
318         }
320         if (!$logstore->is_logging()) {
321             debugging('The selected log store for analytics "' . $logstore->get_name() .
322                 '" is not logging activity logs', DEBUG_DEVELOPER);
323         }
325         return $logstore;
326     }
328     /**
329      * Returns the models with insights at the provided context.
330      *
331      * @param \context $context
332      * @return \core_analytics\model[]
333      */
334     public static function get_models_with_insights(\context $context) {
336         self::check_can_list_insights($context);
338         $models = self::get_all_models(true, true, $context);
339         foreach ($models as $key => $model) {
340             // Check that it not only have predictions but also generates insights from them.
341             if (!$model->uses_insights()) {
342                 unset($models[$key]);
343             }
344         }
345         return $models;
346     }
348     /**
349      * Returns a prediction
350      *
351      * @param int $predictionid
352      * @param bool $requirelogin
353      * @return array array($model, $prediction, $context)
354      */
355     public static function get_prediction($predictionid, $requirelogin = false) {
356         global $DB;
358         if (!$predictionobj = $DB->get_record('analytics_predictions', array('id' => $predictionid))) {
359             throw new \moodle_exception('errorpredictionnotfound', 'report_insights');
360         }
362         if ($requirelogin) {
363             list($context, $course, $cm) = get_context_info_array($predictionobj->contextid);
364             require_login($course, false, $cm);
365         } else {
366             $context = \context::instance_by_id($predictionobj->contextid);
367         }
369         self::check_can_list_insights($context);
371         $model = new \core_analytics\model($predictionobj->modelid);
372         $sampledata = $model->prediction_sample_data($predictionobj);
373         $prediction = new \core_analytics\prediction($predictionobj, $sampledata);
375         return array($model, $prediction, $context);
376     }
378     /**
379      * Returns the provided element classes in the site.
380      *
381      * @param string $element
382      * @return string[] Array keys are the FQCN and the values the class path.
383      */
384     private static function get_analytics_classes($element) {
386         // Just in case...
387         $element = clean_param($element, PARAM_ALPHANUMEXT);
389         $classes = \core_component::get_component_classes_in_namespace('core_analytics', 'local\\' . $element);
390         foreach (\core_component::get_plugin_types() as $type => $unusedplugintypepath) {
391             foreach (\core_component::get_plugin_list($type) as $pluginname => $unusedpluginpath) {
392                 $frankenstyle = $type . '_' . $pluginname;
393                 $classes += \core_component::get_component_classes_in_namespace($frankenstyle, 'analytics\\' . $element);
394             }
395         }
397         foreach (\core_component::get_core_subsystems() as $subsystemname => $unusedsubsystempath) {
398             $componentname = 'core_' . $subsystemname;
399             $classes += \core_component::get_component_classes_in_namespace($componentname, 'analytics\\' . $element);
400         }
402         return $classes;
403     }