Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Moodle course analysable
 *
 * @package   core_analytics
 * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace core_analytics;

defined('MOODLE_INTERNAL') || die();

require_once($CFG->dirroot . '/course/lib.php');
require_once($CFG->dirroot . '/lib/gradelib.php');
require_once($CFG->dirroot . '/lib/enrollib.php');

/**
 * Moodle course analysable
 *
 * @package   core_analytics
 * @copyright 2016 David Monllao {@link http://www.davidmonllao.com}
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class course implements \core_analytics\analysable {

    /**
     * @var bool Has this course data been already loaded.
     */
    protected $loaded = false;

    /**
     * @var int $cachedid self::$cachedinstance analysable id.
     */
    protected static $cachedid = 0;

    /**
     * @var \core_analytics\course $cachedinstance
     */
    protected static $cachedinstance = null;

    /**
     * Course object
     *
     * @var \stdClass
     */
    protected $course = null;

    /**
     * The course context.
     *
     * @var \context_course
     */
    protected $coursecontext = null;

    /**
     * The course activities organized by activity type.
     *
     * @var array
     */
    protected $courseactivities = array();

    /**
     * Course start time.
     *
     * @var int
     */
    protected $starttime = null;


    /**
     * Has the course already started?
     *
     * @var bool
     */
    protected $started = null;

    /**
     * Course end time.
     *
     * @var int
     */
    protected $endtime = null;

    /**
     * Is the course finished?
     *
     * @var bool
     */
    protected $finished = null;

    /**
     * Course students ids.
     *
     * @var int[]
     */
    protected $studentids = [];


    /**
     * Course teachers ids
     *
     * @var int[]
     */
    protected $teacherids = [];

    /**
     * Cached copy of the total number of logs in the course.
     *
     * @var int
     */
    protected $ntotallogs = null;

> /** @var int Store current Unix timestamp. */ /** > protected int $now = 0; * Course manager constructor. >
* * Use self::instance() instead to get cached copies of the course. Instances obtained * through this constructor will not be cached. * * @param int|\stdClass $course Course id or mdl_course record * @param \context|null $context * @return void */ public function __construct($course, ?\context $context = null) { if (is_scalar($course)) { $this->course = new \stdClass(); $this->course->id = $course; } else { $this->course = $course; } if (!is_null($context)) { $this->coursecontext = $context; } } /** * Returns an analytics course instance. * * Lazy load of course data, students and teachers. * * @param int|\stdClass $course Course object or course id * @param \context|null $context * @return \core_analytics\course */ public static function instance($course, ?\context $context = null) { $courseid = $course; if (!is_scalar($courseid)) { $courseid = $course->id; } if (self::$cachedid === $courseid) { return self::$cachedinstance; } $cachedinstance = new \core_analytics\course($course, $context); self::$cachedinstance = $cachedinstance; self::$cachedid = (int)$courseid; return self::$cachedinstance; } /** * get_id * * @return int */ public function get_id() { return $this->course->id; } /** * Loads the analytics course object. * * @return void */ protected function load() { // The instance constructor could be already loaded with the full course object. Using shortname // because it is a required course field. if (empty($this->course->shortname)) { $this->course = get_course($this->course->id); } $this->coursecontext = $this->get_context(); $this->now = time(); // Get the course users, including users assigned to student and teacher roles at an higher context. $cache = \cache::make_from_params(\cache_store::MODE_REQUEST, 'core_analytics', 'rolearchetypes'); // Flag the instance as loaded. $this->loaded = true; if (!$studentroles = $cache->get('student')) { $studentroles = array_keys(get_archetype_roles('student')); $cache->set('student', $studentroles); } $this->studentids = $this->get_user_ids($studentroles); if (!$teacherroles = $cache->get('teacher')) { $teacherroles = array_keys(get_archetype_roles('editingteacher') + get_archetype_roles('teacher')); $cache->set('teacher', $teacherroles); } $this->teacherids = $this->get_user_ids($teacherroles); } /** * The course short name * * @return string */ public function get_name() { return format_string($this->get_course_data()->shortname, true, array('context' => $this->get_context())); } /** * get_context * * @return \context */ public function get_context() { if ($this->coursecontext === null) { $this->coursecontext = \context_course::instance($this->course->id); } return $this->coursecontext; } /** * Get the course start timestamp. * * @return int Timestamp or 0 if has not started yet. */ public function get_start() { if ($this->starttime !== null) { return $this->starttime; } // The field always exist but may have no valid if the course is created through a sync process. if (!empty($this->get_course_data()->startdate)) { $this->starttime = (int)$this->get_course_data()->startdate; } else { $this->starttime = 0; } return $this->starttime; } /** * Guesses the start of the course based on students' activity and enrolment start dates. * * @return int */ public function guess_start() { global $DB; if (!$this->get_total_logs()) { // Can't guess. return 0; } if (!$logstore = \core_analytics\manager::get_analytics_logstore()) { return 0; } // We first try to find current course student logs. $firstlogs = array(); foreach ($this->get_students() as $studentid) { // Grrr, we are limited by logging API, we could do this easily with a // select min(timecreated) from xx where courseid = yy group by userid. // Filters based on the premise that more than 90% of people will be using // standard logstore, which contains a userid, contextlevel, contextinstanceid index. $select = "userid = :userid AND contextlevel = :contextlevel AND contextinstanceid = :contextinstanceid"; $params = array('userid' => $studentid, 'contextlevel' => CONTEXT_COURSE, 'contextinstanceid' => $this->get_id()); $events = $logstore->get_events_select($select, $params, 'timecreated ASC', 0, 1); if ($events) { $event = reset($events); $firstlogs[] = $event->timecreated; } } if (empty($firstlogs)) { // Can't guess if no student accesses. return 0; } sort($firstlogs); $firstlogsmedian = $this->median($firstlogs); $studentenrolments = enrol_get_course_users($this->get_id(), $this->get_students()); if (empty($studentenrolments)) { return 0; } $enrolstart = array(); foreach ($studentenrolments as $studentenrolment) { $enrolstart[] = ($studentenrolment->uetimestart) ? $studentenrolment->uetimestart : $studentenrolment->uetimecreated; } sort($enrolstart); $enrolstartmedian = $this->median($enrolstart); return intval(($enrolstartmedian + $firstlogsmedian) / 2); } /** * Get the course end timestamp. * * @return int Timestamp or 0 if time end was not set. */ public function get_end() { global $DB; if ($this->endtime !== null) { return $this->endtime; } // The enddate field is only available from Moodle 3.2 (MDL-22078). if (!empty($this->get_course_data()->enddate)) { $this->endtime = (int)$this->get_course_data()->enddate; return $this->endtime; } return 0; } /** * Get the course end timestamp. * * @return int Timestamp, \core_analytics\analysable::MAX_TIME if we don't know but ongoing and 0 if we can not work it out. */ public function guess_end() { global $DB; if ($this->get_total_logs() === 0) { // No way to guess if there are no logs. $this->endtime = 0; return $this->endtime; } list($filterselect, $filterparams) = $this->course_students_query_filter('ula'); // Consider the course open if there are still student accesses. $monthsago = time() - (WEEKSECS * 4 * 2); $select = $filterselect . ' AND timeaccess > :timeaccess'; $params = $filterparams + array('timeaccess' => $monthsago); $sql = "SELECT DISTINCT timeaccess FROM {user_lastaccess} ula JOIN {enrol} e ON e.courseid = ula.courseid JOIN {user_enrolments} ue ON e.id = ue.enrolid AND ue.userid = ula.userid WHERE $select"; if ($records = $DB->get_records_sql($sql, $params)) { return 0; } $sql = "SELECT DISTINCT timeaccess FROM {user_lastaccess} ula JOIN {enrol} e ON e.courseid = ula.courseid JOIN {user_enrolments} ue ON e.id = ue.enrolid AND ue.userid = ula.userid WHERE $filterselect AND ula.timeaccess != 0 ORDER BY timeaccess DESC"; $studentlastaccesses = $DB->get_fieldset_sql($sql, $filterparams); if (empty($studentlastaccesses)) { return 0; } sort($studentlastaccesses); return $this->median($studentlastaccesses); } /** * Returns a course plain object. * * @return \stdClass */ public function get_course_data() { if (!$this->loaded) { $this->load(); } return $this->course; } /** * Has the course started? * * @return bool */ public function was_started() { if ($this->started === null) { if ($this->get_start() === 0 || $this->now < $this->get_start()) { // Not yet started. $this->started = false; } else { $this->started = true; } } return $this->started; } /** * Has the course finished? * * @return bool */ public function is_finished() { if ($this->finished === null) { $endtime = $this->get_end(); if ($endtime === 0 || $this->now < $endtime) { // It is not yet finished or no idea when it finishes. $this->finished = false; } else { $this->finished = true; } } return $this->finished; } /** * Returns a list of user ids matching the specified roles in this course. * * @param array $roleids * @return array */ public function get_user_ids($roleids) { // We need to index by ra.id as a user may have more than 1 $roles role. $records = get_role_users($roleids, $this->get_context(), true, 'ra.id, u.id AS userid, r.id AS roleid', 'ra.id ASC'); // If a user have more than 1 $roles role array_combine will discard the duplicate. $callable = array($this, 'filter_user_id'); $userids = array_values(array_map($callable, $records)); return array_combine($userids, $userids); } /** * Returns the course students. * * @return int[] */ public function get_students() { if (!$this->loaded) { $this->load(); } return $this->studentids; } /** * Returns the total number of student logs in the course * * @return int */ public function get_total_logs() { global $DB; // No logs if no students. if (empty($this->get_students())) { return 0; } if ($this->ntotallogs === null) { list($filterselect, $filterparams) = $this->course_students_query_filter(); if (!$logstore = \core_analytics\manager::get_analytics_logstore()) { $this->ntotallogs = 0; } else { $this->ntotallogs = $logstore->get_events_select_count($filterselect, $filterparams); } } return $this->ntotallogs; } /** * Returns all the activities of the provided type the course has. * * @param string $activitytype * @return array */ public function get_all_activities($activitytype) { // Using is set because we set it to false if there are no activities. if (!isset($this->courseactivities[$activitytype])) { $modinfo = get_fast_modinfo($this->get_course_data(), -1); $instances = $modinfo->get_instances_of($activitytype); if ($instances) { $this->courseactivities[$activitytype] = array(); foreach ($instances as $instance) { // By context. $this->courseactivities[$activitytype][$instance->context->id] = $instance; } } else { $this->courseactivities[$activitytype] = false; } } return $this->courseactivities[$activitytype]; } /** * Returns the course students grades. * * @param array $courseactivities * @return array */ public function get_student_grades($courseactivities) { if (empty($courseactivities)) { return array(); } $grades = array(); foreach ($courseactivities as $contextid => $instance) { $gradesinfo = grade_get_grades($this->course->id, 'mod', $instance->modname, $instance->instance, $this->studentids); // Sort them by activity context and user. if ($gradesinfo && $gradesinfo->items) { foreach ($gradesinfo->items as $gradeitem) { foreach ($gradeitem->grades as $userid => $grade) { if (empty($grades[$contextid][$userid])) { // Initialise it as array because a single activity can have multiple grade items (e.g. workshop). $grades[$contextid][$userid] = array(); } $grades[$contextid][$userid][$gradeitem->id] = $grade; } } } } return $grades; } /** * Used by get_user_ids to extract the user id. * * @param \stdClass $record * @return int The user id. */ protected function filter_user_id($record) { return $record->userid; } /** * Returns the average time between 2 timestamps. * * @param int $start * @param int $end * @return array [starttime, averagetime, endtime] */ protected function update_loop_times($start, $end) { $avg = intval(($start + $end) / 2); return array($start, $avg, $end); } /** * Returns the query and params used to filter the logstore by this course students. * * @param string $prefix * @return array */ protected function course_students_query_filter($prefix = false) { global $DB; if ($prefix) { $prefix = $prefix . '.'; } // Check the amount of student logs in the 4 previous weeks. list($studentssql, $studentsparams) = $DB->get_in_or_equal($this->get_students(), SQL_PARAMS_NAMED); $filterselect = $prefix . 'courseid = :courseid AND ' . $prefix . 'userid ' . $studentssql; $filterparams = array('courseid' => $this->course->id) + $studentsparams; return array($filterselect, $filterparams); } /** * Calculate median * * Keys are ignored. * * @param int[]|float[] $values Sorted array of values * @return int */ protected function median($values) { $count = count($values); if ($count === 1) { return reset($values); } $middlevalue = (int)floor(($count - 1) / 2); if ($count % 2) { // Odd number, middle is the median. $median = $values[$middlevalue]; } else { // Even number, calculate avg of 2 medians. $low = $values[$middlevalue]; $high = $values[$middlevalue + 1]; $median = (($low + $high) / 2); } return intval($median); } }