MDL-59010 analytics: Direct db calls to logging API
[moodle.git] / analytics / classes / course.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  *
19  * @package   core_analytics
20  * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
21  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
22  */
24 namespace core_analytics;
26 defined('MOODLE_INTERNAL') || die();
28 require_once($CFG->dirroot . '/course/lib.php');
29 require_once($CFG->dirroot . '/lib/gradelib.php');
30 require_once($CFG->dirroot . '/lib/enrollib.php');
32 /**
33  *
34  * @package   core_analytics
35  * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
36  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  */
38 class course implements \core_analytics\analysable {
40     protected static $instances = array();
42     protected $studentroles = [];
43     protected $teacherroles = [];
45     protected $course = null;
46     protected $coursecontext = null;
48     protected $courseactivities = array();
50     protected $starttime = null;
51     protected $started = null;
52     protected $endtime = null;
53     protected $finished = null;
55     protected $studentids = [];
56     protected $teacherids = [];
58     protected $ntotallogs = null;
60     /**
61      * Course manager constructor.
62      *
63      * Use self::instance() instead to get cached copies of the course. Instances obtained
64      * through this constructor will not be cached either.
65      *
66      * Loads course students and teachers.
67      *
68      * Let's try to keep this computationally inexpensive.
69      *
70      * @param int|stdClass $course Course id
71      * @param array $studentroles
72      * @param array $teacherroles
73      * @return void
74      */
75     public function __construct($course) {
77         if (is_scalar($course)) {
78             $this->course = get_course($course);
79         } else {
80             $this->course = $course;
81         }
83         $this->coursecontext = \context_course::instance($this->course->id);
85         $studentroles = get_config('analytics', 'studentroles');
86         $teacherroles = get_config('analytics', 'teacherroles');
88         if (empty($studentroles) || empty($teacherroles)) {
89             // Unexpected, site settings should be set with default values.
90             throw new \moodle_exception('errornoroles', 'analytics');
91         }
93         $this->studentroles = explode(',', $studentroles);
94         $this->teacherroles = explode(',', $teacherroles);
96         $this->now = time();
98         // Get the course users, including users assigned to student and teacher roles at an higher context.
99         $this->studentids = $this->get_user_ids($this->studentroles);
100         $this->teacherids = $this->get_user_ids($this->teacherroles);
101     }
103     /**
104      * instance
105      *
106      * @param int|stdClass $course Course id
107      * @return void
108      */
109     public static function instance($course) {
111         $courseid = $course;
112         if (!is_scalar($courseid)) {
113             $courseid = $course->id;
114         }
116         if (!empty(self::$instances[$courseid])) {
117             return self::$instances[$courseid];
118         }
120         $instance = new \core_analytics\course($course);
121         self::$instances[$courseid] = $instance;
122         return self::$instances[$courseid];
123     }
125     public function get_id() {
126         return $this->course->id;
127     }
129     public function get_context() {
130         if ($this->coursecontext === null) {
131             $this->coursecontext = \context_course::instance($this->course->id);
132         }
133         return $this->coursecontext;
134     }
136     /**
137      * Get the course start timestamp.
138      *
139      * @return int Timestamp or 0 if has not started yet.
140      */
141     public function get_start() {
142         global $DB;
144         if ($this->starttime !== null) {
145             return $this->starttime;
146         }
148         // The field always exist but may have no valid if the course is created through a sync process.
149         if (!empty($this->course->startdate)) {
150             $this->starttime = (int)$this->course->startdate;
151         } else {
152             $this->starttime = 0;
153         }
155         return $this->starttime;
156     }
158     public function guess_start() {
159         global $DB;
161         if (!$this->get_total_logs()) {
162             // Can't guess.
163             return 0;
164         }
166         $logstore = \core_analytics\manager::get_analytics_logstore();
168         // We first try to find current course student logs.
169         $firstlogs = array();
170         foreach ($this->studentids as $studentid) {
171             // Grrr, we are limited by logging API, we could do this easily with a
172             // select min(timecreated) from xx where courseid = yy group by userid.
174             // Filters based on the premise that more than 90% of people will be using
175             // standard logstore, which contains a userid, contextlevel, contextinstanceid index.
176             $select = "userid = :userid AND contextlevel = :contextlevel AND contextinstanceid = :contextinstanceid";
177             $params = array('userid' => $studentid, 'contextlevel' => CONTEXT_COURSE, 'contextinstanceid' => $this->get_id());
178             $events = $logstore->get_events_select($select, $params, 'timecreated ASC', 0, 1);
179             $event = reset($events);
180             $firstlogs = $event->timecreated;
181         }
182         if (empty($firstlogs)) {
183             // Can't guess if no student accesses.
184             return 0;
185         }
187         sort($firstlogs);
188         $firstlogsmedian = $this->median($firstlogs);
190         $studentenrolments = enrol_get_course_users($this->get_id(), $this->studentids);
191         if (empty($studentenrolments)) {
192             return 0;
193         }
195         $enrolstart = array();
196         foreach ($studentenrolments as $studentenrolment) {
197             $enrolstart[] = ($studentenrolment->uetimestart) ? $studentenrolment->uetimestart : $studentenrolment->uetimecreated;
198         }
199         sort($enrolstart);
200         $enrolstartmedian = $this->median($enrolstart);
202         return intval(($enrolstartmedian + $firstlogsmedian) / 2);
203     }
205     /**
206      * Get the course end timestamp.
207      *
208      * @return int Timestamp or 0 if time end was not set.
209      */
210     public function get_end() {
211         global $DB;
213         if ($this->endtime !== null) {
214             return $this->endtime;
215         }
217         // The enddate field is only available from Moodle 3.2 (MDL-22078).
218         if (!empty($this->course->enddate)) {
219             $this->endtime = (int)$this->course->enddate;
220             return $this->endtime;
221         }
223         return 0;
224     }
226     /**
227      * Get the course end timestamp.
228      *
229      * @return int Timestamp, \core_analytics\analysable::MAX_TIME if we don't know but ongoing and 0 if we can not work it out.
230      */
231     public function guess_end() {
232         global $DB;
234         if ($this->get_total_logs() === 0) {
235             // No way to guess if there are no logs.
236             $this->endtime = 0;
237             return $this->endtime;
238         }
240         list($filterselect, $filterparams) = $this->course_students_query_filter('ula');
242         // Consider the course open if there are still student accesses.
243         $monthsago = time() - (WEEKSECS * 4 * 2);
244         $select = $filterselect . ' AND timeaccess > :timeaccess';
245         $params = $filterparams + array('timeaccess' => $monthsago);
246         $sql = "SELECT timeaccess FROM {user_lastaccess} ula
247                   JOIN {enrol} e ON e.courseid = ula.courseid
248                   JOIN {user_enrolments} ue ON e.id = ue.enrolid AND ue.userid = ula.userid
249                  WHERE $select";
250         if ($records = $DB->get_records_sql($sql, $params)) {
251             return 0;
252         }
254         $sql = "SELECT timeaccess FROM {user_lastaccess} ula
255                   JOIN {enrol} e ON e.courseid = ula.courseid
256                   JOIN {user_enrolments} ue ON e.id = ue.enrolid AND ue.userid = ula.userid
257                  WHERE $filterselect AND ula.timeaccess != 0
258                  ORDER BY timeaccess DESC";
259         $studentlastaccesses = $DB->get_fieldset_sql($sql, $filterparams);
260         if (empty($studentlastaccesses)) {
261             return 0;
262         }
263         sort($studentlastaccesses);
265         return $this->median($studentlastaccesses);
266     }
268     public function get_course_data() {
269         return $this->course;
270     }
272     /**
273      * Is the course valid to extract indicators from it?
274      *
275      * @return bool
276      */
277     public function is_valid() {
279         if (!$this->was_started() || !$this->is_finished()) {
280             return false;
281         }
283         return true;
284     }
286     /**
287      * Has the course started?
288      *
289      * @return bool
290      */
291     public function was_started() {
293         if ($this->started === null) {
294             if ($this->get_start() === 0 || $this->now < $this->get_start()) {
295                 // Not yet started.
296                 $this->started = false;
297             } else {
298                 $this->started = true;
299             }
300         }
302         return $this->started;
303     }
305     /**
306      * Has the course finished?
307      *
308      * @return bool
309      */
310     public function is_finished() {
312         if ($this->finished === null) {
313             $endtime = $this->get_end();
314             if ($endtime === 0 || $this->now < $endtime) {
315                 // It is not yet finished or no idea when it finishes.
316                 $this->finished = false;
317             } else {
318                 $this->finished = true;
319             }
320         }
322         return $this->finished;
323     }
325     /**
326      * Returns a list of user ids matching the specified roles in this course.
327      *
328      * @param array $roleids
329      * @return array
330      */
331     public function get_user_ids($roleids) {
333         // We need to index by ra.id as a user may have more than 1 $roles role.
334         $records = get_role_users($roleids, $this->coursecontext, true, 'ra.id, u.id AS userid, r.id AS roleid', 'ra.id ASC');
336         // If a user have more than 1 $roles role array_combine will discard the duplicate.
337         $callable = array($this, 'filter_user_id');
338         $userids = array_values(array_map($callable, $records));
339         return array_combine($userids, $userids);
340     }
342     /**
343      * Returns the course students.
344      *
345      * @return stdClass[]
346      */
347     public function get_students() {
348         return $this->studentids;
349     }
351     /**
352      * Returns the total number of student logs in the course
353      *
354      * @return int
355      */
356     public function get_total_logs() {
357         global $DB;
359         // No logs if no students.
360         if (empty($this->studentids)) {
361             return 0;
362         }
364         if ($this->ntotallogs === null) {
365             list($filterselect, $filterparams) = $this->course_students_query_filter();
366             $logstore = \core_analytics\manager::get_analytics_logstore();
367             $this->ntotallogs = $logstore->get_events_select_count($filterselect, $filterparams);
368         }
370         return $this->ntotallogs;
371     }
373     public function get_all_activities($activitytype) {
375         // Using is set because we set it to false if there are no activities.
376         if (!isset($this->courseactivities[$activitytype])) {
377             $modinfo = get_fast_modinfo($this->get_course_data(), -1);
378             $instances = $modinfo->get_instances_of($activitytype);
380             if ($instances) {
381                 $this->courseactivities[$activitytype] = array();
382                 foreach ($instances as $instance) {
383                     // By context.
384                     $this->courseactivities[$activitytype][$instance->context->id] = $instance;
385                 }
386             } else {
387                 $this->courseactivities[$activitytype] = false;
388             }
389         }
391         return $this->courseactivities[$activitytype];
392     }
394     public function get_student_grades($courseactivities) {
396         if (empty($courseactivities)) {
397             return array();
398         }
400         $grades = array();
401         foreach ($courseactivities as $contextid => $instance) {
402             $gradesinfo = grade_get_grades($this->course->id, 'mod', $instance->modname, $instance->instance, $this->studentids);
404             // Sort them by activity context and user.
405             if ($gradesinfo && $gradesinfo->items) {
406                 foreach ($gradesinfo->items as $gradeitem) {
407                     foreach ($gradeitem->grades as $userid => $grade) {
408                         if (empty($grades[$contextid][$userid])) {
409                             // Initialise it as array because a single activity can have multiple grade items (e.g. workshop).
410                             $grades[$contextid][$userid] = array();
411                         }
412                         $grades[$contextid][$userid][$gradeitem->id] = $grade;
413                     }
414                 }
415             }
416         }
418         return $grades;
419     }
421     public function get_activities($activitytype, $starttime, $endtime, $student = false) {
423         // $student may not be available, default to not calculating dynamic data.
424         $studentid = -1;
425         if ($student) {
426             $studentid = $student->id;
427         }
428         $modinfo = get_fast_modinfo($this->get_course_data(), $studentid);
429         $activities = $modinfo->get_instances_of($activitytype);
431         $timerangeactivities = array();
432         foreach ($activities as $activity) {
433             if (!$this->completed_by($activity, $starttime, $endtime)) {
434                 continue;
435             }
437             $timerangeactivities[$activity->context->id] = $activity;
438         }
440         return $timerangeactivities;
441     }
443     protected function completed_by(\cm_info $activity, $starttime, $endtime) {
445         // We can't check uservisible because:
446         // - Any activity with available until would not be counted.
447         // - Sites may block student's course view capabilities once the course is closed.
449         // Students can not view hidden activities by default, this is not reliable 100% but accurate in most of the cases.
450         if ($activity->visible === false) {
451             return false;
452         }
454         // TODO Use course_modules_completion's timemodified + COMPLETION_COMPLETE* to discard
455         // activities that have already been completed.
457         // We skip activities that were not yet visible or their 'until' was not in this $starttime - $endtime range.
458         if ($activity->availability) {
459             $info = new \core_availability\info_module($activity);
460             $activityavailability = $this->availability_completed_by($info, $starttime, $endtime);
461             if ($activityavailability === false) {
462                 return false;
463             } else if ($activityavailability === true) {
464                 // This activity belongs to this time range.
465                 return true;
466             }
467         }
469         //// We skip activities in sections that were not yet visible or their 'until' was not in this $starttime - $endtime range.
470         $section = $activity->get_modinfo()->get_section_info($activity->sectionnum);
471         if ($section->availability) {
472             $info = new \core_availability\info_section($section);
473             $sectionavailability = $this->availability_completed_by($info, $starttime, $endtime);
474             if ($sectionavailability === false) {
475                 return false;
476             } else if ($sectionavailability === true) {
477                 // This activity belongs to this section time range.
478                 return true;
479             }
480         }
482         // When the course is using format weeks we use the week's end date.
483         $format = course_get_format($activity->get_modinfo()->get_course());
484         if ($this->course->format === 'weeks') {
485             $dates = $format->get_section_dates($section);
487             // We need to consider the +2 hours added by get_section_dates.
488             // Avoid $starttime <= $dates->end because $starttime may be the start of the next week.
489             if ($starttime < ($dates->end - 7200) && $endtime >= ($dates->end - 7200)) {
490                 return true;
491             } else {
492                 return false;
493             }
494         }
496         // TODO Think about activities in sectionnum 0.
497         if ($activity->sectionnum == 0) {
498             return false;
499         }
501         if (!$this->get_end() || !$this->get_start()) {
502             debugging('Activities which due date is in a time range can not be calculated ' .
503                 'if the course doesn\'t have start and end date', DEBUG_DEVELOPER);
504             return false;
505         }
507         if (!course_format_uses_sections($this->course->format)) {
508             // If it does not use sections and there are no availability conditions to access it it is available
509             // and we can not magically classify it into any other time range than this one.
510             return true;
511         }
513         // Split the course duration in the number of sections and consider the end of each section the due
514         // date of all activities contained in that section.
515         $formatoptions = $format->get_format_options();
516         if (!empty($formatoptions['numsections'])) {
517             $nsections = $formatoptions['numsections'];
518         } else {
519             // There are course format that use sections but without numsections, we fallback to the number
520             // of cached sections in get_section_info_all, not that accurate though.
521             $coursesections = $activity->get_modinfo()->get_section_info_all();
522             $nsections = count($coursesections);
523             if (isset($coursesections[0])) {
524                 // We don't count section 0 if it exists.
525                 $nsections--;
526             }
527         }
529         $courseduration = $this->get_end() - $this->get_start();
530         $sectionduration = round($courseduration / $nsections);
531         $activitysectionenddate = $this->get_start() + ($sectionduration * $activity->sectionnum);
532         if ($activitysectionenddate > $starttime && $activitysectionenddate <= $endtime) {
533             return true;
534         }
536         return false;
537     }
539     protected function availability_completed_by(\core_availability\info $info, $starttime, $endtime) {
541         $dateconditions = $info->get_availability_tree()->get_all_children('\availability_date\condition');
542         foreach ($dateconditions as $condition) {
543             // Availability API does not allow us to check from / to dates nicely, we need to be naughty.
544             // TODO Would be nice to expand \availability_date\condition API for this calling a save that
545             // does not save is weird.
546             $conditiondata = $condition->save();
548             if ($conditiondata->d === \availability_date\condition::DIRECTION_FROM &&
549                     $conditiondata->t > $endtime) {
550                 // Skip this activity if any 'from' date is later than the end time.
551                 return false;
553             } else if ($conditiondata->d === \availability_date\condition::DIRECTION_UNTIL &&
554                     ($conditiondata->t < $starttime || $conditiondata->t > $endtime)) {
555                 // Skip activity if any 'until' date is not in $starttime - $endtime range.
556                 return false;
557             } else if ($conditiondata->d === \availability_date\condition::DIRECTION_UNTIL &&
558                     $conditiondata->t < $endtime && $conditiondata->t > $starttime) {
559                 return true;
560             }
561         }
563         // This can be interpreted as 'the activity was available but we don't know if its expected completion date
564         // was during this period.
565         return null;
566     }
568     /**
569      * Used by get_user_ids to extract the user id.
570      *
571      * @param \stdClass $record
572      * @return int The user id.
573      */
574     protected function filter_user_id($record) {
575         return $record->userid;
576     }
578     /**
579      * Returns the average time between 2 timestamps.
580      *
581      * @param int $start
582      * @param int $end
583      * @return array [starttime, averagetime, endtime]
584      */
585     protected function update_loop_times($start, $end) {
586         $avg = intval(($start + $end) / 2);
587         return array($start, $avg, $end);
588     }
590     /**
591      * Returns the query and params used to filter the logstore by this course students.
592      *
593      * @return array
594      */
595     protected function course_students_query_filter($prefix = false) {
596         global $DB;
598         if ($prefix) {
599             $prefix = $prefix . '.';
600         }
602         // Check the amount of student logs in the 4 previous weeks.
603         list($studentssql, $studentsparams) = $DB->get_in_or_equal($this->studentids, SQL_PARAMS_NAMED);
604         $filterselect = $prefix . 'courseid = :courseid AND ' . $prefix . 'userid ' . $studentssql;
605         $filterparams = array('courseid' => $this->course->id) + $studentsparams;
607         return array($filterselect, $filterparams);
608     }
610     /**
611      * Calculate median
612      *
613      * Keys are ignored.
614      *
615      * @param int|float $values Sorted array of values
616      * @return int
617      */
618     protected function median($values) {
619         $count = count($values);
621         if ($count === 1) {
622             return reset($values);
623         }
625         $middlevalue = floor(($count - 1) / 2);
627         if ($count % 2) {
628             // Odd number, middle is the median.
629             $median = $values[$middlevalue];
630         } else {
631             // Even number, calculate avg of 2 medians.
632             $low = $values[$middlevalue];
633             $high = $values[$middlevalue + 1];
634             $median = (($low + $high) / 2);
635         }
636         return intval($median);
637     }