MDL-37473 completion: Add missing cap checks to tracked users functions
[moodle.git] / lib / completionlib.php
CommitLineData
4e781c7b 1<?php
117bd748
PS
2// This file is part of Moodle - http://moodle.org/
3//
09639ded 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.
117bd748 13//
09639ded 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/**
836375ec
SH
18 * Contains classes, functions and constants used during the tracking
19 * of activity completion for users.
09639ded 20 *
21 * Completion top-level options (admin setting enablecompletion)
117bd748 22 *
836375ec
SH
23 * @package core_completion
24 * @category completion
25 * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
26 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
09639ded 27 */
4e781c7b 28
78bfb562
PS
29defined('MOODLE_INTERNAL') || die();
30
836375ec
SH
31/**
32 * Include the required completion libraries
33 */
75342343 34require_once $CFG->dirroot.'/completion/completion_aggregation.php';
60829d80 35require_once $CFG->dirroot.'/completion/criteria/completion_criteria.php';
75342343
AB
36require_once $CFG->dirroot.'/completion/completion_completion.php';
37require_once $CFG->dirroot.'/completion/completion_criteria_completion.php';
78bfb562
PS
38
39
836375ec
SH
40/**
41 * The completion system is enabled in this site/course
42 */
0d5d12bd 43define('COMPLETION_ENABLED', 1);
836375ec
SH
44/**
45 * The completion system is not enabled in this site/course
46 */
0d5d12bd 47define('COMPLETION_DISABLED', 0);
4e781c7b 48
836375ec
SH
49/**
50 * Completion tracking is disabled for this activity
51 * This is a completion tracking option per-activity (course_modules/completion)
52 */
0d5d12bd 53define('COMPLETION_TRACKING_NONE', 0);
836375ec
SH
54
55/**
56 * Manual completion tracking (user ticks box) is enabled for this activity
57 * This is a completion tracking option per-activity (course_modules/completion)
58 */
0d5d12bd 59define('COMPLETION_TRACKING_MANUAL', 1);
836375ec
SH
60/**
61 * Automatic completion tracking (system ticks box) is enabled for this activity
62 * This is a completion tracking option per-activity (course_modules/completion)
63 */
0d5d12bd 64define('COMPLETION_TRACKING_AUTOMATIC', 2);
4e781c7b 65
836375ec
SH
66/**
67 * The user has not completed this activity.
68 * This is a completion state value (course_modules_completion/completionstate)
69 */
0d5d12bd 70define('COMPLETION_INCOMPLETE', 0);
836375ec
SH
71/**
72 * The user has completed this activity. It is not specified whether they have
73 * passed or failed it.
74 * This is a completion state value (course_modules_completion/completionstate)
75 */
0d5d12bd 76define('COMPLETION_COMPLETE', 1);
836375ec
SH
77/**
78 * The user has completed this activity with a grade above the pass mark.
79 * This is a completion state value (course_modules_completion/completionstate)
80 */
0d5d12bd 81define('COMPLETION_COMPLETE_PASS', 2);
836375ec
SH
82/**
83 * The user has completed this activity but their grade is less than the pass mark
84 * This is a completion state value (course_modules_completion/completionstate)
85 */
0d5d12bd 86define('COMPLETION_COMPLETE_FAIL', 3);
4e781c7b 87
836375ec
SH
88/**
89 * The effect of this change to completion status is unknown.
90 * A completion effect changes (used only in update_state)
91 */
0d5d12bd 92define('COMPLETION_UNKNOWN', -1);
836375ec
SH
93/**
94 * The user's grade has changed, so their new state might be
95 * COMPLETION_COMPLETE_PASS or COMPLETION_COMPLETE_FAIL.
96 * A completion effect changes (used only in update_state)
97 */
0d5d12bd 98define('COMPLETION_GRADECHANGE', -2);
4e781c7b 99
836375ec 100/**
95dd54ee 101 * User must view this activity.
836375ec
SH
102 * Whether view is required to create an activity (course_modules/completionview)
103 */
0d5d12bd 104define('COMPLETION_VIEW_REQUIRED', 1);
836375ec
SH
105/**
106 * User does not need to view this activity
107 * Whether view is required to create an activity (course_modules/completionview)
108 */
0d5d12bd 109define('COMPLETION_VIEW_NOT_REQUIRED', 0);
4e781c7b 110
836375ec
SH
111/**
112 * User has viewed this activity.
113 * Completion viewed state (course_modules_completion/viewed)
114 */
0d5d12bd 115define('COMPLETION_VIEWED', 1);
836375ec
SH
116/**
117 * User has not viewed this activity.
118 * Completion viewed state (course_modules_completion/viewed)
119 */
0d5d12bd 120define('COMPLETION_NOT_VIEWED', 0);
4e781c7b 121
836375ec
SH
122/**
123 * Cache expiry time in seconds (10 minutes)
124 * Completion cacheing
125 */
0d5d12bd 126define('COMPLETION_CACHE_EXPIRY', 10*60);
4e781c7b 127
836375ec
SH
128/**
129 * Completion details should be ORed together and you should return false if
130 * none apply.
131 */
0d5d12bd 132define('COMPLETION_OR', false);
836375ec
SH
133/**
134 * Completion details should be ANDed together and you should return true if
135 * none apply
136 */
0d5d12bd 137define('COMPLETION_AND', true);
4e781c7b 138
836375ec
SH
139/**
140 * Course completion criteria aggregation method.
141 */
142define('COMPLETION_AGGREGATION_ALL', 1);
143/**
144 * Course completion criteria aggregation method.
145 */
146define('COMPLETION_AGGREGATION_ANY', 2);
2be4d090
MD
147
148
4e781c7b 149/**
150 * Class represents completion information for a course.
09639ded 151 *
152 * Does not contain any data, so you can safely construct it multiple times
153 * without causing any problems.
154 *
836375ec
SH
155 * @package core
156 * @category completion
157 * @copyright 2008 Sam Marshall
09639ded 158 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4e781c7b 159 */
160class completion_info {
836375ec 161
95dd54ee 162 /* @var stdClass Course object passed during construction */
4e781c7b 163 private $course;
0d5d12bd 164
95dd54ee 165 /* @var int Course id */
2be4d090
MD
166 public $course_id;
167
f55ff38a 168 /* @var array Completion criteria {@link completion_info::get_criteria()} */
2be4d090
MD
169 private $criteria;
170
171 /**
172 * Return array of aggregation methods
836375ec 173 * @return array
2be4d090
MD
174 */
175 public static function get_aggregation_methods() {
176 return array(
836375ec
SH
177 COMPLETION_AGGREGATION_ALL => get_string('all'),
178 COMPLETION_AGGREGATION_ANY => get_string('any', 'completion'),
2be4d090
MD
179 );
180 }
181
4e781c7b 182 /**
183 * Constructs with course details.
184 *
836375ec
SH
185 * When instantiating a new completion info object you must provide a course
186 * object with at least id, and enablecompletion properties.
187 *
188 * @param stdClass $course Moodle course object.
4e781c7b 189 */
49f6e5f4 190 public function __construct($course) {
0d5d12bd 191 $this->course = $course;
2be4d090 192 $this->course_id = $course->id;
4e781c7b 193 }
194
195 /**
09639ded 196 * Determines whether completion is enabled across entire site.
117bd748 197 *
836375ec 198 * @return bool COMPLETION_ENABLED (true) if completion is enabled for the site,
4e781c7b 199 * COMPLETION_DISABLED (false) if it's complete
200 */
201 public static function is_enabled_for_site() {
202 global $CFG;
1caea91e 203 return !empty($CFG->enablecompletion);
4e781c7b 204 }
0d5d12bd 205
4e781c7b 206 /**
207 * Checks whether completion is enabled in a particular course and possibly
208 * activity.
209 *
836375ec 210 * @param stdClass|cm_info $cm Course-module object. If not specified, returns the course
4e781c7b 211 * completion enable state.
09639ded 212 * @return mixed COMPLETION_ENABLED or COMPLETION_DISABLED (==0) in the case of
4e781c7b 213 * site and course; COMPLETION_TRACKING_MANUAL, _AUTOMATIC or _NONE (==0)
214 * for a course-module.
215 */
836375ec 216 public function is_enabled($cm = null) {
7075e37e 217 global $CFG, $DB;
d7d87535 218
219 // First check global completion
250c0533 220 if (!isset($CFG->enablecompletion) || $CFG->enablecompletion == COMPLETION_DISABLED) {
4e781c7b 221 return COMPLETION_DISABLED;
222 }
0d5d12bd 223
7075e37e
AB
224 // Load data if we do not have enough
225 if (!isset($this->course->enablecompletion)) {
226 $this->course->enablecompletion = $DB->get_field('course', 'enablecompletion', array('id' => $this->course->id));
227 }
228
4e781c7b 229 // Check course completion
0d5d12bd 230 if ($this->course->enablecompletion == COMPLETION_DISABLED) {
4e781c7b 231 return COMPLETION_DISABLED;
232 }
0d5d12bd 233
4e781c7b 234 // If there was no $cm and we got this far, then it's enabled
0d5d12bd 235 if (!$cm) {
4e781c7b 236 return COMPLETION_ENABLED;
237 }
0d5d12bd 238
4e781c7b 239 // Return course-module completion value
240 return $cm->completion;
241 }
0d5d12bd 242
2af26b12 243 /**
244 * Displays the 'Your progress' help icon, if completion tracking is enabled.
245 * Just prints the result of display_help_icon().
836375ec
SH
246 *
247 * @deprecated since Moodle 2.0 - Use display_help_icon instead.
2af26b12 248 */
249 public function print_help_icon() {
250 print $this->display_help_icon();
251 }
252
e3568fde 253 /**
563e97b8 254 * Returns the 'Your progress' help icon, if completion tracking is enabled.
836375ec 255 *
563e97b8 256 * @return string HTML code for help icon, or blank if not needed
e3568fde 257 */
563e97b8 258 public function display_help_icon() {
aa9a6867 259 global $PAGE, $OUTPUT;
563e97b8 260 $result = '';
e3568fde 261 if ($this->is_enabled() && !$PAGE->user_is_editing() && isloggedin() && !isguestuser()) {
e40bd746
FM
262 $result .= html_writer::tag('div', get_string('yourprogress','completion') .
263 $OUTPUT->help_icon('completionicons', 'completion'), array('id' => 'completionprogressid',
264 'class' => 'completionprogress'));
e3568fde 265 }
563e97b8 266 return $result;
e3568fde 267 }
2be4d090
MD
268
269 /**
270 * Get a course completion for a user
836375ec
SH
271 *
272 * @param int $user_id User id
273 * @param int $criteriatype Specific criteria type to return
95dd54ee 274 * @return bool|completion_criteria_completion returns false on fail
2be4d090
MD
275 */
276 public function get_completion($user_id, $criteriatype) {
277 $completions = $this->get_completions($user_id, $criteriatype);
278
279 if (empty($completions)) {
280 return false;
281 } elseif (count($completions) > 1) {
282 print_error('multipleselfcompletioncriteria', 'completion');
283 }
284
285 return $completions[0];
286 }
287
288 /**
289 * Get all course criteria's completion objects for a user
836375ec
SH
290 *
291 * @param int $user_id User id
292 * @param int $criteriatype Specific criteria type to return (optional)
293 * @return array
2be4d090
MD
294 */
295 public function get_completions($user_id, $criteriatype = null) {
296 $criterion = $this->get_criteria($criteriatype);
297
298 $completions = array();
299
300 foreach ($criterion as $criteria) {
301 $params = array(
302 'course' => $this->course_id,
303 'userid' => $user_id,
304 'criteriaid' => $criteria->id
305 );
306
307 $completion = new completion_criteria_completion($params);
308 $completion->attach_criteria($criteria);
309
310 $completions[] = $completion;
311 }
312
313 return $completions;
314 }
315
316 /**
317 * Get completion object for a user and a criteria
836375ec
SH
318 *
319 * @param int $user_id User id
320 * @param completion_criteria $criteria Criteria object
321 * @return completion_criteria_completion
2be4d090
MD
322 */
323 public function get_user_completion($user_id, $criteria) {
324 $params = array(
dbfcf440
AB
325 'course' => $this->course_id,
326 'userid' => $user_id,
2be4d090 327 'criteriaid' => $criteria->id,
2be4d090
MD
328 );
329
330 $completion = new completion_criteria_completion($params);
331 return $completion;
332 }
333
334 /**
335 * Check if course has completion criteria set
336 *
836375ec 337 * @return bool Returns true if there are criteria
2be4d090
MD
338 */
339 public function has_criteria() {
340 $criteria = $this->get_criteria();
341
342 return (bool) count($criteria);
343 }
344
2be4d090
MD
345 /**
346 * Get course completion criteria
836375ec
SH
347 *
348 * @param int $criteriatype Specific criteria type to return (optional)
2be4d090
MD
349 */
350 public function get_criteria($criteriatype = null) {
351
352 // Fill cache if empty
353 if (!is_array($this->criteria)) {
354 global $DB;
355
356 $params = array(
357 'course' => $this->course->id
358 );
359
360 // Load criteria from database
361 $records = (array)$DB->get_records('course_completion_criteria', $params);
362
363 // Build array of criteria objects
364 $this->criteria = array();
365 foreach ($records as $record) {
dbfcf440 366 $this->criteria[$record->id] = completion_criteria::factory((array)$record);
2be4d090
MD
367 }
368 }
369
370 // If after all criteria
371 if ($criteriatype === null) {
372 return $this->criteria;
373 }
374
375 // If we are only after a specific criteria type
376 $criteria = array();
377 foreach ($this->criteria as $criterion) {
378
379 if ($criterion->criteriatype != $criteriatype) {
380 continue;
381 }
382
383 $criteria[$criterion->id] = $criterion;
384 }
385
386 return $criteria;
387 }
388
389 /**
390 * Get aggregation method
836375ec
SH
391 *
392 * @param int $criteriatype If none supplied, get overall aggregation method (optional)
393 * @return int One of COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY
2be4d090
MD
394 */
395 public function get_aggregation_method($criteriatype = null) {
396 $params = array(
397 'course' => $this->course_id,
398 'criteriatype' => $criteriatype
399 );
400
401 $aggregation = new completion_aggregation($params);
402
403 if (!$aggregation->id) {
404 $aggregation->method = COMPLETION_AGGREGATION_ALL;
405 }
406
407 return $aggregation->method;
408 }
409
410 /**
411 * Get incomplete course completion criteria
836375ec
SH
412 *
413 * @return array
2be4d090
MD
414 */
415 public function get_incomplete_criteria() {
416 $incomplete = array();
417
418 foreach ($this->get_criteria() as $criteria) {
419 if (!$criteria->is_complete()) {
420 $incomplete[] = $criteria;
421 }
422 }
423
424 return $incomplete;
425 }
426
427 /**
428 * Clear old course completion criteria
429 */
430 public function clear_criteria() {
431 global $DB;
432 $DB->delete_records('course_completion_criteria', array('course' => $this->course_id));
433 $DB->delete_records('course_completion_aggr_methd', array('course' => $this->course_id));
434
435 $this->delete_course_completion_data();
436 }
437
438 /**
439 * Has the supplied user completed this course
836375ec
SH
440 *
441 * @param int $user_id User's id
442 * @return boolean
2be4d090
MD
443 */
444 public function is_course_complete($user_id) {
445 $params = array(
446 'userid' => $user_id,
447 'course' => $this->course_id
448 );
449
450 $ccompletion = new completion_completion($params);
451 return $ccompletion->is_complete();
452 }
453
4e781c7b 454 /**
455 * Updates (if necessary) the completion state of activity $cm for the given
456 * user.
09639ded 457 *
4e781c7b 458 * For manual completion, this function is called when completion is toggled
459 * with $possibleresult set to the target state.
09639ded 460 *
4e781c7b 461 * For automatic completion, this function should be called every time a module
462 * does something which might influence a user's completion state. For example,
463 * if a forum provides options for marking itself 'completed' once a user makes
464 * N posts, this function should be called every time a user makes a new post.
465 * [After the post has been saved to the database]. When calling, you do not
466 * need to pass in the new completion state. Instead this function carries out
467 * completion calculation by checking grades and viewed state itself, and
468 * calling the involved module via modulename_get_completion_state() to check
469 * module-specific conditions.
470 *
7142a755 471 * @param stdClass|cm_info $cm Course-module
4e781c7b 472 * @param int $possibleresult Expected completion result. If the event that
473 * has just occurred (e.g. add post) can only result in making the activity
474 * complete when it wasn't before, use COMPLETION_COMPLETE. If the event that
475 * has just occurred (e.g. delete post) can only result in making the activity
476 * not complete when it was previously complete, use COMPLETION_INCOMPLETE.
477 * Otherwise use COMPLETION_UNKNOWN. Setting this value to something other than
478 * COMPLETION_UNKNOWN significantly improves performance because it will abandon
479 * processing early if the user's completion state already matches the expected
480 * result. For manual events, COMPLETION_COMPLETE or COMPLETION_INCOMPLETE
481 * must be used; these directly set the specified state.
482 * @param int $userid User ID to be updated. Default 0 = current user
09639ded 483 * @return void
4e781c7b 484 */
0d5d12bd 485 public function update_state($cm, $possibleresult=COMPLETION_UNKNOWN, $userid=0) {
486 global $USER, $SESSION;
d7d87535 487
0d5d12bd 488 // Do nothing if completion is not enabled for that activity
489 if (!$this->is_enabled($cm)) {
4e781c7b 490 return;
491 }
0d5d12bd 492
4e781c7b 493 // Get current value of completion state and do nothing if it's same as
494 // the possible result of this change. If the change is to COMPLETE and the
495 // current value is one of the COMPLETE_xx subtypes, ignore that as well
0d5d12bd 496 $current = $this->get_data($cm, false, $userid);
497 if ($possibleresult == $current->completionstate ||
498 ($possibleresult == COMPLETION_COMPLETE &&
499 ($current->completionstate == COMPLETION_COMPLETE_PASS ||
500 $current->completionstate == COMPLETION_COMPLETE_FAIL))) {
4e781c7b 501 return;
502 }
0d5d12bd 503
504 if ($cm->completion == COMPLETION_TRACKING_MANUAL) {
4e781c7b 505 // For manual tracking we set the result directly
506 switch($possibleresult) {
507 case COMPLETION_COMPLETE:
508 case COMPLETION_INCOMPLETE:
0d5d12bd 509 $newstate = $possibleresult;
4e781c7b 510 break;
511 default:
512 $this->internal_systemerror("Unexpected manual completion state for {$cm->id}: $possibleresult");
513 }
d7d87535 514
4e781c7b 515 } else {
516 // Automatic tracking; get new state
0d5d12bd 517 $newstate = $this->internal_get_state($cm, $userid, $current);
4e781c7b 518 }
0d5d12bd 519
4e781c7b 520 // If changed, update
0d5d12bd 521 if ($newstate != $current->completionstate) {
522 $current->completionstate = $newstate;
523 $current->timemodified = time();
524 $this->internal_set_data($cm, $current);
4e781c7b 525 }
526 }
0d5d12bd 527
4e781c7b 528 /**
529 * Calculates the completion state for an activity and user.
4e781c7b 530 *
09639ded 531 * Internal function. Not private, so we can unit-test it.
95dd54ee 532 *
836375ec 533 * @param stdClass|cm_info $cm Activity
4e781c7b 534 * @param int $userid ID of user
836375ec 535 * @param stdClass $current Previous completion information from database
09639ded 536 * @return mixed
4e781c7b 537 */
836375ec 538 public function internal_get_state($cm, $userid, $current) {
7a7dbd77 539 global $USER, $DB, $CFG;
d7d87535 540
541 // Get user ID
0d5d12bd 542 if (!$userid) {
543 $userid = $USER->id;
4e781c7b 544 }
0d5d12bd 545
4e781c7b 546 // Check viewed
0d5d12bd 547 if ($cm->completionview == COMPLETION_VIEW_REQUIRED &&
548 $current->viewed == COMPLETION_NOT_VIEWED) {
549
4e781c7b 550 return COMPLETION_INCOMPLETE;
551 }
0d5d12bd 552
4e781c7b 553 // Modname hopefully is provided in $cm but just in case it isn't, let's grab it
0d5d12bd 554 if (!isset($cm->modname)) {
555 $cm->modname = $DB->get_field('modules', 'name', array('id'=>$cm->module));
4e781c7b 556 }
0d5d12bd 557
558 $newstate = COMPLETION_COMPLETE;
559
4e781c7b 560 // Check grade
0d5d12bd 561 if (!is_null($cm->completiongradeitemnumber)) {
7a7dbd77 562 require_once($CFG->libdir.'/gradelib.php');
0d5d12bd 563 $item = grade_item::fetch(array('courseid'=>$cm->course, 'itemtype'=>'mod',
564 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance,
4e781c7b 565 'itemnumber'=>$cm->completiongradeitemnumber));
0d5d12bd 566 if ($item) {
4e781c7b 567 // Fetch 'grades' (will be one or none)
0d5d12bd 568 $grades = grade_grade::fetch_users_grades($item, array($userid), false);
569 if (empty($grades)) {
4e781c7b 570 // No grade for user
571 return COMPLETION_INCOMPLETE;
572 }
0d5d12bd 573 if (count($grades) > 1) {
4e781c7b 574 $this->internal_systemerror("Unexpected result: multiple grades for
575 item '{$item->id}', user '{$userid}'");
576 }
4218d813 577 $newstate = self::internal_get_grade_state($item, reset($grades));
0d5d12bd 578 if ($newstate == COMPLETION_INCOMPLETE) {
4e781c7b 579 return COMPLETION_INCOMPLETE;
580 }
d7d87535 581
4e781c7b 582 } else {
583 $this->internal_systemerror("Cannot find grade item for '{$cm->modname}'
584 cm '{$cm->id}' matching number '{$cm->completiongradeitemnumber}'");
585 }
586 }
0d5d12bd 587
588 if (plugin_supports('mod', $cm->modname, FEATURE_COMPLETION_HAS_RULES)) {
589 $function = $cm->modname.'_get_completion_state';
590 if (!function_exists($function)) {
4e781c7b 591 $this->internal_systemerror("Module {$cm->modname} claims to support
592 FEATURE_COMPLETION_HAS_RULES but does not have required
593 {$cm->modname}_get_completion_state function");
594 }
0d5d12bd 595 if (!$function($this->course, $cm, $userid, COMPLETION_AND)) {
4e781c7b 596 return COMPLETION_INCOMPLETE;
597 }
598 }
0d5d12bd 599
4e781c7b 600 return $newstate;
0d5d12bd 601
4e781c7b 602 }
0d5d12bd 603
4e781c7b 604 /**
605 * Marks a module as viewed.
09639ded 606 *
4e781c7b 607 * Should be called whenever a module is 'viewed' (it is up to the module how to
608 * determine that). Has no effect if viewing is not set as a completion condition.
609 *
6553cda7 610 * Note that this function must be called before you print the page header because
611 * it is possible that the navigation block may depend on it. If you call it after
612 * printing the header, it shows a developer debug warning.
836375ec
SH
613 *
614 * @param stdClass|cm_info $cm Activity
4e781c7b 615 * @param int $userid User ID or 0 (default) for current user
09639ded 616 * @return void
4e781c7b 617 */
0d5d12bd 618 public function set_module_viewed($cm, $userid=0) {
c8b3346c
PS
619 global $PAGE;
620 if ($PAGE->headerprinted) {
6553cda7 621 debugging('set_module_viewed must be called before header is printed',
622 DEBUG_DEVELOPER);
623 }
1caeb4b4 624
4e781c7b 625 // Don't do anything if view condition is not turned on
0d5d12bd 626 if ($cm->completionview == COMPLETION_VIEW_NOT_REQUIRED || !$this->is_enabled($cm)) {
4e781c7b 627 return;
628 }
1caeb4b4 629
4e781c7b 630 // Get current completion state
1caeb4b4
AB
631 $data = $this->get_data($cm, false, $userid);
632
4e781c7b 633 // If we already viewed it, don't do anything
0d5d12bd 634 if ($data->viewed == COMPLETION_VIEWED) {
4e781c7b 635 return;
636 }
1caeb4b4 637
4e781c7b 638 // OK, change state, save it, and update completion
0d5d12bd 639 $data->viewed = COMPLETION_VIEWED;
640 $this->internal_set_data($cm, $data);
641 $this->update_state($cm, COMPLETION_COMPLETE, $userid);
4e781c7b 642 }
0d5d12bd 643
4e781c7b 644 /**
645 * Determines how much completion data exists for an activity. This is used when
646 * deciding whether completion information should be 'locked' in the module
647 * editing form.
648 *
836375ec 649 * @param cm_info $cm Activity
4e781c7b 650 * @return int The number of users who have completion data stored for this
0d5d12bd 651 * activity, 0 if none
4e781c7b 652 */
653 public function count_user_data($cm) {
2be4d090 654 global $DB;
0d5d12bd 655
4e781c7b 656 return $DB->get_field_sql("
657 SELECT
658 COUNT(1)
659 FROM
49f6e5f4 660 {course_modules_completion}
4e781c7b 661 WHERE
0d5d12bd 662 coursemoduleid=? AND completionstate<>0", array($cm->id));
4e781c7b 663 }
0d5d12bd 664
2be4d090
MD
665 /**
666 * Determines how much course completion data exists for a course. This is used when
667 * deciding whether completion information should be 'locked' in the completion
668 * settings form and activity completion settings.
669 *
836375ec 670 * @param int $user_id Optionally only get course completion data for a single user
2be4d090 671 * @return int The number of users who have completion data stored for this
836375ec 672 * course, 0 if none
2be4d090
MD
673 */
674 public function count_course_user_data($user_id = null) {
675 global $DB;
676
677 $sql = '
678 SELECT
679 COUNT(1)
680 FROM
681 {course_completion_crit_compl}
682 WHERE
683 course = ?
684 ';
685
686 $params = array($this->course_id);
687
688 // Limit data to a single user if an ID is supplied
689 if ($user_id) {
690 $sql .= ' AND userid = ?';
691 $params[] = $user_id;
692 }
693
694 return $DB->get_field_sql($sql, $params);
695 }
696
697 /**
698 * Check if this course's completion criteria should be locked
699 *
836375ec 700 * @return boolean
2be4d090
MD
701 */
702 public function is_course_locked() {
703 return (bool) $this->count_course_user_data();
704 }
705
706 /**
707 * Deletes all course completion completion data.
708 *
709 * Intended to be used when unlocking completion criteria settings.
2be4d090
MD
710 */
711 public function delete_course_completion_data() {
712 global $DB;
713
714 $DB->delete_records('course_completions', array('course' => $this->course_id));
715 $DB->delete_records('course_completion_crit_compl', array('course' => $this->course_id));
716 }
717
5ae17b09 718 /**
719 * Deletes all activity and course completion data for an entire course
720 * (the below delete_all_state function does this for a single activity).
721 *
722 * Used by course reset page.
723 */
724 public function delete_all_completion_data() {
7f4de36d 725 global $DB, $SESSION;
5ae17b09 726
727 // Delete from database.
728 $DB->delete_records_select('course_modules_completion',
729 'coursemoduleid IN (SELECT id FROM {course_modules} WHERE course=?)',
730 array($this->course_id));
731
732 // Reset cache for current user.
733 if (isset($SESSION->completioncache) &&
734 array_key_exists($this->course_id, $SESSION->completioncache)) {
735
736 unset($SESSION->completioncache[$this->course_id]);
737 }
738
739 // Wipe course completion data too.
740 $this->delete_course_completion_data();
741 }
742
4e781c7b 743 /**
0d5d12bd 744 * Deletes completion state related to an activity for all users.
117bd748 745 *
4e781c7b 746 * Intended for use only when the activity itself is deleted.
747 *
836375ec 748 * @param stdClass|cm_info $cm Activity
4e781c7b 749 */
0d5d12bd 750 public function delete_all_state($cm) {
751 global $SESSION, $DB;
752
4e781c7b 753 // Delete from database
0d5d12bd 754 $DB->delete_records('course_modules_completion', array('coursemoduleid'=>$cm->id));
755
4e781c7b 756 // Erase cache data for current user if applicable
0d5d12bd 757 if (isset($SESSION->completioncache) &&
758 array_key_exists($cm->course, $SESSION->completioncache) &&
759 array_key_exists($cm->id, $SESSION->completioncache[$cm->course])) {
760
4e781c7b 761 unset($SESSION->completioncache[$cm->course][$cm->id]);
762 }
2be4d090
MD
763
764 // Check if there is an associated course completion criteria
765 $criteria = $this->get_criteria(COMPLETION_CRITERIA_TYPE_ACTIVITY);
766 $acriteria = false;
767 foreach ($criteria as $criterion) {
768 if ($criterion->moduleinstance == $cm->id) {
769 $acriteria = $criterion;
770 break;
836375ec 771 }
2be4d090
MD
772 }
773
774 if ($acriteria) {
775 // Delete all criteria completions relating to this activity
776 $DB->delete_records('course_completion_crit_compl', array('course' => $this->course_id, 'criteriaid' => $acriteria->id));
777 $DB->delete_records('course_completions', array('course' => $this->course_id));
778 }
4e781c7b 779 }
0d5d12bd 780
4e781c7b 781 /**
782 * Recalculates completion state related to an activity for all users.
117bd748 783 *
4e781c7b 784 * Intended for use if completion conditions change. (This should be avoided
785 * as it may cause some things to become incomplete when they were previously
786 * complete, with the effect - for example - of hiding a later activity that
787 * was previously available.)
117bd748 788 *
0d5d12bd 789 * Resetting state of manual tickbox has same result as deleting state for
81f64ed3 790 * it.
09639ded 791 *
836375ec 792 * @param stcClass|cm_info $cm Activity
4e781c7b 793 */
794 public function reset_all_state($cm) {
d7d87535 795 global $DB;
796
0d5d12bd 797 if ($cm->completion == COMPLETION_TRACKING_MANUAL) {
81f64ed3 798 $this->delete_all_state($cm);
799 return;
800 }
4e781c7b 801 // Get current list of users with completion state
0d5d12bd 802 $rs = $DB->get_recordset('course_modules_completion', array('coursemoduleid'=>$cm->id), '', 'userid');
803 $keepusers = array();
804 foreach ($rs as $rec) {
805 $keepusers[] = $rec->userid;
4e781c7b 806 }
807 $rs->close();
0d5d12bd 808
4e781c7b 809 // Delete all existing state [also clears session cache for current user]
810 $this->delete_all_state($cm);
0d5d12bd 811
812 // Merge this with list of planned users (according to roles)
24a3b341 813 $trackedusers = $this->get_tracked_users();
0d5d12bd 814 foreach ($trackedusers as $trackeduser) {
815 $keepusers[] = $trackeduser->id;
816 }
817 $keepusers = array_unique($keepusers);
818
4e781c7b 819 // Recalculate state for each kept user
0d5d12bd 820 foreach ($keepusers as $keepuser) {
821 $this->update_state($cm, COMPLETION_UNKNOWN, $keepuser);
4e781c7b 822 }
823 }
0d5d12bd 824
4e781c7b 825 /**
826 * Obtains completion data for a particular activity and user (from the
827 * session cache if available, or by SQL query)
828 *
836375ec 829 * @param stcClass|cm_info $cm Activity; only required field is ->id
4e781c7b 830 * @param bool $wholecourse If true (default false) then, when necessary to
831 * fill the cache, retrieves information from the entire course not just for
832 * this one activity
833 * @param int $userid User ID or 0 (default) for current user
117bd748
PS
834 * @param array $modinfo Supply the value here - this is used for unit
835 * testing and so that it can be called recursively from within
82bd6a5e 836 * get_fast_modinfo. (Needs only list of all CMs with IDs.)
837 * Otherwise the method calls get_fast_modinfo itself.
4e781c7b 838 * @return object Completion data (record from course_modules_completion)
4e781c7b 839 */
836375ec 840 public function get_data($cm, $wholecourse = false, $userid = 0, $modinfo = null) {
0d5d12bd 841 global $USER, $CFG, $SESSION, $DB;
d7d87535 842
843 // Get user ID
0d5d12bd 844 if (!$userid) {
845 $userid = $USER->id;
4e781c7b 846 }
0d5d12bd 847
4e781c7b 848 // Is this the current user?
0d5d12bd 849 $currentuser = $userid==$USER->id;
850
2be4d090 851 if ($currentuser && is_object($SESSION)) {
0d5d12bd 852 // Make sure cache is present and is for current user (loginas
49f6e5f4 853 // changes this)
0d5d12bd 854 if (!isset($SESSION->completioncache) || $SESSION->completioncacheuserid!=$USER->id) {
855 $SESSION->completioncache = array();
856 $SESSION->completioncacheuserid = $USER->id;
4e781c7b 857 }
858 // Expire any old data from cache
0d5d12bd 859 foreach ($SESSION->completioncache as $courseid=>$activities) {
860 if (empty($activities['updated']) || $activities['updated'] < time()-COMPLETION_CACHE_EXPIRY) {
4e781c7b 861 unset($SESSION->completioncache[$courseid]);
862 }
863 }
864 // See if requested data is present, if so use cache to get it
0d5d12bd 865 if (isset($SESSION->completioncache) &&
866 array_key_exists($this->course->id, $SESSION->completioncache) &&
867 array_key_exists($cm->id, $SESSION->completioncache[$this->course->id])) {
868 return $SESSION->completioncache[$this->course->id][$cm->id];
4e781c7b 869 }
870 }
0d5d12bd 871
4e781c7b 872 // Not there, get via SQL
0d5d12bd 873 if ($currentuser && $wholecourse) {
4e781c7b 874 // Get whole course data for cache
0d5d12bd 875 $alldatabycmc = $DB->get_records_sql("
4e781c7b 876 SELECT
877 cmc.*
878 FROM
49f6e5f4 879 {course_modules} cm
880 INNER JOIN {course_modules_completion} cmc ON cmc.coursemoduleid=cm.id
0d5d12bd 881 WHERE
882 cm.course=? AND cmc.userid=?", array($this->course->id, $userid));
883
4e781c7b 884 // Reindex by cm id
0d5d12bd 885 $alldata = array();
886 if ($alldatabycmc) {
887 foreach ($alldatabycmc as $data) {
888 $alldata[$data->coursemoduleid] = $data;
4e781c7b 889 }
890 }
0d5d12bd 891
4e781c7b 892 // Get the module info and build up condition info for each one
0d5d12bd 893 if (empty($modinfo)) {
894 $modinfo = get_fast_modinfo($this->course, $userid);
4e781c7b 895 }
0d5d12bd 896 foreach ($modinfo->cms as $othercm) {
897 if (array_key_exists($othercm->id, $alldata)) {
898 $data = $alldata[$othercm->id];
4e781c7b 899 } else {
900 // Row not present counts as 'not complete'
0d5d12bd 901 $data = new StdClass;
902 $data->id = 0;
903 $data->coursemoduleid = $othercm->id;
904 $data->userid = $userid;
905 $data->completionstate = 0;
906 $data->viewed = 0;
907 $data->timemodified = 0;
4e781c7b 908 }
0d5d12bd 909 $SESSION->completioncache[$this->course->id][$othercm->id] = $data;
4e781c7b 910 }
0d5d12bd 911 $SESSION->completioncache[$this->course->id]['updated'] = time();
912
913 if (!isset($SESSION->completioncache[$this->course->id][$cm->id])) {
4e781c7b 914 $this->internal_systemerror("Unexpected error: course-module {$cm->id} could not be found on course {$this->course->id}");
915 }
916 return $SESSION->completioncache[$this->course->id][$cm->id];
d7d87535 917
4e781c7b 918 } else {
919 // Get single record
0d5d12bd 920 $data = $DB->get_record('course_modules_completion', array('coursemoduleid'=>$cm->id, 'userid'=>$userid));
921 if ($data == false) {
4e781c7b 922 // Row not present counts as 'not complete'
0d5d12bd 923 $data = new StdClass;
924 $data->id = 0;
925 $data->coursemoduleid = $cm->id;
926 $data->userid = $userid;
927 $data->completionstate = 0;
928 $data->viewed = 0;
929 $data->timemodified = 0;
4e781c7b 930 }
0d5d12bd 931
4e781c7b 932 // Put in cache
0d5d12bd 933 if ($currentuser) {
934 $SESSION->completioncache[$this->course->id][$cm->id] = $data;
4e781c7b 935 // For single updates, only set date if it was empty before
0d5d12bd 936 if (empty($SESSION->completioncache[$this->course->id]['updated'])) {
937 $SESSION->completioncache[$this->course->id]['updated'] = time();
4e781c7b 938 }
939 }
940 }
0d5d12bd 941
4e781c7b 942 return $data;
943 }
0d5d12bd 944
4e781c7b 945 /**
0d5d12bd 946 * Updates completion data for a particular coursemodule and user (user is
4e781c7b 947 * determined from $data).
117bd748 948 *
4e781c7b 949 * (Internal function. Not private, so we can unit-test it.)
0d5d12bd 950 *
836375ec
SH
951 * @param stdClass|cm_info $cm Activity
952 * @param stdClass $data Data about completion for that user
4e781c7b 953 */
836375ec 954 public function internal_set_data($cm, $data) {
0d5d12bd 955 global $USER, $SESSION, $DB;
d7d87535 956
a854bca3 957 $transaction = $DB->start_delegated_transaction();
958 if (!$data->id) {
959 // Check there isn't really a row
960 $data->id = $DB->get_field('course_modules_completion', 'id',
961 array('coursemoduleid'=>$data->coursemoduleid, 'userid'=>$data->userid));
962 }
963 if (!$data->id) {
4e781c7b 964 // Didn't exist before, needs creating
0d5d12bd 965 $data->id = $DB->insert_record('course_modules_completion', $data);
a854bca3 966 } else {
967 // Has real (nonzero) id meaning that a database row exists, update
968 $DB->update_record('course_modules_completion', $data);
4e781c7b 969 }
a854bca3 970 $transaction->allow_commit();
d7d87535 971
0d5d12bd 972 if ($data->userid == $USER->id) {
973 $SESSION->completioncache[$cm->course][$cm->id] = $data;
b46be6ad
MG
974 // reset modinfo for user (no need to call rebuild_course_cache())
975 get_fast_modinfo($cm->course, 0, true);
4e781c7b 976 }
977 }
0d5d12bd 978
4e781c7b 979 /**
0d5d12bd 980 * Obtains a list of activities for which completion is enabled on the
4e781c7b 981 * course. The list is ordered by the section order of those activities.
09639ded 982 *
0d5d12bd 983 * @param array $modinfo For unit testing only, supply the value
4e781c7b 984 * here. Otherwise the method calls get_fast_modinfo
985 * @return array Array from $cmid => $cm of all activities with completion enabled,
986 * empty array if none
987 */
988 public function get_activities($modinfo=null) {
989 global $DB;
0d5d12bd 990
4e781c7b 991 // Obtain those activities which have completion turned on
0d5d12bd 992 $withcompletion = $DB->get_records_select('course_modules', 'course='.$this->course->id.
4e781c7b 993 ' AND completion<>'.COMPLETION_TRACKING_NONE);
2be4d090 994 if (!$withcompletion) {
4e781c7b 995 return array();
996 }
0d5d12bd 997
4e781c7b 998 // Use modinfo to get section order and also add in names
0d5d12bd 999 if (empty($modinfo)) {
1000 $modinfo = get_fast_modinfo($this->course);
1001 }
1002 $result = array();
1003 foreach ($modinfo->sections as $sectioncms) {
1004 foreach ($sectioncms as $cmid) {
1005 if (array_key_exists($cmid, $withcompletion)) {
1006 $result[$cmid] = $withcompletion[$cmid];
1007 $result[$cmid]->modname = $modinfo->cms[$cmid]->modname;
1008 $result[$cmid]->name = $modinfo->cms[$cmid]->name;
4e781c7b 1009 }
1010 }
1011 }
0d5d12bd 1012
4e781c7b 1013 return $result;
1014 }
0d5d12bd 1015
4e781c7b 1016 /**
24a3b341
AB
1017 * Checks to see if the userid supplied has a tracked role in
1018 * this course
09639ded 1019 *
836375ec
SH
1020 * @param int $userid User id
1021 * @return bool
4e781c7b 1022 */
836375ec 1023 public function is_tracked_user($userid) {
10a8581f 1024 return is_enrolled(context_course::instance($this->course->id), $userid, 'moodle/course:isincompletionreports', true);
24a3b341
AB
1025 }
1026
24a3b341 1027 /**
38d06fea 1028 * Returns the number of users whose progress is tracked in this course.
24a3b341 1029 *
38d06fea 1030 * Optionally supply a search's where clause, or a group id.
24a3b341 1031 *
38d06fea 1032 * @param string $where Where clause sql (use 'u.whatever' for user table fields)
1033 * @param array $whereparams Where clause params
836375ec 1034 * @param int $groupid Group id
38d06fea 1035 * @return int Number of tracked users
24a3b341 1036 */
38d06fea 1037 public function get_num_tracked_users($where = '', $whereparams = array(), $groupid = 0) {
24a3b341
AB
1038 global $DB;
1039
38d06fea 1040 list($enrolledsql, $enrolledparams) = get_enrolled_sql(
10a8581f 1041 context_course::instance($this->course->id), 'moodle/course:isincompletionreports', $groupid, true);
38d06fea 1042 $sql = 'SELECT COUNT(eu.id) FROM (' . $enrolledsql . ') eu JOIN {user} u ON u.id = eu.id';
24a3b341 1043 if ($where) {
38d06fea 1044 $sql .= " WHERE $where";
24a3b341
AB
1045 }
1046
38d06fea 1047 $params = array_merge($enrolledparams, $whereparams);
5642a8e5 1048 return $DB->count_records_sql($sql, $params);
24a3b341
AB
1049 }
1050
24a3b341 1051 /**
38d06fea 1052 * Return array of users whose progress is tracked in this course.
24a3b341 1053 *
38d06fea 1054 * Optionally supply a search's where clause, group id, sorting, paging.
24a3b341 1055 *
38d06fea 1056 * @param string $where Where clause sql, referring to 'u.' fields (optional)
1057 * @param array $whereparams Where clause params (optional)
1058 * @param int $groupid Group ID to restrict to (optional)
836375ec 1059 * @param string $sort Order by clause (optional)
38d06fea 1060 * @param int $limitfrom Result start (optional)
1061 * @param int $limitnum Result max size (optional)
24e14bc7 1062 * @param context $extracontext If set, includes extra user information fields
1063 * as appropriate to display for current user in this context
38d06fea 1064 * @return array Array of user objects with standard user fields
24a3b341 1065 */
38d06fea 1066 public function get_tracked_users($where = '', $whereparams = array(), $groupid = 0,
24e14bc7 1067 $sort = '', $limitfrom = '', $limitnum = '', context $extracontext = null) {
24a3b341
AB
1068
1069 global $DB;
1070
38d06fea 1071 list($enrolledsql, $params) = get_enrolled_sql(
b61924d4 1072 context_course::instance($this->course->id),
1073 'moodle/course:isincompletionreports', $groupid, true);
5642a8e5 1074
38d06fea 1075 $sql = 'SELECT u.id, u.firstname, u.lastname, u.idnumber';
24e14bc7 1076 if ($extracontext) {
1077 $sql .= get_extra_user_fields_sql($extracontext, 'u', '', array('idnumber'));
1078 }
38d06fea 1079 $sql .= ' FROM (' . $enrolledsql . ') eu JOIN {user} u ON u.id = eu.id';
24a3b341
AB
1080
1081 if ($where) {
1082 $sql .= " AND $where";
38d06fea 1083 $params = array_merge($params, $whereparams);
24a3b341
AB
1084 }
1085
1086 if ($sort) {
1087 $sql .= " ORDER BY $sort";
1088 }
1089
38d06fea 1090 return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
4e781c7b 1091 }
0d5d12bd 1092
4e781c7b 1093 /**
1094 * Obtains progress information across a course for all users on that course, or
1095 * for all users in a specific group. Intended for use when displaying progress.
117bd748 1096 *
4e781c7b 1097 * This includes only users who, in course context, have one of the roles for
1c6ed505 1098 * which progress is tracked (the gradebookroles admin option) and are enrolled in course.
117bd748 1099 *
4e781c7b 1100 * Users are included (in the first array) even if they do not have
1101 * completion progress for any course-module.
1102 *
1103 * @param bool $sortfirstname If true, sort by first name, otherwise sort by
1104 * last name
5642a8e5
AB
1105 * @param string $where Where clause sql (optional)
1106 * @param array $where_params Where clause params (optional)
4e781c7b 1107 * @param int $groupid Group ID or 0 (default)/false for all groups
24a3b341
AB
1108 * @param int $pagesize Number of users to actually return (optional)
1109 * @param int $start User to start at if paging (optional)
24e14bc7 1110 * @param context $extracontext If set, includes extra user information fields
1111 * as appropriate to display for current user in this context
836375ec 1112 * @return stdClass with ->total and ->start (same as $start) and ->users;
35da0e87 1113 * an array of user objects (like mdl_user id, firstname, lastname)
4e781c7b 1114 * containing an additional ->progress array of coursemoduleid => completionstate
1115 */
5642a8e5 1116 public function get_progress_all($where = '', $where_params = array(), $groupid = 0,
24e14bc7 1117 $sort = '', $pagesize = '', $start = '', context $extracontext = null) {
0d5d12bd 1118 global $CFG, $DB;
1119
4e781c7b 1120 // Get list of applicable users
24e14bc7 1121 $users = $this->get_tracked_users($where, $where_params, $groupid, $sort,
1122 $start, $pagesize, $extracontext);
0d5d12bd 1123
1124 // Get progress information for these users in groups of 1, 000 (if needed)
4e781c7b 1125 // to avoid making the SQL IN too long
24a3b341 1126 $results = array();
0d5d12bd 1127 $userids = array();
1128 foreach ($users as $user) {
1129 $userids[] = $user->id;
24a3b341
AB
1130 $results[$user->id] = $user;
1131 $results[$user->id]->progress = array();
0d5d12bd 1132 }
1133
1134 for($i=0; $i<count($userids); $i+=1000) {
1135 $blocksize = count($userids)-$i < 1000 ? count($userids)-$i : 1000;
1136
1137 list($insql, $params) = $DB->get_in_or_equal(array_slice($userids, $i, $blocksize));
1138 array_splice($params, 0, 0, array($this->course->id));
1139 $rs = $DB->get_recordset_sql("
24a3b341
AB
1140 SELECT
1141 cmc.*
1142 FROM
1143 {course_modules} cm
1144 INNER JOIN {course_modules_completion} cmc ON cm.id=cmc.coursemoduleid
1145 WHERE
836375ec 1146 cm.course=? AND cmc.userid $insql", $params);
0d5d12bd 1147 foreach ($rs as $progress) {
24a3b341
AB
1148 $progress = (object)$progress;
1149 $results[$progress->userid]->progress[$progress->coursemoduleid] = $progress;
4e781c7b 1150 }
1151 $rs->close();
1152 }
0d5d12bd 1153
24a3b341 1154 return $results;
4e781c7b 1155 }
0d5d12bd 1156
09639ded 1157 /**
c4893595
SM
1158 * Called by grade code to inform the completion system when a grade has
1159 * been changed. If the changed grade is used to determine completion for
1160 * the course-module, then the completion status will be updated.
09639ded 1161 *
836375ec 1162 * @param stdClass|cm_info $cm Course-module for item that owns grade
c4893595 1163 * @param grade_item $item Grade item
836375ec 1164 * @param stdClass $grade
09639ded 1165 * @param bool $deleted
09639ded 1166 */
91537a88 1167 public function inform_grade_changed($cm, $item, $grade, $deleted) {
ca6b2d68 1168 // Bail out now if completion is not enabled for course-module, it is enabled
1169 // but is set to manual, grade is not used to compute completion, or this
1170 // is a different numbered grade
0d5d12bd 1171 if (!$this->is_enabled($cm) ||
ca6b2d68 1172 $cm->completion == COMPLETION_TRACKING_MANUAL ||
4e781c7b 1173 is_null($cm->completiongradeitemnumber) ||
0d5d12bd 1174 $item->itemnumber != $cm->completiongradeitemnumber) {
4e781c7b 1175 return;
1176 }
0d5d12bd 1177
4e781c7b 1178 // What is the expected result based on this grade?
0d5d12bd 1179 if ($deleted) {
4e781c7b 1180 // Grade being deleted, so only change could be to make it incomplete
0d5d12bd 1181 $possibleresult = COMPLETION_INCOMPLETE;
4e781c7b 1182 } else {
caee6e6c 1183 $possibleresult = self::internal_get_grade_state($item, $grade);
4e781c7b 1184 }
caee6e6c 1185
4e781c7b 1186 // OK, let's update state based on this
0d5d12bd 1187 $this->update_state($cm, $possibleresult, $grade->userid);
4e781c7b 1188 }
0d5d12bd 1189
4e781c7b 1190 /**
1191 * Calculates the completion state that would result from a graded item
1192 * (where grade-based completion is turned on) based on the actual grade
1193 * and settings.
117bd748 1194 *
09639ded 1195 * Internal function. Not private, so we can unit-test it.
4e781c7b 1196 *
95dd54ee
AA
1197 * @param grade_item $item an instance of grade_item
1198 * @param grade_grade $grade an instance of grade_grade
4e781c7b 1199 * @return int Completion state e.g. COMPLETION_INCOMPLETE
1200 */
caee6e6c 1201 public static function internal_get_grade_state($item, $grade) {
0d5d12bd 1202 if (!$grade) {
4e781c7b 1203 return COMPLETION_INCOMPLETE;
1204 }
1205 // Conditions to show pass/fail:
1206 // a) Grade has pass mark (default is 0.00000 which is boolean true so be careful)
1207 // b) Grade is visible (neither hidden nor hidden-until)
0d5d12bd 1208 if ($item->gradepass && $item->gradepass > 0.000009 && !$item->hidden) {
4e781c7b 1209 // Use final grade if set otherwise raw grade
0d5d12bd 1210 $score = !is_null($grade->finalgrade) ? $grade->finalgrade : $grade->rawgrade;
1211
4e781c7b 1212 // We are displaying and tracking pass/fail
0d5d12bd 1213 if ($score >= $item->gradepass) {
4e781c7b 1214 return COMPLETION_COMPLETE_PASS;
1215 } else {
1216 return COMPLETION_COMPLETE_FAIL;
1217 }
1218 } else {
fd546aaa
SM
1219 // Not displaying pass/fail, so just if there is a grade
1220 if (!is_null($grade->finalgrade) || !is_null($grade->rawgrade)) {
1221 // Grade exists, so maybe complete now
1222 return COMPLETION_COMPLETE;
1223 } else {
1224 // Grade does not exist, so maybe incomplete now
1225 return COMPLETION_INCOMPLETE;
1226 }
4e781c7b 1227 }
1228 }
0d5d12bd 1229
94db2749
AB
1230 /**
1231 * Aggregate activity completion state
1232 *
1233 * @param int $type Aggregation type (COMPLETION_* constant)
1234 * @param bool $old Old state
1235 * @param bool $new New state
1236 * @return bool
1237 */
1238 public static function aggregate_completion_states($type, $old, $new) {
1239 if ($type == COMPLETION_AND) {
1240 return $old && $new;
1241 } else {
1242 return $old || $new;
1243 }
1244 }
1245
4e781c7b 1246 /**
4e781c7b 1247 * This is to be used only for system errors (things that shouldn't happen)
1248 * and not user-level errors.
1249 *
836375ec
SH
1250 * @global type $CFG
1251 * @param string $error Error string (will not be displayed to user unless debugging is enabled)
1252 * @throws moodle_exception Exception with the error string as debug info
4e781c7b 1253 */
836375ec 1254 public function internal_systemerror($error) {
4e781c7b 1255 global $CFG;
82bd6a5e 1256 throw new moodle_exception('err_system','completion',
1257 $CFG->wwwroot.'/course/view.php?id='.$this->course->id,null,$error);
1258 }
d7d87535 1259
117bd748
PS
1260 /**
1261 * For testing only. Wipes information cached in user session.
09639ded 1262 */
836375ec 1263 public static function wipe_session_cache() {
82bd6a5e 1264 global $SESSION;
1265 unset($SESSION->completioncache);
1266 unset($SESSION->completioncacheuserid);
4e781c7b 1267 }
7142a755 1268}