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