completion/cron.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/>.
  16
  17 /**
  18  * Code used by scheduled tasks for reviewing and aggregating course completion criteria.
  19  *
  20  * @package core_completion
  21  * @category completion
  22  * @copyright 2009 Catalyst IT Ltd
  23  * @author Aaron Barnes <aaronb@catalyst.net.nz>
  24  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 defined('MOODLE_INTERNAL') || die();
  28 require_once($CFG->libdir.'/completionlib.php');
  29
  30 /**
  31  * Mark users as started if the config option is set
  32  *
  33  * @return void
  34  */
  35 function completion_cron_mark_started() {
  36     global $CFG, $DB;
  37
  38     if (debugging()) {
  39         mtrace('Marking users as started');
  40     }
  41
  42     if (!empty($CFG->gradebookroles)) {
  43         $roles = ' AND ra.roleid IN ('.$CFG->gradebookroles.')';
  44     } else {
  45         // This causes it to default to everyone (if there is no student role)
  46         $roles = '';
  47     }
  48
  49     /**
  50      * A quick explaination of this horrible looking query
  51      *
  52      * It's purpose is to locate all the active participants
  53      * of a course with course completion enabled.
  54      *
  55      * We also only want the users with no course_completions
  56      * record as this functions job is to create the missing
  57      * ones :)
  58      *
  59      * We want to record the user's enrolment start time for the
  60      * course. This gets tricky because there can be multiple
  61      * enrolment plugins active in a course, hence the possibility
  62      * of multiple records for each couse/user in the results
  63      */
  64     $sql = "
  65         SELECT
  66             c.id AS course,
  67             u.id AS userid,
  68             crc.id AS completionid,
  69             ue.timestart AS timeenrolled,
  70             ue.timecreated
  71         FROM
  72             {user} u
  73         INNER JOIN
  74             {user_enrolments} ue
  75          ON ue.userid = u.id
  76         INNER JOIN
  77             {enrol} e
  78          ON e.id = ue.enrolid
  79         INNER JOIN
  80             {course} c
  81          ON c.id = e.courseid
  82         INNER JOIN
  83             {role_assignments} ra
  84          ON ra.userid = u.id
  85         LEFT JOIN
  86             {course_completions} crc
  87          ON crc.course = c.id
  88         AND crc.userid = u.id
  89         WHERE
  90             c.enablecompletion = 1
  91         AND crc.timeenrolled IS NULL
  92         AND ue.status = 0
  93         AND e.status = 0
  94         AND u.deleted = 0
  95         AND ue.timestart < ?
  96         AND (ue.timeend > ? OR ue.timeend = 0)
  97             $roles
  98         ORDER BY
  99             course,
 100             userid
 101     ";
 102
 103     $now = time();
 104     $rs = $DB->get_recordset_sql($sql, array($now, $now, $now, $now));
 105
 106     // Check if result is empty
 107     if (!$rs->valid()) {
 108         $rs->close(); // Not going to iterate (but exit), close rs
 109         return;
 110     }
 111
 112     /**
 113      * An explaination of the following loop
 114      *
 115      * We are essentially doing a group by in the code here (as I can't find
 116      * a decent way of doing it in the sql).
 117      *
 118      * Since there can be multiple enrolment plugins for each course, we can have
 119      * multiple rows for each particpant in the query result. This isn't really
 120      * a problem until you combine it with the fact that the enrolment plugins
 121      * can save the enrol start time in either timestart or timeenrolled.
 122      *
 123      * The purpose of this loop is to find the earliest enrolment start time for
 124      * each participant in each course.
 125      */
 126     $prev = null;
 127     while ($rs->valid() || $prev) {
 128
 129         $current = $rs->current();
 130
 131         if (!isset($current->course)) {
 132             $current = false;
 133         }
 134         else {
 135             // Not all enrol plugins fill out timestart correctly, so use whichever
 136             // is non-zero
 137             $current->timeenrolled = max($current->timecreated, $current->timeenrolled);
 138         }
 139
 140         // If we are at the last record,
 141         // or we aren't at the first and the record is for a diff user/course
 142         if ($prev &&
 143             (!$rs->valid() ||
 144             ($current->course != $prev->course || $current->userid != $prev->userid))) {
 145
 146             $completion = new completion_completion();
 147             $completion->userid = $prev->userid;
 148             $completion->course = $prev->course;
 149             $completion->timeenrolled = (string) $prev->timeenrolled;
 150             $completion->timestarted = 0;
 151             $completion->reaggregate = time();
 152
 153             if ($prev->completionid) {
 154                 $completion->id = $prev->completionid;
 155             }
 156
 157             $completion->mark_enrolled();
 158
 159             if (debugging()) {
 160                 mtrace('Marked started user '.$prev->userid.' in course '.$prev->course);
 161             }
 162         }
 163         // Else, if this record is for the same user/course
 164         elseif ($prev && $current) {
 165             // Use oldest timeenrolled
 166             $current->timeenrolled = min($current->timeenrolled, $prev->timeenrolled);
 167         }
 168
 169         // Move current record to previous
 170         $prev = $current;
 171
 172         // Move to next record
 173         $rs->next();
 174     }
 175
 176     $rs->close();
 177 }
 178
 179 /**
 180  * Run installed criteria's data aggregation methods
 181  *
 182  * Loop through each installed criteria and run the
 183  * cron() method if it exists
 184  *
 185  * @return void
 186  */
 187 function completion_cron_criteria() {
 188
 189     // Process each criteria type
 190     global $CFG, $COMPLETION_CRITERIA_TYPES;
 191
 192     foreach ($COMPLETION_CRITERIA_TYPES as $type) {
 193
 194         $object = 'completion_criteria_'.$type;
 195         require_once $CFG->dirroot.'/completion/criteria/'.$object.'.php';
 196
 197         $class = new $object();
 198
 199         // Run the criteria type's cron method, if it has one
 200         if (method_exists($class, 'cron')) {
 201
 202             if (debugging()) {
 203                 mtrace('Running '.$object.'->cron()');
 204             }
 205             $class->cron();
 206         }
 207     }
 208 }
 209
 210 /**
 211  * Aggregate each user's criteria completions
 212  */
 213 function completion_cron_completions() {
 214     global $DB;
 215
 216     if (debugging()) {
 217         mtrace('Aggregating completions');
 218     }
 219
 220     // Save time started
 221     $timestarted = time();
 222
 223     // Grab all criteria and their associated criteria completions
 224     $sql = '
 225         SELECT DISTINCT
 226             c.id AS course,
 227             cr.id AS criteriaid,
 228             crc.userid AS userid,
 229             cr.criteriatype AS criteriatype,
 230             cc.timecompleted AS timecompleted
 231         FROM
 232             {course_completion_criteria} cr
 233         INNER JOIN
 234             {course} c
 235          ON cr.course = c.id
 236         INNER JOIN
 237             {course_completions} crc
 238          ON crc.course = c.id
 239         LEFT JOIN
 240             {course_completion_crit_compl} cc
 241          ON cc.criteriaid = cr.id
 242         AND crc.userid = cc.userid
 243         WHERE
 244             c.enablecompletion = 1
 245         AND crc.timecompleted IS NULL
 246         AND crc.reaggregate > 0
 247         AND crc.reaggregate < :timestarted
 248         ORDER BY
 249             course,
 250             userid
 251     ';
 252
 253     $rs = $DB->get_recordset_sql($sql, array('timestarted' => $timestarted));
 254
 255     // Check if result is empty
 256     if (!$rs->valid()) {
 257         $rs->close(); // Not going to iterate (but exit), close rs
 258         return;
 259     }
 260
 261     $current_user = null;
 262     $current_course = null;
 263     $completions = array();
 264
 265     while (1) {
 266
 267         // Grab records for current user/course
 268         foreach ($rs as $record) {
 269             // If we are still grabbing the same users completions
 270             if ($record->userid === $current_user && $record->course === $current_course) {
 271                 $completions[$record->criteriaid] = $record;
 272             } else {
 273                 break;
 274             }
 275         }
 276
 277         // Aggregate
 278         if (!empty($completions)) {
 279
 280             if (debugging()) {
 281                 mtrace('Aggregating completions for user '.$current_user.' in course '.$current_course);
 282             }
 283
 284             // Get course info object
 285             $info = new completion_info((object)array('id' => $current_course));
 286
 287             // Setup aggregation
 288             $overall = $info->get_aggregation_method();
 289             $activity = $info->get_aggregation_method(COMPLETION_CRITERIA_TYPE_ACTIVITY);
 290             $prerequisite = $info->get_aggregation_method(COMPLETION_CRITERIA_TYPE_COURSE);
 291             $role = $info->get_aggregation_method(COMPLETION_CRITERIA_TYPE_ROLE);
 292
 293             $overall_status = null;
 294             $activity_status = null;
 295             $prerequisite_status = null;
 296             $role_status = null;
 297
 298             // Get latest timecompleted
 299             $timecompleted = null;
 300
 301             // Check each of the criteria
 302             foreach ($completions as $params) {
 303                 $timecompleted = max($timecompleted, $params->timecompleted);
 304
 305                 $completion = new completion_criteria_completion((array)$params, false);
 306
 307                 // Handle aggregation special cases
 308                 if ($params->criteriatype == COMPLETION_CRITERIA_TYPE_ACTIVITY) {
 309                     completion_cron_aggregate($activity, $completion->is_complete(), $activity_status);
 310                 } else if ($params->criteriatype == COMPLETION_CRITERIA_TYPE_COURSE) {
 311                     completion_cron_aggregate($prerequisite, $completion->is_complete(), $prerequisite_status);
 312                 } else if ($params->criteriatype == COMPLETION_CRITERIA_TYPE_ROLE) {
 313                     completion_cron_aggregate($role, $completion->is_complete(), $role_status);
 314                 } else {
 315                     completion_cron_aggregate($overall, $completion->is_complete(), $overall_status);
 316                 }
 317             }
 318
 319             // Include role criteria aggregation in overall aggregation
 320             if ($role_status !== null) {
 321                 completion_cron_aggregate($overall, $role_status, $overall_status);
 322             }
 323
 324             // Include activity criteria aggregation in overall aggregation
 325             if ($activity_status !== null) {
 326                 completion_cron_aggregate($overall, $activity_status, $overall_status);
 327             }
 328
 329             // Include prerequisite criteria aggregation in overall aggregation
 330             if ($prerequisite_status !== null) {
 331                 completion_cron_aggregate($overall, $prerequisite_status, $overall_status);
 332             }
 333
 334             // If aggregation status is true, mark course complete for user
 335             if ($overall_status) {
 336                 if (debugging()) {
 337                     mtrace('Marking complete');
 338                 }
 339
 340                 $ccompletion = new completion_completion(array('course' => $params->course, 'userid' => $params->userid));
 341                 $ccompletion->mark_complete($timecompleted);
 342             }
 343         }
 344
 345         // If this is the end of the recordset, break the loop
 346         if (!$rs->valid()) {
 347             $rs->close();
 348             break;
 349         }
 350
 351         // New/next user, update user details, reset completions
 352         $current_user = $record->userid;
 353         $current_course = $record->course;
 354         $completions = array();
 355         $completions[$record->criteriaid] = $record;
 356     }
 357
 358     // Mark all users as aggregated
 359     $sql = "
 360         UPDATE
 361             {course_completions}
 362         SET
 363             reaggregate = 0
 364         WHERE
 365             reaggregate < :timestarted
 366         AND reaggregate > 0
 367     ";
 368
 369     $DB->execute($sql, array('timestarted' => $timestarted));
 370 }
 371
 372 /**
 373  * Aggregate criteria status's as per configured aggregation method
 374  *
 375  * @param int $method COMPLETION_AGGREGATION_* constant
 376  * @param bool $data Criteria completion status
 377  * @param bool|null $state Aggregation state
 378  */
 379 function completion_cron_aggregate($method, $data, &$state) {
 380     if ($method == COMPLETION_AGGREGATION_ALL) {
 381         if ($data && $state !== false) {
 382             $state = true;
 383         } else {
 384             $state = false;
 385         }
 386     } elseif ($method == COMPLETION_AGGREGATION_ANY) {
 387         if ($data) {
 388             $state = true;
 389         } else if (!$data && $state === null) {
 390             $state = false;
 391         }
 392     }
 393 }