Merge branch 'MDL-65051-master' of git://github.com/lameze/moodle
[moodle.git] / completion / cron.php
CommitLineData
2be4d090 1<?php
2be4d090
MD
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
2be4d090 17/**
0628925b 18 * Code used by scheduled tasks for reviewing and aggregating course completion criteria.
2be4d090 19 *
836375ec
SH
20 * @package core_completion
21 * @category completion
2be4d090 22 * @copyright 2009 Catalyst IT Ltd
836375ec
SH
23 * @author Aaron Barnes <aaronb@catalyst.net.nz>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2be4d090 25 */
2be4d090 26
836375ec 27defined('MOODLE_INTERNAL') || die();
f55ff38a 28require_once($CFG->libdir.'/completionlib.php');
2be4d090 29
2be4d090
MD
30/**
31 * Mark users as started if the config option is set
32 *
836375ec 33 * @return void
2be4d090
MD
34 */
35function completion_cron_mark_started() {
926f5143 36 global $CFG, $DB;
2be4d090
MD
37
38 if (debugging()) {
39 mtrace('Marking users as started');
40 }
41
926f5143
DP
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
89482538
AB
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 */
2be4d090 64 $sql = "
89482538 65 SELECT
2be4d090 66 c.id AS course,
926f5143
DP
67 u.id AS userid,
68 crc.id AS completionid,
69 ue.timestart AS timeenrolled,
70 ue.timecreated
2be4d090 71 FROM
926f5143
DP
72 {user} u
73 INNER JOIN
89482538 74 {user_enrolments} ue
926f5143 75 ON ue.userid = u.id
2be4d090 76 INNER JOIN
89482538
AB
77 {enrol} e
78 ON e.id = ue.enrolid
2be4d090 79 INNER JOIN
89482538
AB
80 {course} c
81 ON c.id = e.courseid
926f5143
DP
82 INNER JOIN
83 {role_assignments} ra
84 ON ra.userid = u.id
2be4d090
MD
85 LEFT JOIN
86 {course_completions} crc
87 ON crc.course = c.id
926f5143 88 AND crc.userid = u.id
2be4d090 89 WHERE
89482538 90 c.enablecompletion = 1
926f5143
DP
91 AND crc.timeenrolled IS NULL
92 AND ue.status = 0
93 AND e.status = 0
94 AND u.deleted = 0
89482538
AB
95 AND ue.timestart < ?
96 AND (ue.timeend > ? OR ue.timeend = 0)
926f5143
DP
97 $roles
98 ORDER BY
99 course,
100 userid
2be4d090
MD
101 ";
102
89482538 103 $now = time();
926f5143
DP
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();
2be4d090
MD
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 *
836375ec 185 * @return void
2be4d090
MD
186 */
187function 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;
60829d80 195 require_once $CFG->dirroot.'/completion/criteria/'.$object.'.php';
2be4d090
MD
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
2be4d090
MD
212 */
213function 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,
24a3b341 228 crc.userid AS userid,
2be4d090
MD
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
89482538
AB
237 {course_completions} crc
238 ON crc.course = c.id
2be4d090
MD
239 LEFT JOIN
240 {course_completion_crit_compl} cc
241 ON cc.criteriaid = cr.id
89482538 242 AND crc.userid = cc.userid
2be4d090 243 WHERE
89482538 244 c.enablecompletion = 1
2be4d090
MD
245 AND crc.timecompleted IS NULL
246 AND crc.reaggregate > 0
24a3b341 247 AND crc.reaggregate < :timestarted
2be4d090
MD
248 ORDER BY
249 course,
250 userid
251 ';
252
419178d7
EL
253 $rs = $DB->get_recordset_sql($sql, array('timestarted' => $timestarted));
254
2be4d090 255 // Check if result is empty
419178d7
EL
256 if (!$rs->valid()) {
257 $rs->close(); // Not going to iterate (but exit), close rs
2be4d090
MD
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
dbfcf440 305 $completion = new completion_criteria_completion((array)$params, false);
2be4d090
MD
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
7ba1c665
AB
365 reaggregate < :timestarted
366 AND reaggregate > 0
2be4d090
MD
367 ";
368
7ba1c665 369 $DB->execute($sql, array('timestarted' => $timestarted));
2be4d090
MD
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
2be4d090
MD
378 */
379function 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}