Merge branch 'MDL-64666-master' of git://github.com/aanabit/moodle
[moodle.git] / 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  * 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  */
27 defined('MOODLE_INTERNAL') || die();
28 require_once($CFG->libdir.'/completionlib.php');
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;
38     if (debugging()) {
39         mtrace('Marking users as started');
40     }
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     }
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     ";
103     $now = time();
104     $rs = $DB->get_recordset_sql($sql, array($now, $now, $now, $now));
106     // Check if result is empty
107     if (!$rs->valid()) {
108         $rs->close(); // Not going to iterate (but exit), close rs
109         return;
110     }
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) {
129         $current = $rs->current();
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         }
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))) {
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();
153             if ($prev->completionid) {
154                 $completion->id = $prev->completionid;
155             }
157             $completion->mark_enrolled();
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         }
169         // Move current record to previous
170         $prev = $current;
172         // Move to next record
173         $rs->next();
174     }
176     $rs->close();
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() {
189     // Process each criteria type
190     global $CFG, $COMPLETION_CRITERIA_TYPES;
192     foreach ($COMPLETION_CRITERIA_TYPES as $type) {
194         $object = 'completion_criteria_'.$type;
195         require_once $CFG->dirroot.'/completion/criteria/'.$object.'.php';
197         $class = new $object();
199         // Run the criteria type's cron method, if it has one
200         if (method_exists($class, 'cron')) {
202             if (debugging()) {
203                 mtrace('Running '.$object.'->cron()');
204             }
205             $class->cron();
206         }
207     }
210 /**
211  * Aggregate each user's criteria completions
212  */
213 function completion_cron_completions() {
214     global $DB;
216     if (debugging()) {
217         mtrace('Aggregating completions');
218     }
220     // Save time started
221     $timestarted = time();
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     ';
253     $rs = $DB->get_recordset_sql($sql, array('timestarted' => $timestarted));
255     // Check if result is empty
256     if (!$rs->valid()) {
257         $rs->close(); // Not going to iterate (but exit), close rs
258         return;
259     }
261     $current_user = null;
262     $current_course = null;
263     $completions = array();
265     while (1) {
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         }
277         // Aggregate
278         if (!empty($completions)) {
280             if (debugging()) {
281                 mtrace('Aggregating completions for user '.$current_user.' in course '.$current_course);
282             }
284             // Get course info object
285             $info = new completion_info((object)array('id' => $current_course));
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);
293             $overall_status = null;
294             $activity_status = null;
295             $prerequisite_status = null;
296             $role_status = null;
298             // Get latest timecompleted
299             $timecompleted = null;
301             // Check each of the criteria
302             foreach ($completions as $params) {
303                 $timecompleted = max($timecompleted, $params->timecompleted);
305                 $completion = new completion_criteria_completion((array)$params, false);
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             }
319             // Include role criteria aggregation in overall aggregation
320             if ($role_status !== null) {
321                 completion_cron_aggregate($overall, $role_status, $overall_status);
322             }
324             // Include activity criteria aggregation in overall aggregation
325             if ($activity_status !== null) {
326                 completion_cron_aggregate($overall, $activity_status, $overall_status);
327             }
329             // Include prerequisite criteria aggregation in overall aggregation
330             if ($prerequisite_status !== null) {
331                 completion_cron_aggregate($overall, $prerequisite_status, $overall_status);
332             }
334             // If aggregation status is true, mark course complete for user
335             if ($overall_status) {
336                 if (debugging()) {
337                     mtrace('Marking complete');
338                 }
340                 $ccompletion = new completion_completion(array('course' => $params->course, 'userid' => $params->userid));
341                 $ccompletion->mark_complete($timecompleted);
342             }
343         }
345         // If this is the end of the recordset, break the loop
346         if (!$rs->valid()) {
347             $rs->close();
348             break;
349         }
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     }
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     ";
369     $DB->execute($sql, array('timestarted' => $timestarted));
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     }