MDL-61407 mod_quiz: Add initial privacy implementation
[moodle.git] / mod / quiz / lib.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  * Library of functions for the quiz module.
19  *
20  * This contains functions that are called also from outside the quiz module
21  * Functions that are only called by the quiz module itself are in {@link locallib.php}
22  *
23  * @package    mod_quiz
24  * @copyright  1999 onwards Martin Dougiamas {@link http://moodle.com}
25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
29 defined('MOODLE_INTERNAL') || die();
31 require_once($CFG->libdir . '/eventslib.php');
32 require_once($CFG->dirroot . '/calendar/lib.php');
35 /**#@+
36  * Option controlling what options are offered on the quiz settings form.
37  */
38 define('QUIZ_MAX_ATTEMPT_OPTION', 10);
39 define('QUIZ_MAX_QPP_OPTION', 50);
40 define('QUIZ_MAX_DECIMAL_OPTION', 5);
41 define('QUIZ_MAX_Q_DECIMAL_OPTION', 7);
42 /**#@-*/
44 /**#@+
45  * Options determining how the grades from individual attempts are combined to give
46  * the overall grade for a user
47  */
48 define('QUIZ_GRADEHIGHEST', '1');
49 define('QUIZ_GRADEAVERAGE', '2');
50 define('QUIZ_ATTEMPTFIRST', '3');
51 define('QUIZ_ATTEMPTLAST',  '4');
52 /**#@-*/
54 /**
55  * @var int If start and end date for the quiz are more than this many seconds apart
56  * they will be represented by two separate events in the calendar
57  */
58 define('QUIZ_MAX_EVENT_LENGTH', 5*24*60*60); // 5 days.
60 /**#@+
61  * Options for navigation method within quizzes.
62  */
63 define('QUIZ_NAVMETHOD_FREE', 'free');
64 define('QUIZ_NAVMETHOD_SEQ',  'sequential');
65 /**#@-*/
67 /**
68  * Event types.
69  */
70 define('QUIZ_EVENT_TYPE_OPEN', 'open');
71 define('QUIZ_EVENT_TYPE_CLOSE', 'close');
73 /**
74  * Given an object containing all the necessary data,
75  * (defined by the form in mod_form.php) this function
76  * will create a new instance and return the id number
77  * of the new instance.
78  *
79  * @param object $quiz the data that came from the form.
80  * @return mixed the id of the new instance on success,
81  *          false or a string error message on failure.
82  */
83 function quiz_add_instance($quiz) {
84     global $DB;
85     $cmid = $quiz->coursemodule;
87     // Process the options from the form.
88     $quiz->created = time();
89     $result = quiz_process_options($quiz);
90     if ($result && is_string($result)) {
91         return $result;
92     }
94     // Try to store it in the database.
95     $quiz->id = $DB->insert_record('quiz', $quiz);
97     // Create the first section for this quiz.
98     $DB->insert_record('quiz_sections', array('quizid' => $quiz->id,
99             'firstslot' => 1, 'heading' => '', 'shufflequestions' => 0));
101     // Do the processing required after an add or an update.
102     quiz_after_add_or_update($quiz);
104     return $quiz->id;
107 /**
108  * Given an object containing all the necessary data,
109  * (defined by the form in mod_form.php) this function
110  * will update an existing instance with new data.
111  *
112  * @param object $quiz the data that came from the form.
113  * @return mixed true on success, false or a string error message on failure.
114  */
115 function quiz_update_instance($quiz, $mform) {
116     global $CFG, $DB;
117     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
119     // Process the options from the form.
120     $result = quiz_process_options($quiz);
121     if ($result && is_string($result)) {
122         return $result;
123     }
125     // Get the current value, so we can see what changed.
126     $oldquiz = $DB->get_record('quiz', array('id' => $quiz->instance));
128     // We need two values from the existing DB record that are not in the form,
129     // in some of the function calls below.
130     $quiz->sumgrades = $oldquiz->sumgrades;
131     $quiz->grade     = $oldquiz->grade;
133     // Update the database.
134     $quiz->id = $quiz->instance;
135     $DB->update_record('quiz', $quiz);
137     // Do the processing required after an add or an update.
138     quiz_after_add_or_update($quiz);
140     if ($oldquiz->grademethod != $quiz->grademethod) {
141         quiz_update_all_final_grades($quiz);
142         quiz_update_grades($quiz);
143     }
145     $quizdateschanged = $oldquiz->timelimit   != $quiz->timelimit
146                      || $oldquiz->timeclose   != $quiz->timeclose
147                      || $oldquiz->graceperiod != $quiz->graceperiod;
148     if ($quizdateschanged) {
149         quiz_update_open_attempts(array('quizid' => $quiz->id));
150     }
152     // Delete any previous preview attempts.
153     quiz_delete_previews($quiz);
155     // Repaginate, if asked to.
156     if (!empty($quiz->repaginatenow)) {
157         quiz_repaginate_questions($quiz->id, $quiz->questionsperpage);
158     }
160     return true;
163 /**
164  * Given an ID of an instance of this module,
165  * this function will permanently delete the instance
166  * and any data that depends on it.
167  *
168  * @param int $id the id of the quiz to delete.
169  * @return bool success or failure.
170  */
171 function quiz_delete_instance($id) {
172     global $DB;
174     $quiz = $DB->get_record('quiz', array('id' => $id), '*', MUST_EXIST);
176     quiz_delete_all_attempts($quiz);
177     quiz_delete_all_overrides($quiz);
179     // Look for random questions that may no longer be used when this quiz is gone.
180     $sql = "SELECT q.id
181               FROM {quiz_slots} slot
182               JOIN {question} q ON q.id = slot.questionid
183              WHERE slot.quizid = ? AND q.qtype = ?";
184     $questionids = $DB->get_fieldset_sql($sql, array($quiz->id, 'random'));
186     // We need to do the following deletes before we try and delete randoms, otherwise they would still be 'in use'.
187     $quizslots = $DB->get_fieldset_select('quiz_slots', 'id', 'quizid = ?', array($quiz->id));
188     $DB->delete_records_list('quiz_slot_tags', 'slotid', $quizslots);
189     $DB->delete_records('quiz_slots', array('quizid' => $quiz->id));
190     $DB->delete_records('quiz_sections', array('quizid' => $quiz->id));
192     foreach ($questionids as $questionid) {
193         question_delete_question($questionid);
194     }
196     $DB->delete_records('quiz_feedback', array('quizid' => $quiz->id));
198     quiz_access_manager::delete_settings($quiz);
200     $events = $DB->get_records('event', array('modulename' => 'quiz', 'instance' => $quiz->id));
201     foreach ($events as $event) {
202         $event = calendar_event::load($event);
203         $event->delete();
204     }
206     quiz_grade_item_delete($quiz);
207     $DB->delete_records('quiz', array('id' => $quiz->id));
209     return true;
212 /**
213  * Deletes a quiz override from the database and clears any corresponding calendar events
214  *
215  * @param object $quiz The quiz object.
216  * @param int $overrideid The id of the override being deleted
217  * @param bool $log Whether to trigger logs.
218  * @return bool true on success
219  */
220 function quiz_delete_override($quiz, $overrideid, $log = true) {
221     global $DB;
223     if (!isset($quiz->cmid)) {
224         $cm = get_coursemodule_from_instance('quiz', $quiz->id, $quiz->course);
225         $quiz->cmid = $cm->id;
226     }
228     $override = $DB->get_record('quiz_overrides', array('id' => $overrideid), '*', MUST_EXIST);
230     // Delete the events.
231     if (isset($override->groupid)) {
232         // Create the search array for a group override.
233         $eventsearcharray = array('modulename' => 'quiz',
234             'instance' => $quiz->id, 'groupid' => (int)$override->groupid);
235     } else {
236         // Create the search array for a user override.
237         $eventsearcharray = array('modulename' => 'quiz',
238             'instance' => $quiz->id, 'userid' => (int)$override->userid);
239     }
240     $events = $DB->get_records('event', $eventsearcharray);
241     foreach ($events as $event) {
242         $eventold = calendar_event::load($event);
243         $eventold->delete();
244     }
246     $DB->delete_records('quiz_overrides', array('id' => $overrideid));
248     if ($log) {
249         // Set the common parameters for one of the events we will be triggering.
250         $params = array(
251             'objectid' => $override->id,
252             'context' => context_module::instance($quiz->cmid),
253             'other' => array(
254                 'quizid' => $override->quiz
255             )
256         );
257         // Determine which override deleted event to fire.
258         if (!empty($override->userid)) {
259             $params['relateduserid'] = $override->userid;
260             $event = \mod_quiz\event\user_override_deleted::create($params);
261         } else {
262             $params['other']['groupid'] = $override->groupid;
263             $event = \mod_quiz\event\group_override_deleted::create($params);
264         }
266         // Trigger the override deleted event.
267         $event->add_record_snapshot('quiz_overrides', $override);
268         $event->trigger();
269     }
271     return true;
274 /**
275  * Deletes all quiz overrides from the database and clears any corresponding calendar events
276  *
277  * @param object $quiz The quiz object.
278  * @param bool $log Whether to trigger logs.
279  */
280 function quiz_delete_all_overrides($quiz, $log = true) {
281     global $DB;
283     $overrides = $DB->get_records('quiz_overrides', array('quiz' => $quiz->id), 'id');
284     foreach ($overrides as $override) {
285         quiz_delete_override($quiz, $override->id, $log);
286     }
289 /**
290  * Updates a quiz object with override information for a user.
291  *
292  * Algorithm:  For each quiz setting, if there is a matching user-specific override,
293  *   then use that otherwise, if there are group-specific overrides, return the most
294  *   lenient combination of them.  If neither applies, leave the quiz setting unchanged.
295  *
296  *   Special case: if there is more than one password that applies to the user, then
297  *   quiz->extrapasswords will contain an array of strings giving the remaining
298  *   passwords.
299  *
300  * @param object $quiz The quiz object.
301  * @param int $userid The userid.
302  * @return object $quiz The updated quiz object.
303  */
304 function quiz_update_effective_access($quiz, $userid) {
305     global $DB;
307     // Check for user override.
308     $override = $DB->get_record('quiz_overrides', array('quiz' => $quiz->id, 'userid' => $userid));
310     if (!$override) {
311         $override = new stdClass();
312         $override->timeopen = null;
313         $override->timeclose = null;
314         $override->timelimit = null;
315         $override->attempts = null;
316         $override->password = null;
317     }
319     // Check for group overrides.
320     $groupings = groups_get_user_groups($quiz->course, $userid);
322     if (!empty($groupings[0])) {
323         // Select all overrides that apply to the User's groups.
324         list($extra, $params) = $DB->get_in_or_equal(array_values($groupings[0]));
325         $sql = "SELECT * FROM {quiz_overrides}
326                 WHERE groupid $extra AND quiz = ?";
327         $params[] = $quiz->id;
328         $records = $DB->get_records_sql($sql, $params);
330         // Combine the overrides.
331         $opens = array();
332         $closes = array();
333         $limits = array();
334         $attempts = array();
335         $passwords = array();
337         foreach ($records as $gpoverride) {
338             if (isset($gpoverride->timeopen)) {
339                 $opens[] = $gpoverride->timeopen;
340             }
341             if (isset($gpoverride->timeclose)) {
342                 $closes[] = $gpoverride->timeclose;
343             }
344             if (isset($gpoverride->timelimit)) {
345                 $limits[] = $gpoverride->timelimit;
346             }
347             if (isset($gpoverride->attempts)) {
348                 $attempts[] = $gpoverride->attempts;
349             }
350             if (isset($gpoverride->password)) {
351                 $passwords[] = $gpoverride->password;
352             }
353         }
354         // If there is a user override for a setting, ignore the group override.
355         if (is_null($override->timeopen) && count($opens)) {
356             $override->timeopen = min($opens);
357         }
358         if (is_null($override->timeclose) && count($closes)) {
359             if (in_array(0, $closes)) {
360                 $override->timeclose = 0;
361             } else {
362                 $override->timeclose = max($closes);
363             }
364         }
365         if (is_null($override->timelimit) && count($limits)) {
366             if (in_array(0, $limits)) {
367                 $override->timelimit = 0;
368             } else {
369                 $override->timelimit = max($limits);
370             }
371         }
372         if (is_null($override->attempts) && count($attempts)) {
373             if (in_array(0, $attempts)) {
374                 $override->attempts = 0;
375             } else {
376                 $override->attempts = max($attempts);
377             }
378         }
379         if (is_null($override->password) && count($passwords)) {
380             $override->password = array_shift($passwords);
381             if (count($passwords)) {
382                 $override->extrapasswords = $passwords;
383             }
384         }
386     }
388     // Merge with quiz defaults.
389     $keys = array('timeopen', 'timeclose', 'timelimit', 'attempts', 'password', 'extrapasswords');
390     foreach ($keys as $key) {
391         if (isset($override->{$key})) {
392             $quiz->{$key} = $override->{$key};
393         }
394     }
396     return $quiz;
399 /**
400  * Delete all the attempts belonging to a quiz.
401  *
402  * @param object $quiz The quiz object.
403  */
404 function quiz_delete_all_attempts($quiz) {
405     global $CFG, $DB;
406     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
407     question_engine::delete_questions_usage_by_activities(new qubaids_for_quiz($quiz->id));
408     $DB->delete_records('quiz_attempts', array('quiz' => $quiz->id));
409     $DB->delete_records('quiz_grades', array('quiz' => $quiz->id));
412 /**
413  * Delete all the attempts belonging to a user in a particular quiz.
414  *
415  * @param object $quiz The quiz object.
416  * @param object $user The user object.
417  */
418 function quiz_delete_user_attempts($quiz, $user) {
419     global $CFG, $DB;
420     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
421     question_engine::delete_questions_usage_by_activities(new qubaids_for_quiz_user($quiz->get_quizid(), $user->id));
422     $params = [
423         'quiz' => $quiz->get_quizid(),
424         'userid' => $user->id,
425     ];
426     $DB->delete_records('quiz_attempts', $params);
427     $DB->delete_records('quiz_grades', $params);
430 /**
431  * Get the best current grade for a particular user in a quiz.
432  *
433  * @param object $quiz the quiz settings.
434  * @param int $userid the id of the user.
435  * @return float the user's current grade for this quiz, or null if this user does
436  * not have a grade on this quiz.
437  */
438 function quiz_get_best_grade($quiz, $userid) {
439     global $DB;
440     $grade = $DB->get_field('quiz_grades', 'grade',
441             array('quiz' => $quiz->id, 'userid' => $userid));
443     // Need to detect errors/no result, without catching 0 grades.
444     if ($grade === false) {
445         return null;
446     }
448     return $grade + 0; // Convert to number.
451 /**
452  * Is this a graded quiz? If this method returns true, you can assume that
453  * $quiz->grade and $quiz->sumgrades are non-zero (for example, if you want to
454  * divide by them).
455  *
456  * @param object $quiz a row from the quiz table.
457  * @return bool whether this is a graded quiz.
458  */
459 function quiz_has_grades($quiz) {
460     return $quiz->grade >= 0.000005 && $quiz->sumgrades >= 0.000005;
463 /**
464  * Does this quiz allow multiple tries?
465  *
466  * @return bool
467  */
468 function quiz_allows_multiple_tries($quiz) {
469     $bt = question_engine::get_behaviour_type($quiz->preferredbehaviour);
470     return $bt->allows_multiple_submitted_responses();
473 /**
474  * Return a small object with summary information about what a
475  * user has done with a given particular instance of this module
476  * Used for user activity reports.
477  * $return->time = the time they did it
478  * $return->info = a short text description
479  *
480  * @param object $course
481  * @param object $user
482  * @param object $mod
483  * @param object $quiz
484  * @return object|null
485  */
486 function quiz_user_outline($course, $user, $mod, $quiz) {
487     global $DB, $CFG;
488     require_once($CFG->libdir . '/gradelib.php');
489     $grades = grade_get_grades($course->id, 'mod', 'quiz', $quiz->id, $user->id);
491     if (empty($grades->items[0]->grades)) {
492         return null;
493     } else {
494         $grade = reset($grades->items[0]->grades);
495     }
497     $result = new stdClass();
498     // If the user can't see hidden grades, don't return that information.
499     $gitem = grade_item::fetch(array('id' => $grades->items[0]->id));
500     if (!$gitem->hidden || has_capability('moodle/grade:viewhidden', context_course::instance($course->id))) {
501         $result->info = get_string('grade') . ': ' . $grade->str_long_grade;
502     } else {
503         $result->info = get_string('grade') . ': ' . get_string('hidden', 'grades');
504     }
506     // Datesubmitted == time created. dategraded == time modified or time overridden
507     // if grade was last modified by the user themselves use date graded. Otherwise use
508     // date submitted.
509     // TODO: move this copied & pasted code somewhere in the grades API. See MDL-26704.
510     if ($grade->usermodified == $user->id || empty($grade->datesubmitted)) {
511         $result->time = $grade->dategraded;
512     } else {
513         $result->time = $grade->datesubmitted;
514     }
516     return $result;
519 /**
520  * Print a detailed representation of what a  user has done with
521  * a given particular instance of this module, for user activity reports.
522  *
523  * @param object $course
524  * @param object $user
525  * @param object $mod
526  * @param object $quiz
527  * @return bool
528  */
529 function quiz_user_complete($course, $user, $mod, $quiz) {
530     global $DB, $CFG, $OUTPUT;
531     require_once($CFG->libdir . '/gradelib.php');
532     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
534     $grades = grade_get_grades($course->id, 'mod', 'quiz', $quiz->id, $user->id);
535     if (!empty($grades->items[0]->grades)) {
536         $grade = reset($grades->items[0]->grades);
537         // If the user can't see hidden grades, don't return that information.
538         $gitem = grade_item::fetch(array('id' => $grades->items[0]->id));
539         if (!$gitem->hidden || has_capability('moodle/grade:viewhidden', context_course::instance($course->id))) {
540             echo $OUTPUT->container(get_string('grade').': '.$grade->str_long_grade);
541             if ($grade->str_feedback) {
542                 echo $OUTPUT->container(get_string('feedback').': '.$grade->str_feedback);
543             }
544         } else {
545             echo $OUTPUT->container(get_string('grade') . ': ' . get_string('hidden', 'grades'));
546             if ($grade->str_feedback) {
547                 echo $OUTPUT->container(get_string('feedback').': '.get_string('hidden', 'grades'));
548             }
549         }
550     }
552     if ($attempts = $DB->get_records('quiz_attempts',
553             array('userid' => $user->id, 'quiz' => $quiz->id), 'attempt')) {
554         foreach ($attempts as $attempt) {
555             echo get_string('attempt', 'quiz', $attempt->attempt) . ': ';
556             if ($attempt->state != quiz_attempt::FINISHED) {
557                 echo quiz_attempt_state_name($attempt->state);
558             } else {
559                 if (!isset($gitem)) {
560                     if (!empty($grades->items[0]->grades)) {
561                         $gitem = grade_item::fetch(array('id' => $grades->items[0]->id));
562                     } else {
563                         $gitem = new stdClass();
564                         $gitem->hidden = true;
565                     }
566                 }
567                 if (!$gitem->hidden || has_capability('moodle/grade:viewhidden', context_course::instance($course->id))) {
568                     echo quiz_format_grade($quiz, $attempt->sumgrades) . '/' . quiz_format_grade($quiz, $quiz->sumgrades);
569                 } else {
570                     echo get_string('hidden', 'grades');
571                 }
572             }
573             echo ' - '.userdate($attempt->timemodified).'<br />';
574         }
575     } else {
576         print_string('noattempts', 'quiz');
577     }
579     return true;
582 /**
583  * Quiz periodic clean-up tasks.
584  */
585 function quiz_cron() {
586     global $CFG;
588     require_once($CFG->dirroot . '/mod/quiz/cronlib.php');
589     mtrace('');
591     $timenow = time();
592     $overduehander = new mod_quiz_overdue_attempt_updater();
594     $processto = $timenow - get_config('quiz', 'graceperiodmin');
596     mtrace('  Looking for quiz overdue quiz attempts...');
598     list($count, $quizcount) = $overduehander->update_overdue_attempts($timenow, $processto);
600     mtrace('  Considered ' . $count . ' attempts in ' . $quizcount . ' quizzes.');
602     // Run cron for our sub-plugin types.
603     cron_execute_plugin_type('quiz', 'quiz reports');
604     cron_execute_plugin_type('quizaccess', 'quiz access rules');
606     return true;
609 /**
610  * @param int|array $quizids A quiz ID, or an array of quiz IDs.
611  * @param int $userid the userid.
612  * @param string $status 'all', 'finished' or 'unfinished' to control
613  * @param bool $includepreviews
614  * @return an array of all the user's attempts at this quiz. Returns an empty
615  *      array if there are none.
616  */
617 function quiz_get_user_attempts($quizids, $userid, $status = 'finished', $includepreviews = false) {
618     global $DB, $CFG;
619     // TODO MDL-33071 it is very annoying to have to included all of locallib.php
620     // just to get the quiz_attempt::FINISHED constants, but I will try to sort
621     // that out properly for Moodle 2.4. For now, I will just do a quick fix for
622     // MDL-33048.
623     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
625     $params = array();
626     switch ($status) {
627         case 'all':
628             $statuscondition = '';
629             break;
631         case 'finished':
632             $statuscondition = ' AND state IN (:state1, :state2)';
633             $params['state1'] = quiz_attempt::FINISHED;
634             $params['state2'] = quiz_attempt::ABANDONED;
635             break;
637         case 'unfinished':
638             $statuscondition = ' AND state IN (:state1, :state2)';
639             $params['state1'] = quiz_attempt::IN_PROGRESS;
640             $params['state2'] = quiz_attempt::OVERDUE;
641             break;
642     }
644     $quizids = (array) $quizids;
645     list($insql, $inparams) = $DB->get_in_or_equal($quizids, SQL_PARAMS_NAMED);
646     $params += $inparams;
647     $params['userid'] = $userid;
649     $previewclause = '';
650     if (!$includepreviews) {
651         $previewclause = ' AND preview = 0';
652     }
654     return $DB->get_records_select('quiz_attempts',
655             "quiz $insql AND userid = :userid" . $previewclause . $statuscondition,
656             $params, 'quiz, attempt ASC');
659 /**
660  * Return grade for given user or all users.
661  *
662  * @param int $quizid id of quiz
663  * @param int $userid optional user id, 0 means all users
664  * @return array array of grades, false if none. These are raw grades. They should
665  * be processed with quiz_format_grade for display.
666  */
667 function quiz_get_user_grades($quiz, $userid = 0) {
668     global $CFG, $DB;
670     $params = array($quiz->id);
671     $usertest = '';
672     if ($userid) {
673         $params[] = $userid;
674         $usertest = 'AND u.id = ?';
675     }
676     return $DB->get_records_sql("
677             SELECT
678                 u.id,
679                 u.id AS userid,
680                 qg.grade AS rawgrade,
681                 qg.timemodified AS dategraded,
682                 MAX(qa.timefinish) AS datesubmitted
684             FROM {user} u
685             JOIN {quiz_grades} qg ON u.id = qg.userid
686             JOIN {quiz_attempts} qa ON qa.quiz = qg.quiz AND qa.userid = u.id
688             WHERE qg.quiz = ?
689             $usertest
690             GROUP BY u.id, qg.grade, qg.timemodified", $params);
693 /**
694  * Round a grade to to the correct number of decimal places, and format it for display.
695  *
696  * @param object $quiz The quiz table row, only $quiz->decimalpoints is used.
697  * @param float $grade The grade to round.
698  * @return float
699  */
700 function quiz_format_grade($quiz, $grade) {
701     if (is_null($grade)) {
702         return get_string('notyetgraded', 'quiz');
703     }
704     return format_float($grade, $quiz->decimalpoints);
707 /**
708  * Determine the correct number of decimal places required to format a grade.
709  *
710  * @param object $quiz The quiz table row, only $quiz->decimalpoints is used.
711  * @return integer
712  */
713 function quiz_get_grade_format($quiz) {
714     if (empty($quiz->questiondecimalpoints)) {
715         $quiz->questiondecimalpoints = -1;
716     }
718     if ($quiz->questiondecimalpoints == -1) {
719         return $quiz->decimalpoints;
720     }
722     return $quiz->questiondecimalpoints;
725 /**
726  * Round a grade to the correct number of decimal places, and format it for display.
727  *
728  * @param object $quiz The quiz table row, only $quiz->decimalpoints is used.
729  * @param float $grade The grade to round.
730  * @return float
731  */
732 function quiz_format_question_grade($quiz, $grade) {
733     return format_float($grade, quiz_get_grade_format($quiz));
736 /**
737  * Update grades in central gradebook
738  *
739  * @category grade
740  * @param object $quiz the quiz settings.
741  * @param int $userid specific user only, 0 means all users.
742  * @param bool $nullifnone If a single user is specified and $nullifnone is true a grade item with a null rawgrade will be inserted
743  */
744 function quiz_update_grades($quiz, $userid = 0, $nullifnone = true) {
745     global $CFG, $DB;
746     require_once($CFG->libdir . '/gradelib.php');
748     if ($quiz->grade == 0) {
749         quiz_grade_item_update($quiz);
751     } else if ($grades = quiz_get_user_grades($quiz, $userid)) {
752         quiz_grade_item_update($quiz, $grades);
754     } else if ($userid && $nullifnone) {
755         $grade = new stdClass();
756         $grade->userid = $userid;
757         $grade->rawgrade = null;
758         quiz_grade_item_update($quiz, $grade);
760     } else {
761         quiz_grade_item_update($quiz);
762     }
765 /**
766  * Create or update the grade item for given quiz
767  *
768  * @category grade
769  * @param object $quiz object with extra cmidnumber
770  * @param mixed $grades optional array/object of grade(s); 'reset' means reset grades in gradebook
771  * @return int 0 if ok, error code otherwise
772  */
773 function quiz_grade_item_update($quiz, $grades = null) {
774     global $CFG, $OUTPUT;
775     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
776     require_once($CFG->libdir . '/gradelib.php');
778     if (array_key_exists('cmidnumber', $quiz)) { // May not be always present.
779         $params = array('itemname' => $quiz->name, 'idnumber' => $quiz->cmidnumber);
780     } else {
781         $params = array('itemname' => $quiz->name);
782     }
784     if ($quiz->grade > 0) {
785         $params['gradetype'] = GRADE_TYPE_VALUE;
786         $params['grademax']  = $quiz->grade;
787         $params['grademin']  = 0;
789     } else {
790         $params['gradetype'] = GRADE_TYPE_NONE;
791     }
793     // What this is trying to do:
794     // 1. If the quiz is set to not show grades while the quiz is still open,
795     //    and is set to show grades after the quiz is closed, then create the
796     //    grade_item with a show-after date that is the quiz close date.
797     // 2. If the quiz is set to not show grades at either of those times,
798     //    create the grade_item as hidden.
799     // 3. If the quiz is set to show grades, create the grade_item visible.
800     $openreviewoptions = mod_quiz_display_options::make_from_quiz($quiz,
801             mod_quiz_display_options::LATER_WHILE_OPEN);
802     $closedreviewoptions = mod_quiz_display_options::make_from_quiz($quiz,
803             mod_quiz_display_options::AFTER_CLOSE);
804     if ($openreviewoptions->marks < question_display_options::MARK_AND_MAX &&
805             $closedreviewoptions->marks < question_display_options::MARK_AND_MAX) {
806         $params['hidden'] = 1;
808     } else if ($openreviewoptions->marks < question_display_options::MARK_AND_MAX &&
809             $closedreviewoptions->marks >= question_display_options::MARK_AND_MAX) {
810         if ($quiz->timeclose) {
811             $params['hidden'] = $quiz->timeclose;
812         } else {
813             $params['hidden'] = 1;
814         }
816     } else {
817         // Either
818         // a) both open and closed enabled
819         // b) open enabled, closed disabled - we can not "hide after",
820         //    grades are kept visible even after closing.
821         $params['hidden'] = 0;
822     }
824     if (!$params['hidden']) {
825         // If the grade item is not hidden by the quiz logic, then we need to
826         // hide it if the quiz is hidden from students.
827         if (property_exists($quiz, 'visible')) {
828             // Saving the quiz form, and cm not yet updated in the database.
829             $params['hidden'] = !$quiz->visible;
830         } else {
831             $cm = get_coursemodule_from_instance('quiz', $quiz->id);
832             $params['hidden'] = !$cm->visible;
833         }
834     }
836     if ($grades  === 'reset') {
837         $params['reset'] = true;
838         $grades = null;
839     }
841     $gradebook_grades = grade_get_grades($quiz->course, 'mod', 'quiz', $quiz->id);
842     if (!empty($gradebook_grades->items)) {
843         $grade_item = $gradebook_grades->items[0];
844         if ($grade_item->locked) {
845             // NOTE: this is an extremely nasty hack! It is not a bug if this confirmation fails badly. --skodak.
846             $confirm_regrade = optional_param('confirm_regrade', 0, PARAM_INT);
847             if (!$confirm_regrade) {
848                 if (!AJAX_SCRIPT) {
849                     $message = get_string('gradeitemislocked', 'grades');
850                     $back_link = $CFG->wwwroot . '/mod/quiz/report.php?q=' . $quiz->id .
851                             '&amp;mode=overview';
852                     $regrade_link = qualified_me() . '&amp;confirm_regrade=1';
853                     echo $OUTPUT->box_start('generalbox', 'notice');
854                     echo '<p>'. $message .'</p>';
855                     echo $OUTPUT->container_start('buttons');
856                     echo $OUTPUT->single_button($regrade_link, get_string('regradeanyway', 'grades'));
857                     echo $OUTPUT->single_button($back_link,  get_string('cancel'));
858                     echo $OUTPUT->container_end();
859                     echo $OUTPUT->box_end();
860                 }
861                 return GRADE_UPDATE_ITEM_LOCKED;
862             }
863         }
864     }
866     return grade_update('mod/quiz', $quiz->course, 'mod', 'quiz', $quiz->id, 0, $grades, $params);
869 /**
870  * Delete grade item for given quiz
871  *
872  * @category grade
873  * @param object $quiz object
874  * @return object quiz
875  */
876 function quiz_grade_item_delete($quiz) {
877     global $CFG;
878     require_once($CFG->libdir . '/gradelib.php');
880     return grade_update('mod/quiz', $quiz->course, 'mod', 'quiz', $quiz->id, 0,
881             null, array('deleted' => 1));
884 /**
885  * This standard function will check all instances of this module
886  * and make sure there are up-to-date events created for each of them.
887  * If courseid = 0, then every quiz event in the site is checked, else
888  * only quiz events belonging to the course specified are checked.
889  * This function is used, in its new format, by restore_refresh_events()
890  *
891  * @param int $courseid
892  * @param int|stdClass $instance Quiz module instance or ID.
893  * @param int|stdClass $cm Course module object or ID (not used in this module).
894  * @return bool
895  */
896 function quiz_refresh_events($courseid = 0, $instance = null, $cm = null) {
897     global $DB;
899     // If we have instance information then we can just update the one event instead of updating all events.
900     if (isset($instance)) {
901         if (!is_object($instance)) {
902             $instance = $DB->get_record('quiz', array('id' => $instance), '*', MUST_EXIST);
903         }
904         quiz_update_events($instance);
905         return true;
906     }
908     if ($courseid == 0) {
909         if (!$quizzes = $DB->get_records('quiz')) {
910             return true;
911         }
912     } else {
913         if (!$quizzes = $DB->get_records('quiz', array('course' => $courseid))) {
914             return true;
915         }
916     }
918     foreach ($quizzes as $quiz) {
919         quiz_update_events($quiz);
920     }
922     return true;
925 /**
926  * Returns all quiz graded users since a given time for specified quiz
927  */
928 function quiz_get_recent_mod_activity(&$activities, &$index, $timestart,
929         $courseid, $cmid, $userid = 0, $groupid = 0) {
930     global $CFG, $USER, $DB;
931     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
933     $course = get_course($courseid);
934     $modinfo = get_fast_modinfo($course);
936     $cm = $modinfo->cms[$cmid];
937     $quiz = $DB->get_record('quiz', array('id' => $cm->instance));
939     if ($userid) {
940         $userselect = "AND u.id = :userid";
941         $params['userid'] = $userid;
942     } else {
943         $userselect = '';
944     }
946     if ($groupid) {
947         $groupselect = 'AND gm.groupid = :groupid';
948         $groupjoin   = 'JOIN {groups_members} gm ON  gm.userid=u.id';
949         $params['groupid'] = $groupid;
950     } else {
951         $groupselect = '';
952         $groupjoin   = '';
953     }
955     $params['timestart'] = $timestart;
956     $params['quizid'] = $quiz->id;
958     $ufields = user_picture::fields('u', null, 'useridagain');
959     if (!$attempts = $DB->get_records_sql("
960               SELECT qa.*,
961                      {$ufields}
962                 FROM {quiz_attempts} qa
963                      JOIN {user} u ON u.id = qa.userid
964                      $groupjoin
965                WHERE qa.timefinish > :timestart
966                  AND qa.quiz = :quizid
967                  AND qa.preview = 0
968                      $userselect
969                      $groupselect
970             ORDER BY qa.timefinish ASC", $params)) {
971         return;
972     }
974     $context         = context_module::instance($cm->id);
975     $accessallgroups = has_capability('moodle/site:accessallgroups', $context);
976     $viewfullnames   = has_capability('moodle/site:viewfullnames', $context);
977     $grader          = has_capability('mod/quiz:viewreports', $context);
978     $groupmode       = groups_get_activity_groupmode($cm, $course);
980     $usersgroups = null;
981     $aname = format_string($cm->name, true);
982     foreach ($attempts as $attempt) {
983         if ($attempt->userid != $USER->id) {
984             if (!$grader) {
985                 // Grade permission required.
986                 continue;
987             }
989             if ($groupmode == SEPARATEGROUPS and !$accessallgroups) {
990                 $usersgroups = groups_get_all_groups($course->id,
991                         $attempt->userid, $cm->groupingid);
992                 $usersgroups = array_keys($usersgroups);
993                 if (!array_intersect($usersgroups, $modinfo->get_groups($cm->groupingid))) {
994                     continue;
995                 }
996             }
997         }
999         $options = quiz_get_review_options($quiz, $attempt, $context);
1001         $tmpactivity = new stdClass();
1003         $tmpactivity->type       = 'quiz';
1004         $tmpactivity->cmid       = $cm->id;
1005         $tmpactivity->name       = $aname;
1006         $tmpactivity->sectionnum = $cm->sectionnum;
1007         $tmpactivity->timestamp  = $attempt->timefinish;
1009         $tmpactivity->content = new stdClass();
1010         $tmpactivity->content->attemptid = $attempt->id;
1011         $tmpactivity->content->attempt   = $attempt->attempt;
1012         if (quiz_has_grades($quiz) && $options->marks >= question_display_options::MARK_AND_MAX) {
1013             $tmpactivity->content->sumgrades = quiz_format_grade($quiz, $attempt->sumgrades);
1014             $tmpactivity->content->maxgrade  = quiz_format_grade($quiz, $quiz->sumgrades);
1015         } else {
1016             $tmpactivity->content->sumgrades = null;
1017             $tmpactivity->content->maxgrade  = null;
1018         }
1020         $tmpactivity->user = user_picture::unalias($attempt, null, 'useridagain');
1021         $tmpactivity->user->fullname  = fullname($tmpactivity->user, $viewfullnames);
1023         $activities[$index++] = $tmpactivity;
1024     }
1027 function quiz_print_recent_mod_activity($activity, $courseid, $detail, $modnames) {
1028     global $CFG, $OUTPUT;
1030     echo '<table border="0" cellpadding="3" cellspacing="0" class="forum-recent">';
1032     echo '<tr><td class="userpicture" valign="top">';
1033     echo $OUTPUT->user_picture($activity->user, array('courseid' => $courseid));
1034     echo '</td><td>';
1036     if ($detail) {
1037         $modname = $modnames[$activity->type];
1038         echo '<div class="title">';
1039         echo $OUTPUT->image_icon('icon', $modname, $activity->type);
1040         echo '<a href="' . $CFG->wwwroot . '/mod/quiz/view.php?id=' .
1041                 $activity->cmid . '">' . $activity->name . '</a>';
1042         echo '</div>';
1043     }
1045     echo '<div class="grade">';
1046     echo  get_string('attempt', 'quiz', $activity->content->attempt);
1047     if (isset($activity->content->maxgrade)) {
1048         $grades = $activity->content->sumgrades . ' / ' . $activity->content->maxgrade;
1049         echo ': (<a href="' . $CFG->wwwroot . '/mod/quiz/review.php?attempt=' .
1050                 $activity->content->attemptid . '">' . $grades . '</a>)';
1051     }
1052     echo '</div>';
1054     echo '<div class="user">';
1055     echo '<a href="' . $CFG->wwwroot . '/user/view.php?id=' . $activity->user->id .
1056             '&amp;course=' . $courseid . '">' . $activity->user->fullname .
1057             '</a> - ' . userdate($activity->timestamp);
1058     echo '</div>';
1060     echo '</td></tr></table>';
1062     return;
1065 /**
1066  * Pre-process the quiz options form data, making any necessary adjustments.
1067  * Called by add/update instance in this file.
1068  *
1069  * @param object $quiz The variables set on the form.
1070  */
1071 function quiz_process_options($quiz) {
1072     global $CFG;
1073     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
1074     require_once($CFG->libdir . '/questionlib.php');
1076     $quiz->timemodified = time();
1078     // Quiz name.
1079     if (!empty($quiz->name)) {
1080         $quiz->name = trim($quiz->name);
1081     }
1083     // Password field - different in form to stop browsers that remember passwords
1084     // getting confused.
1085     $quiz->password = $quiz->quizpassword;
1086     unset($quiz->quizpassword);
1088     // Quiz feedback.
1089     if (isset($quiz->feedbacktext)) {
1090         // Clean up the boundary text.
1091         for ($i = 0; $i < count($quiz->feedbacktext); $i += 1) {
1092             if (empty($quiz->feedbacktext[$i]['text'])) {
1093                 $quiz->feedbacktext[$i]['text'] = '';
1094             } else {
1095                 $quiz->feedbacktext[$i]['text'] = trim($quiz->feedbacktext[$i]['text']);
1096             }
1097         }
1099         // Check the boundary value is a number or a percentage, and in range.
1100         $i = 0;
1101         while (!empty($quiz->feedbackboundaries[$i])) {
1102             $boundary = trim($quiz->feedbackboundaries[$i]);
1103             if (!is_numeric($boundary)) {
1104                 if (strlen($boundary) > 0 && $boundary[strlen($boundary) - 1] == '%') {
1105                     $boundary = trim(substr($boundary, 0, -1));
1106                     if (is_numeric($boundary)) {
1107                         $boundary = $boundary * $quiz->grade / 100.0;
1108                     } else {
1109                         return get_string('feedbackerrorboundaryformat', 'quiz', $i + 1);
1110                     }
1111                 }
1112             }
1113             if ($boundary <= 0 || $boundary >= $quiz->grade) {
1114                 return get_string('feedbackerrorboundaryoutofrange', 'quiz', $i + 1);
1115             }
1116             if ($i > 0 && $boundary >= $quiz->feedbackboundaries[$i - 1]) {
1117                 return get_string('feedbackerrororder', 'quiz', $i + 1);
1118             }
1119             $quiz->feedbackboundaries[$i] = $boundary;
1120             $i += 1;
1121         }
1122         $numboundaries = $i;
1124         // Check there is nothing in the remaining unused fields.
1125         if (!empty($quiz->feedbackboundaries)) {
1126             for ($i = $numboundaries; $i < count($quiz->feedbackboundaries); $i += 1) {
1127                 if (!empty($quiz->feedbackboundaries[$i]) &&
1128                         trim($quiz->feedbackboundaries[$i]) != '') {
1129                     return get_string('feedbackerrorjunkinboundary', 'quiz', $i + 1);
1130                 }
1131             }
1132         }
1133         for ($i = $numboundaries + 1; $i < count($quiz->feedbacktext); $i += 1) {
1134             if (!empty($quiz->feedbacktext[$i]['text']) &&
1135                     trim($quiz->feedbacktext[$i]['text']) != '') {
1136                 return get_string('feedbackerrorjunkinfeedback', 'quiz', $i + 1);
1137             }
1138         }
1139         // Needs to be bigger than $quiz->grade because of '<' test in quiz_feedback_for_grade().
1140         $quiz->feedbackboundaries[-1] = $quiz->grade + 1;
1141         $quiz->feedbackboundaries[$numboundaries] = 0;
1142         $quiz->feedbackboundarycount = $numboundaries;
1143     } else {
1144         $quiz->feedbackboundarycount = -1;
1145     }
1147     // Combing the individual settings into the review columns.
1148     $quiz->reviewattempt = quiz_review_option_form_to_db($quiz, 'attempt');
1149     $quiz->reviewcorrectness = quiz_review_option_form_to_db($quiz, 'correctness');
1150     $quiz->reviewmarks = quiz_review_option_form_to_db($quiz, 'marks');
1151     $quiz->reviewspecificfeedback = quiz_review_option_form_to_db($quiz, 'specificfeedback');
1152     $quiz->reviewgeneralfeedback = quiz_review_option_form_to_db($quiz, 'generalfeedback');
1153     $quiz->reviewrightanswer = quiz_review_option_form_to_db($quiz, 'rightanswer');
1154     $quiz->reviewoverallfeedback = quiz_review_option_form_to_db($quiz, 'overallfeedback');
1155     $quiz->reviewattempt |= mod_quiz_display_options::DURING;
1156     $quiz->reviewoverallfeedback &= ~mod_quiz_display_options::DURING;
1159 /**
1160  * Helper function for {@link quiz_process_options()}.
1161  * @param object $fromform the sumbitted form date.
1162  * @param string $field one of the review option field names.
1163  */
1164 function quiz_review_option_form_to_db($fromform, $field) {
1165     static $times = array(
1166         'during' => mod_quiz_display_options::DURING,
1167         'immediately' => mod_quiz_display_options::IMMEDIATELY_AFTER,
1168         'open' => mod_quiz_display_options::LATER_WHILE_OPEN,
1169         'closed' => mod_quiz_display_options::AFTER_CLOSE,
1170     );
1172     $review = 0;
1173     foreach ($times as $whenname => $when) {
1174         $fieldname = $field . $whenname;
1175         if (isset($fromform->$fieldname)) {
1176             $review |= $when;
1177             unset($fromform->$fieldname);
1178         }
1179     }
1181     return $review;
1184 /**
1185  * This function is called at the end of quiz_add_instance
1186  * and quiz_update_instance, to do the common processing.
1187  *
1188  * @param object $quiz the quiz object.
1189  */
1190 function quiz_after_add_or_update($quiz) {
1191     global $DB;
1192     $cmid = $quiz->coursemodule;
1194     // We need to use context now, so we need to make sure all needed info is already in db.
1195     $DB->set_field('course_modules', 'instance', $quiz->id, array('id'=>$cmid));
1196     $context = context_module::instance($cmid);
1198     // Save the feedback.
1199     $DB->delete_records('quiz_feedback', array('quizid' => $quiz->id));
1201     for ($i = 0; $i <= $quiz->feedbackboundarycount; $i++) {
1202         $feedback = new stdClass();
1203         $feedback->quizid = $quiz->id;
1204         $feedback->feedbacktext = $quiz->feedbacktext[$i]['text'];
1205         $feedback->feedbacktextformat = $quiz->feedbacktext[$i]['format'];
1206         $feedback->mingrade = $quiz->feedbackboundaries[$i];
1207         $feedback->maxgrade = $quiz->feedbackboundaries[$i - 1];
1208         $feedback->id = $DB->insert_record('quiz_feedback', $feedback);
1209         $feedbacktext = file_save_draft_area_files((int)$quiz->feedbacktext[$i]['itemid'],
1210                 $context->id, 'mod_quiz', 'feedback', $feedback->id,
1211                 array('subdirs' => false, 'maxfiles' => -1, 'maxbytes' => 0),
1212                 $quiz->feedbacktext[$i]['text']);
1213         $DB->set_field('quiz_feedback', 'feedbacktext', $feedbacktext,
1214                 array('id' => $feedback->id));
1215     }
1217     // Store any settings belonging to the access rules.
1218     quiz_access_manager::save_settings($quiz);
1220     // Update the events relating to this quiz.
1221     quiz_update_events($quiz);
1222     $completionexpected = (!empty($quiz->completionexpected)) ? $quiz->completionexpected : null;
1223     \core_completion\api::update_completion_date_event($quiz->coursemodule, 'quiz', $quiz->id, $completionexpected);
1225     // Update related grade item.
1226     quiz_grade_item_update($quiz);
1229 /**
1230  * This function updates the events associated to the quiz.
1231  * If $override is non-zero, then it updates only the events
1232  * associated with the specified override.
1233  *
1234  * @uses QUIZ_MAX_EVENT_LENGTH
1235  * @param object $quiz the quiz object.
1236  * @param object optional $override limit to a specific override
1237  */
1238 function quiz_update_events($quiz, $override = null) {
1239     global $DB;
1241     // Load the old events relating to this quiz.
1242     $conds = array('modulename'=>'quiz',
1243                    'instance'=>$quiz->id);
1244     if (!empty($override)) {
1245         // Only load events for this override.
1246         if (isset($override->userid)) {
1247             $conds['userid'] = $override->userid;
1248         } else {
1249             $conds['groupid'] = $override->groupid;
1250         }
1251     }
1252     $oldevents = $DB->get_records('event', $conds, 'id ASC');
1254     // Now make a to-do list of all that needs to be updated.
1255     if (empty($override)) {
1256         // We are updating the primary settings for the quiz, so we need to add all the overrides.
1257         $overrides = $DB->get_records('quiz_overrides', array('quiz' => $quiz->id), 'id ASC');
1258         // It is necessary to add an empty stdClass to the beginning of the array as the $oldevents
1259         // list contains the original (non-override) event for the module. If this is not included
1260         // the logic below will end up updating the wrong row when we try to reconcile this $overrides
1261         // list against the $oldevents list.
1262         array_unshift($overrides, new stdClass());
1263     } else {
1264         // Just do the one override.
1265         $overrides = array($override);
1266     }
1268     // Get group override priorities.
1269     $grouppriorities = quiz_get_group_override_priorities($quiz->id);
1271     foreach ($overrides as $current) {
1272         $groupid   = isset($current->groupid)?  $current->groupid : 0;
1273         $userid    = isset($current->userid)? $current->userid : 0;
1274         $timeopen  = isset($current->timeopen)?  $current->timeopen : $quiz->timeopen;
1275         $timeclose = isset($current->timeclose)? $current->timeclose : $quiz->timeclose;
1277         // Only add open/close events for an override if they differ from the quiz default.
1278         $addopen  = empty($current->id) || !empty($current->timeopen);
1279         $addclose = empty($current->id) || !empty($current->timeclose);
1281         if (!empty($quiz->coursemodule)) {
1282             $cmid = $quiz->coursemodule;
1283         } else {
1284             $cmid = get_coursemodule_from_instance('quiz', $quiz->id, $quiz->course)->id;
1285         }
1287         $event = new stdClass();
1288         $event->type = !$timeclose ? CALENDAR_EVENT_TYPE_ACTION : CALENDAR_EVENT_TYPE_STANDARD;
1289         $event->description = format_module_intro('quiz', $quiz, $cmid);
1290         // Events module won't show user events when the courseid is nonzero.
1291         $event->courseid    = ($userid) ? 0 : $quiz->course;
1292         $event->groupid     = $groupid;
1293         $event->userid      = $userid;
1294         $event->modulename  = 'quiz';
1295         $event->instance    = $quiz->id;
1296         $event->timestart   = $timeopen;
1297         $event->timeduration = max($timeclose - $timeopen, 0);
1298         $event->timesort    = $timeopen;
1299         $event->visible     = instance_is_visible('quiz', $quiz);
1300         $event->eventtype   = QUIZ_EVENT_TYPE_OPEN;
1301         $event->priority    = null;
1303         // Determine the event name and priority.
1304         if ($groupid) {
1305             // Group override event.
1306             $params = new stdClass();
1307             $params->quiz = $quiz->name;
1308             $params->group = groups_get_group_name($groupid);
1309             if ($params->group === false) {
1310                 // Group doesn't exist, just skip it.
1311                 continue;
1312             }
1313             $eventname = get_string('overridegroupeventname', 'quiz', $params);
1314             // Set group override priority.
1315             if ($grouppriorities !== null) {
1316                 $openpriorities = $grouppriorities['open'];
1317                 if (isset($openpriorities[$timeopen])) {
1318                     $event->priority = $openpriorities[$timeopen];
1319                 }
1320             }
1321         } else if ($userid) {
1322             // User override event.
1323             $params = new stdClass();
1324             $params->quiz = $quiz->name;
1325             $eventname = get_string('overrideusereventname', 'quiz', $params);
1326             // Set user override priority.
1327             $event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY;
1328         } else {
1329             // The parent event.
1330             $eventname = $quiz->name;
1331         }
1333         if ($addopen or $addclose) {
1334             // Separate start and end events.
1335             $event->timeduration  = 0;
1336             if ($timeopen && $addopen) {
1337                 if ($oldevent = array_shift($oldevents)) {
1338                     $event->id = $oldevent->id;
1339                 } else {
1340                     unset($event->id);
1341                 }
1342                 $event->name = get_string('quizeventopens', 'quiz', $eventname);
1343                 // The method calendar_event::create will reuse a db record if the id field is set.
1344                 calendar_event::create($event);
1345             }
1346             if ($timeclose && $addclose) {
1347                 if ($oldevent = array_shift($oldevents)) {
1348                     $event->id = $oldevent->id;
1349                 } else {
1350                     unset($event->id);
1351                 }
1352                 $event->type      = CALENDAR_EVENT_TYPE_ACTION;
1353                 $event->name      = get_string('quizeventcloses', 'quiz', $eventname);
1354                 $event->timestart = $timeclose;
1355                 $event->timesort  = $timeclose;
1356                 $event->eventtype = QUIZ_EVENT_TYPE_CLOSE;
1357                 if ($groupid && $grouppriorities !== null) {
1358                     $closepriorities = $grouppriorities['close'];
1359                     if (isset($closepriorities[$timeclose])) {
1360                         $event->priority = $closepriorities[$timeclose];
1361                     }
1362                 }
1363                 calendar_event::create($event);
1364             }
1365         }
1366     }
1368     // Delete any leftover events.
1369     foreach ($oldevents as $badevent) {
1370         $badevent = calendar_event::load($badevent);
1371         $badevent->delete();
1372     }
1375 /**
1376  * Calculates the priorities of timeopen and timeclose values for group overrides for a quiz.
1377  *
1378  * @param int $quizid The quiz ID.
1379  * @return array|null Array of group override priorities for open and close times. Null if there are no group overrides.
1380  */
1381 function quiz_get_group_override_priorities($quizid) {
1382     global $DB;
1384     // Fetch group overrides.
1385     $where = 'quiz = :quiz AND groupid IS NOT NULL';
1386     $params = ['quiz' => $quizid];
1387     $overrides = $DB->get_records_select('quiz_overrides', $where, $params, '', 'id, timeopen, timeclose');
1388     if (!$overrides) {
1389         return null;
1390     }
1392     $grouptimeopen = [];
1393     $grouptimeclose = [];
1394     foreach ($overrides as $override) {
1395         if ($override->timeopen !== null && !in_array($override->timeopen, $grouptimeopen)) {
1396             $grouptimeopen[] = $override->timeopen;
1397         }
1398         if ($override->timeclose !== null && !in_array($override->timeclose, $grouptimeclose)) {
1399             $grouptimeclose[] = $override->timeclose;
1400         }
1401     }
1403     // Sort open times in ascending manner. The earlier open time gets higher priority.
1404     sort($grouptimeopen);
1405     // Set priorities.
1406     $opengrouppriorities = [];
1407     $openpriority = 1;
1408     foreach ($grouptimeopen as $timeopen) {
1409         $opengrouppriorities[$timeopen] = $openpriority++;
1410     }
1412     // Sort close times in descending manner. The later close time gets higher priority.
1413     rsort($grouptimeclose);
1414     // Set priorities.
1415     $closegrouppriorities = [];
1416     $closepriority = 1;
1417     foreach ($grouptimeclose as $timeclose) {
1418         $closegrouppriorities[$timeclose] = $closepriority++;
1419     }
1421     return [
1422         'open' => $opengrouppriorities,
1423         'close' => $closegrouppriorities
1424     ];
1427 /**
1428  * List the actions that correspond to a view of this module.
1429  * This is used by the participation report.
1430  *
1431  * Note: This is not used by new logging system. Event with
1432  *       crud = 'r' and edulevel = LEVEL_PARTICIPATING will
1433  *       be considered as view action.
1434  *
1435  * @return array
1436  */
1437 function quiz_get_view_actions() {
1438     return array('view', 'view all', 'report', 'review');
1441 /**
1442  * List the actions that correspond to a post of this module.
1443  * This is used by the participation report.
1444  *
1445  * Note: This is not used by new logging system. Event with
1446  *       crud = ('c' || 'u' || 'd') and edulevel = LEVEL_PARTICIPATING
1447  *       will be considered as post action.
1448  *
1449  * @return array
1450  */
1451 function quiz_get_post_actions() {
1452     return array('attempt', 'close attempt', 'preview', 'editquestions',
1453             'delete attempt', 'manualgrade');
1456 /**
1457  * @param array $questionids of question ids.
1458  * @return bool whether any of these questions are used by any instance of this module.
1459  */
1460 function quiz_questions_in_use($questionids) {
1461     global $DB, $CFG;
1462     require_once($CFG->libdir . '/questionlib.php');
1463     list($test, $params) = $DB->get_in_or_equal($questionids);
1464     return $DB->record_exists_select('quiz_slots',
1465             'questionid ' . $test, $params) || question_engine::questions_in_use(
1466             $questionids, new qubaid_join('{quiz_attempts} quiza',
1467             'quiza.uniqueid', 'quiza.preview = 0'));
1470 /**
1471  * Implementation of the function for printing the form elements that control
1472  * whether the course reset functionality affects the quiz.
1473  *
1474  * @param $mform the course reset form that is being built.
1475  */
1476 function quiz_reset_course_form_definition($mform) {
1477     $mform->addElement('header', 'quizheader', get_string('modulenameplural', 'quiz'));
1478     $mform->addElement('advcheckbox', 'reset_quiz_attempts',
1479             get_string('removeallquizattempts', 'quiz'));
1480     $mform->addElement('advcheckbox', 'reset_quiz_user_overrides',
1481             get_string('removealluseroverrides', 'quiz'));
1482     $mform->addElement('advcheckbox', 'reset_quiz_group_overrides',
1483             get_string('removeallgroupoverrides', 'quiz'));
1486 /**
1487  * Course reset form defaults.
1488  * @return array the defaults.
1489  */
1490 function quiz_reset_course_form_defaults($course) {
1491     return array('reset_quiz_attempts' => 1,
1492                  'reset_quiz_group_overrides' => 1,
1493                  'reset_quiz_user_overrides' => 1);
1496 /**
1497  * Removes all grades from gradebook
1498  *
1499  * @param int $courseid
1500  * @param string optional type
1501  */
1502 function quiz_reset_gradebook($courseid, $type='') {
1503     global $CFG, $DB;
1505     $quizzes = $DB->get_records_sql("
1506             SELECT q.*, cm.idnumber as cmidnumber, q.course as courseid
1507             FROM {modules} m
1508             JOIN {course_modules} cm ON m.id = cm.module
1509             JOIN {quiz} q ON cm.instance = q.id
1510             WHERE m.name = 'quiz' AND cm.course = ?", array($courseid));
1512     foreach ($quizzes as $quiz) {
1513         quiz_grade_item_update($quiz, 'reset');
1514     }
1517 /**
1518  * Actual implementation of the reset course functionality, delete all the
1519  * quiz attempts for course $data->courseid, if $data->reset_quiz_attempts is
1520  * set and true.
1521  *
1522  * Also, move the quiz open and close dates, if the course start date is changing.
1523  *
1524  * @param object $data the data submitted from the reset course.
1525  * @return array status array
1526  */
1527 function quiz_reset_userdata($data) {
1528     global $CFG, $DB;
1529     require_once($CFG->libdir . '/questionlib.php');
1531     $componentstr = get_string('modulenameplural', 'quiz');
1532     $status = array();
1534     // Delete attempts.
1535     if (!empty($data->reset_quiz_attempts)) {
1536         question_engine::delete_questions_usage_by_activities(new qubaid_join(
1537                 '{quiz_attempts} quiza JOIN {quiz} quiz ON quiza.quiz = quiz.id',
1538                 'quiza.uniqueid', 'quiz.course = :quizcourseid',
1539                 array('quizcourseid' => $data->courseid)));
1541         $DB->delete_records_select('quiz_attempts',
1542                 'quiz IN (SELECT id FROM {quiz} WHERE course = ?)', array($data->courseid));
1543         $status[] = array(
1544             'component' => $componentstr,
1545             'item' => get_string('attemptsdeleted', 'quiz'),
1546             'error' => false);
1548         // Remove all grades from gradebook.
1549         $DB->delete_records_select('quiz_grades',
1550                 'quiz IN (SELECT id FROM {quiz} WHERE course = ?)', array($data->courseid));
1551         if (empty($data->reset_gradebook_grades)) {
1552             quiz_reset_gradebook($data->courseid);
1553         }
1554         $status[] = array(
1555             'component' => $componentstr,
1556             'item' => get_string('gradesdeleted', 'quiz'),
1557             'error' => false);
1558     }
1560     // Remove user overrides.
1561     if (!empty($data->reset_quiz_user_overrides)) {
1562         $DB->delete_records_select('quiz_overrides',
1563                 'quiz IN (SELECT id FROM {quiz} WHERE course = ?) AND userid IS NOT NULL', array($data->courseid));
1564         $status[] = array(
1565             'component' => $componentstr,
1566             'item' => get_string('useroverridesdeleted', 'quiz'),
1567             'error' => false);
1568     }
1569     // Remove group overrides.
1570     if (!empty($data->reset_quiz_group_overrides)) {
1571         $DB->delete_records_select('quiz_overrides',
1572                 'quiz IN (SELECT id FROM {quiz} WHERE course = ?) AND groupid IS NOT NULL', array($data->courseid));
1573         $status[] = array(
1574             'component' => $componentstr,
1575             'item' => get_string('groupoverridesdeleted', 'quiz'),
1576             'error' => false);
1577     }
1579     // Updating dates - shift may be negative too.
1580     if ($data->timeshift) {
1581         $DB->execute("UPDATE {quiz_overrides}
1582                          SET timeopen = timeopen + ?
1583                        WHERE quiz IN (SELECT id FROM {quiz} WHERE course = ?)
1584                          AND timeopen <> 0", array($data->timeshift, $data->courseid));
1585         $DB->execute("UPDATE {quiz_overrides}
1586                          SET timeclose = timeclose + ?
1587                        WHERE quiz IN (SELECT id FROM {quiz} WHERE course = ?)
1588                          AND timeclose <> 0", array($data->timeshift, $data->courseid));
1590         // Any changes to the list of dates that needs to be rolled should be same during course restore and course reset.
1591         // See MDL-9367.
1592         shift_course_mod_dates('quiz', array('timeopen', 'timeclose'),
1593                 $data->timeshift, $data->courseid);
1595         $status[] = array(
1596             'component' => $componentstr,
1597             'item' => get_string('openclosedatesupdated', 'quiz'),
1598             'error' => false);
1599     }
1601     return $status;
1604 /**
1605  * Prints quiz summaries on MyMoodle Page
1606  *
1607  * @deprecated since 3.3
1608  * @todo The final deprecation of this function will take place in Moodle 3.7 - see MDL-57487.
1609  * @param array $courses
1610  * @param array $htmlarray
1611  */
1612 function quiz_print_overview($courses, &$htmlarray) {
1613     global $USER, $CFG;
1615     debugging('The function quiz_print_overview() is now deprecated.', DEBUG_DEVELOPER);
1617     // These next 6 Lines are constant in all modules (just change module name).
1618     if (empty($courses) || !is_array($courses) || count($courses) == 0) {
1619         return array();
1620     }
1622     if (!$quizzes = get_all_instances_in_courses('quiz', $courses)) {
1623         return;
1624     }
1626     // Get the quizzes attempts.
1627     $attemptsinfo = [];
1628     $quizids = [];
1629     foreach ($quizzes as $quiz) {
1630         $quizids[] = $quiz->id;
1631         $attemptsinfo[$quiz->id] = ['count' => 0, 'hasfinished' => false];
1632     }
1633     $attempts = quiz_get_user_attempts($quizids, $USER->id);
1634     foreach ($attempts as $attempt) {
1635         $attemptsinfo[$attempt->quiz]['count']++;
1636         $attemptsinfo[$attempt->quiz]['hasfinished'] = true;
1637     }
1638     unset($attempts);
1640     // Fetch some language strings outside the main loop.
1641     $strquiz = get_string('modulename', 'quiz');
1642     $strnoattempts = get_string('noattempts', 'quiz');
1644     // We want to list quizzes that are currently available, and which have a close date.
1645     // This is the same as what the lesson does, and the dabate is in MDL-10568.
1646     $now = time();
1647     foreach ($quizzes as $quiz) {
1648         if ($quiz->timeclose >= $now && $quiz->timeopen < $now) {
1649             $str = '';
1651             // Now provide more information depending on the uers's role.
1652             $context = context_module::instance($quiz->coursemodule);
1653             if (has_capability('mod/quiz:viewreports', $context)) {
1654                 // For teacher-like people, show a summary of the number of student attempts.
1655                 // The $quiz objects returned by get_all_instances_in_course have the necessary $cm
1656                 // fields set to make the following call work.
1657                 $str .= '<div class="info">' . quiz_num_attempt_summary($quiz, $quiz, true) . '</div>';
1659             } else if (has_any_capability(array('mod/quiz:reviewmyattempts', 'mod/quiz:attempt'), $context)) { // Student
1660                 // For student-like people, tell them how many attempts they have made.
1662                 if (isset($USER->id)) {
1663                     if ($attemptsinfo[$quiz->id]['hasfinished']) {
1664                         // The student's last attempt is finished.
1665                         continue;
1666                     }
1668                     if ($attemptsinfo[$quiz->id]['count'] > 0) {
1669                         $str .= '<div class="info">' .
1670                             get_string('numattemptsmade', 'quiz', $attemptsinfo[$quiz->id]['count']) . '</div>';
1671                     } else {
1672                         $str .= '<div class="info">' . $strnoattempts . '</div>';
1673                     }
1675                 } else {
1676                     $str .= '<div class="info">' . $strnoattempts . '</div>';
1677                 }
1679             } else {
1680                 // For ayone else, there is no point listing this quiz, so stop processing.
1681                 continue;
1682             }
1684             // Give a link to the quiz, and the deadline.
1685             $html = '<div class="quiz overview">' .
1686                     '<div class="name">' . $strquiz . ': <a ' .
1687                     ($quiz->visible ? '' : ' class="dimmed"') .
1688                     ' href="' . $CFG->wwwroot . '/mod/quiz/view.php?id=' .
1689                     $quiz->coursemodule . '">' .
1690                     $quiz->name . '</a></div>';
1691             $html .= '<div class="info">' . get_string('quizcloseson', 'quiz',
1692                     userdate($quiz->timeclose)) . '</div>';
1693             $html .= $str;
1694             $html .= '</div>';
1695             if (empty($htmlarray[$quiz->course]['quiz'])) {
1696                 $htmlarray[$quiz->course]['quiz'] = $html;
1697             } else {
1698                 $htmlarray[$quiz->course]['quiz'] .= $html;
1699             }
1700         }
1701     }
1704 /**
1705  * Return a textual summary of the number of attempts that have been made at a particular quiz,
1706  * returns '' if no attempts have been made yet, unless $returnzero is passed as true.
1707  *
1708  * @param object $quiz the quiz object. Only $quiz->id is used at the moment.
1709  * @param object $cm the cm object. Only $cm->course, $cm->groupmode and
1710  *      $cm->groupingid fields are used at the moment.
1711  * @param bool $returnzero if false (default), when no attempts have been
1712  *      made '' is returned instead of 'Attempts: 0'.
1713  * @param int $currentgroup if there is a concept of current group where this method is being called
1714  *         (e.g. a report) pass it in here. Default 0 which means no current group.
1715  * @return string a string like "Attempts: 123", "Attemtps 123 (45 from your groups)" or
1716  *          "Attemtps 123 (45 from this group)".
1717  */
1718 function quiz_num_attempt_summary($quiz, $cm, $returnzero = false, $currentgroup = 0) {
1719     global $DB, $USER;
1720     $numattempts = $DB->count_records('quiz_attempts', array('quiz'=> $quiz->id, 'preview'=>0));
1721     if ($numattempts || $returnzero) {
1722         if (groups_get_activity_groupmode($cm)) {
1723             $a = new stdClass();
1724             $a->total = $numattempts;
1725             if ($currentgroup) {
1726                 $a->group = $DB->count_records_sql('SELECT COUNT(DISTINCT qa.id) FROM ' .
1727                         '{quiz_attempts} qa JOIN ' .
1728                         '{groups_members} gm ON qa.userid = gm.userid ' .
1729                         'WHERE quiz = ? AND preview = 0 AND groupid = ?',
1730                         array($quiz->id, $currentgroup));
1731                 return get_string('attemptsnumthisgroup', 'quiz', $a);
1732             } else if ($groups = groups_get_all_groups($cm->course, $USER->id, $cm->groupingid)) {
1733                 list($usql, $params) = $DB->get_in_or_equal(array_keys($groups));
1734                 $a->group = $DB->count_records_sql('SELECT COUNT(DISTINCT qa.id) FROM ' .
1735                         '{quiz_attempts} qa JOIN ' .
1736                         '{groups_members} gm ON qa.userid = gm.userid ' .
1737                         'WHERE quiz = ? AND preview = 0 AND ' .
1738                         "groupid $usql", array_merge(array($quiz->id), $params));
1739                 return get_string('attemptsnumyourgroups', 'quiz', $a);
1740             }
1741         }
1742         return get_string('attemptsnum', 'quiz', $numattempts);
1743     }
1744     return '';
1747 /**
1748  * Returns the same as {@link quiz_num_attempt_summary()} but wrapped in a link
1749  * to the quiz reports.
1750  *
1751  * @param object $quiz the quiz object. Only $quiz->id is used at the moment.
1752  * @param object $cm the cm object. Only $cm->course, $cm->groupmode and
1753  *      $cm->groupingid fields are used at the moment.
1754  * @param object $context the quiz context.
1755  * @param bool $returnzero if false (default), when no attempts have been made
1756  *      '' is returned instead of 'Attempts: 0'.
1757  * @param int $currentgroup if there is a concept of current group where this method is being called
1758  *         (e.g. a report) pass it in here. Default 0 which means no current group.
1759  * @return string HTML fragment for the link.
1760  */
1761 function quiz_attempt_summary_link_to_reports($quiz, $cm, $context, $returnzero = false,
1762         $currentgroup = 0) {
1763     global $CFG;
1764     $summary = quiz_num_attempt_summary($quiz, $cm, $returnzero, $currentgroup);
1765     if (!$summary) {
1766         return '';
1767     }
1769     require_once($CFG->dirroot . '/mod/quiz/report/reportlib.php');
1770     $url = new moodle_url('/mod/quiz/report.php', array(
1771             'id' => $cm->id, 'mode' => quiz_report_default_report($context)));
1772     return html_writer::link($url, $summary);
1775 /**
1776  * @param string $feature FEATURE_xx constant for requested feature
1777  * @return bool True if quiz supports feature
1778  */
1779 function quiz_supports($feature) {
1780     switch($feature) {
1781         case FEATURE_GROUPS:                    return true;
1782         case FEATURE_GROUPINGS:                 return true;
1783         case FEATURE_MOD_INTRO:                 return true;
1784         case FEATURE_COMPLETION_TRACKS_VIEWS:   return true;
1785         case FEATURE_COMPLETION_HAS_RULES:      return true;
1786         case FEATURE_GRADE_HAS_GRADE:           return true;
1787         case FEATURE_GRADE_OUTCOMES:            return true;
1788         case FEATURE_BACKUP_MOODLE2:            return true;
1789         case FEATURE_SHOW_DESCRIPTION:          return true;
1790         case FEATURE_CONTROLS_GRADE_VISIBILITY: return true;
1791         case FEATURE_USES_QUESTIONS:            return true;
1793         default: return null;
1794     }
1797 /**
1798  * @return array all other caps used in module
1799  */
1800 function quiz_get_extra_capabilities() {
1801     global $CFG;
1802     require_once($CFG->libdir . '/questionlib.php');
1803     $caps = question_get_all_capabilities();
1804     $caps[] = 'moodle/site:accessallgroups';
1805     return $caps;
1808 /**
1809  * This function extends the settings navigation block for the site.
1810  *
1811  * It is safe to rely on PAGE here as we will only ever be within the module
1812  * context when this is called
1813  *
1814  * @param settings_navigation $settings
1815  * @param navigation_node $quiznode
1816  * @return void
1817  */
1818 function quiz_extend_settings_navigation($settings, $quiznode) {
1819     global $PAGE, $CFG;
1821     // Require {@link questionlib.php}
1822     // Included here as we only ever want to include this file if we really need to.
1823     require_once($CFG->libdir . '/questionlib.php');
1825     // We want to add these new nodes after the Edit settings node, and before the
1826     // Locally assigned roles node. Of course, both of those are controlled by capabilities.
1827     $keys = $quiznode->get_children_key_list();
1828     $beforekey = null;
1829     $i = array_search('modedit', $keys);
1830     if ($i === false and array_key_exists(0, $keys)) {
1831         $beforekey = $keys[0];
1832     } else if (array_key_exists($i + 1, $keys)) {
1833         $beforekey = $keys[$i + 1];
1834     }
1836     if (has_capability('mod/quiz:manageoverrides', $PAGE->cm->context)) {
1837         $url = new moodle_url('/mod/quiz/overrides.php', array('cmid'=>$PAGE->cm->id));
1838         $node = navigation_node::create(get_string('groupoverrides', 'quiz'),
1839                 new moodle_url($url, array('mode'=>'group')),
1840                 navigation_node::TYPE_SETTING, null, 'mod_quiz_groupoverrides');
1841         $quiznode->add_node($node, $beforekey);
1843         $node = navigation_node::create(get_string('useroverrides', 'quiz'),
1844                 new moodle_url($url, array('mode'=>'user')),
1845                 navigation_node::TYPE_SETTING, null, 'mod_quiz_useroverrides');
1846         $quiznode->add_node($node, $beforekey);
1847     }
1849     if (has_capability('mod/quiz:manage', $PAGE->cm->context)) {
1850         $node = navigation_node::create(get_string('editquiz', 'quiz'),
1851                 new moodle_url('/mod/quiz/edit.php', array('cmid'=>$PAGE->cm->id)),
1852                 navigation_node::TYPE_SETTING, null, 'mod_quiz_edit',
1853                 new pix_icon('t/edit', ''));
1854         $quiznode->add_node($node, $beforekey);
1855     }
1857     if (has_capability('mod/quiz:preview', $PAGE->cm->context)) {
1858         $url = new moodle_url('/mod/quiz/startattempt.php',
1859                 array('cmid'=>$PAGE->cm->id, 'sesskey'=>sesskey()));
1860         $node = navigation_node::create(get_string('preview', 'quiz'), $url,
1861                 navigation_node::TYPE_SETTING, null, 'mod_quiz_preview',
1862                 new pix_icon('i/preview', ''));
1863         $quiznode->add_node($node, $beforekey);
1864     }
1866     if (has_any_capability(array('mod/quiz:viewreports', 'mod/quiz:grade'), $PAGE->cm->context)) {
1867         require_once($CFG->dirroot . '/mod/quiz/report/reportlib.php');
1868         $reportlist = quiz_report_list($PAGE->cm->context);
1870         $url = new moodle_url('/mod/quiz/report.php',
1871                 array('id' => $PAGE->cm->id, 'mode' => reset($reportlist)));
1872         $reportnode = $quiznode->add_node(navigation_node::create(get_string('results', 'quiz'), $url,
1873                 navigation_node::TYPE_SETTING,
1874                 null, null, new pix_icon('i/report', '')), $beforekey);
1876         foreach ($reportlist as $report) {
1877             $url = new moodle_url('/mod/quiz/report.php',
1878                     array('id' => $PAGE->cm->id, 'mode' => $report));
1879             $reportnode->add_node(navigation_node::create(get_string($report, 'quiz_'.$report), $url,
1880                     navigation_node::TYPE_SETTING,
1881                     null, 'quiz_report_' . $report, new pix_icon('i/item', '')));
1882         }
1883     }
1885     question_extend_settings_navigation($quiznode, $PAGE->cm->context)->trim_if_empty();
1888 /**
1889  * Serves the quiz files.
1890  *
1891  * @package  mod_quiz
1892  * @category files
1893  * @param stdClass $course course object
1894  * @param stdClass $cm course module object
1895  * @param stdClass $context context object
1896  * @param string $filearea file area
1897  * @param array $args extra arguments
1898  * @param bool $forcedownload whether or not force download
1899  * @param array $options additional options affecting the file serving
1900  * @return bool false if file not found, does not return if found - justsend the file
1901  */
1902 function quiz_pluginfile($course, $cm, $context, $filearea, $args, $forcedownload, array $options=array()) {
1903     global $CFG, $DB;
1905     if ($context->contextlevel != CONTEXT_MODULE) {
1906         return false;
1907     }
1909     require_login($course, false, $cm);
1911     if (!$quiz = $DB->get_record('quiz', array('id'=>$cm->instance))) {
1912         return false;
1913     }
1915     // The 'intro' area is served by pluginfile.php.
1916     $fileareas = array('feedback');
1917     if (!in_array($filearea, $fileareas)) {
1918         return false;
1919     }
1921     $feedbackid = (int)array_shift($args);
1922     if (!$feedback = $DB->get_record('quiz_feedback', array('id'=>$feedbackid))) {
1923         return false;
1924     }
1926     $fs = get_file_storage();
1927     $relativepath = implode('/', $args);
1928     $fullpath = "/$context->id/mod_quiz/$filearea/$feedbackid/$relativepath";
1929     if (!$file = $fs->get_file_by_hash(sha1($fullpath)) or $file->is_directory()) {
1930         return false;
1931     }
1932     send_stored_file($file, 0, 0, true, $options);
1935 /**
1936  * Called via pluginfile.php -> question_pluginfile to serve files belonging to
1937  * a question in a question_attempt when that attempt is a quiz attempt.
1938  *
1939  * @package  mod_quiz
1940  * @category files
1941  * @param stdClass $course course settings object
1942  * @param stdClass $context context object
1943  * @param string $component the name of the component we are serving files for.
1944  * @param string $filearea the name of the file area.
1945  * @param int $qubaid the attempt usage id.
1946  * @param int $slot the id of a question in this quiz attempt.
1947  * @param array $args the remaining bits of the file path.
1948  * @param bool $forcedownload whether the user must be forced to download the file.
1949  * @param array $options additional options affecting the file serving
1950  * @return bool false if file not found, does not return if found - justsend the file
1951  */
1952 function quiz_question_pluginfile($course, $context, $component,
1953         $filearea, $qubaid, $slot, $args, $forcedownload, array $options=array()) {
1954     global $CFG;
1955     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
1957     $attemptobj = quiz_attempt::create_from_usage_id($qubaid);
1958     require_login($attemptobj->get_course(), false, $attemptobj->get_cm());
1960     if ($attemptobj->is_own_attempt() && !$attemptobj->is_finished()) {
1961         // In the middle of an attempt.
1962         if (!$attemptobj->is_preview_user()) {
1963             $attemptobj->require_capability('mod/quiz:attempt');
1964         }
1965         $isreviewing = false;
1967     } else {
1968         // Reviewing an attempt.
1969         $attemptobj->check_review_capability();
1970         $isreviewing = true;
1971     }
1973     if (!$attemptobj->check_file_access($slot, $isreviewing, $context->id,
1974             $component, $filearea, $args, $forcedownload)) {
1975         send_file_not_found();
1976     }
1978     $fs = get_file_storage();
1979     $relativepath = implode('/', $args);
1980     $fullpath = "/$context->id/$component/$filearea/$relativepath";
1981     if (!$file = $fs->get_file_by_hash(sha1($fullpath)) or $file->is_directory()) {
1982         send_file_not_found();
1983     }
1985     send_stored_file($file, 0, 0, $forcedownload, $options);
1988 /**
1989  * Return a list of page types
1990  * @param string $pagetype current page type
1991  * @param stdClass $parentcontext Block's parent context
1992  * @param stdClass $currentcontext Current context of block
1993  */
1994 function quiz_page_type_list($pagetype, $parentcontext, $currentcontext) {
1995     $module_pagetype = array(
1996         'mod-quiz-*'       => get_string('page-mod-quiz-x', 'quiz'),
1997         'mod-quiz-view'    => get_string('page-mod-quiz-view', 'quiz'),
1998         'mod-quiz-attempt' => get_string('page-mod-quiz-attempt', 'quiz'),
1999         'mod-quiz-summary' => get_string('page-mod-quiz-summary', 'quiz'),
2000         'mod-quiz-review'  => get_string('page-mod-quiz-review', 'quiz'),
2001         'mod-quiz-edit'    => get_string('page-mod-quiz-edit', 'quiz'),
2002         'mod-quiz-report'  => get_string('page-mod-quiz-report', 'quiz'),
2003     );
2004     return $module_pagetype;
2007 /**
2008  * @return the options for quiz navigation.
2009  */
2010 function quiz_get_navigation_options() {
2011     return array(
2012         QUIZ_NAVMETHOD_FREE => get_string('navmethod_free', 'quiz'),
2013         QUIZ_NAVMETHOD_SEQ  => get_string('navmethod_seq', 'quiz')
2014     );
2017 /**
2018  * Obtains the automatic completion state for this quiz on any conditions
2019  * in quiz settings, such as if all attempts are used or a certain grade is achieved.
2020  *
2021  * @param object $course Course
2022  * @param object $cm Course-module
2023  * @param int $userid User ID
2024  * @param bool $type Type of comparison (or/and; can be used as return value if no conditions)
2025  * @return bool True if completed, false if not. (If no conditions, then return
2026  *   value depends on comparison type)
2027  */
2028 function quiz_get_completion_state($course, $cm, $userid, $type) {
2029     global $DB;
2030     global $CFG;
2032     $quiz = $DB->get_record('quiz', array('id' => $cm->instance), '*', MUST_EXIST);
2033     if (!$quiz->completionattemptsexhausted && !$quiz->completionpass) {
2034         return $type;
2035     }
2037     // Check if the user has used up all attempts.
2038     if ($quiz->completionattemptsexhausted) {
2039         $attempts = quiz_get_user_attempts($quiz->id, $userid, 'finished', true);
2040         if ($attempts) {
2041             $lastfinishedattempt = end($attempts);
2042             $context = context_module::instance($cm->id);
2043             $quizobj = quiz::create($quiz->id, $userid);
2044             $accessmanager = new quiz_access_manager($quizobj, time(),
2045                     has_capability('mod/quiz:ignoretimelimits', $context, $userid, false));
2046             if ($accessmanager->is_finished(count($attempts), $lastfinishedattempt)) {
2047                 return true;
2048             }
2049         }
2050     }
2052     // Check for passing grade.
2053     if ($quiz->completionpass) {
2054         require_once($CFG->libdir . '/gradelib.php');
2055         $item = grade_item::fetch(array('courseid' => $course->id, 'itemtype' => 'mod',
2056                 'itemmodule' => 'quiz', 'iteminstance' => $cm->instance, 'outcomeid' => null));
2057         if ($item) {
2058             $grades = grade_grade::fetch_users_grades($item, array($userid), false);
2059             if (!empty($grades[$userid])) {
2060                 return $grades[$userid]->is_passed($item);
2061             }
2062         }
2063     }
2064     return false;
2067 /**
2068  * Check if the module has any update that affects the current user since a given time.
2069  *
2070  * @param  cm_info $cm course module data
2071  * @param  int $from the time to check updates from
2072  * @param  array $filter  if we need to check only specific updates
2073  * @return stdClass an object with the different type of areas indicating if they were updated or not
2074  * @since Moodle 3.2
2075  */
2076 function quiz_check_updates_since(cm_info $cm, $from, $filter = array()) {
2077     global $DB, $USER, $CFG;
2078     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
2080     $updates = course_check_module_updates_since($cm, $from, array(), $filter);
2082     // Check if questions were updated.
2083     $updates->questions = (object) array('updated' => false);
2084     $quizobj = quiz::create($cm->instance, $USER->id);
2085     $quizobj->preload_questions();
2086     $quizobj->load_questions();
2087     $questionids = array_keys($quizobj->get_questions());
2088     if (!empty($questionids)) {
2089         list($questionsql, $params) = $DB->get_in_or_equal($questionids, SQL_PARAMS_NAMED);
2090         $select = 'id ' . $questionsql . ' AND (timemodified > :time1 OR timecreated > :time2)';
2091         $params['time1'] = $from;
2092         $params['time2'] = $from;
2093         $questions = $DB->get_records_select('question', $select, $params, '', 'id');
2094         if (!empty($questions)) {
2095             $updates->questions->updated = true;
2096             $updates->questions->itemids = array_keys($questions);
2097         }
2098     }
2100     // Check for new attempts or grades.
2101     $updates->attempts = (object) array('updated' => false);
2102     $updates->grades = (object) array('updated' => false);
2103     $select = 'quiz = ? AND userid = ? AND timemodified > ?';
2104     $params = array($cm->instance, $USER->id, $from);
2106     $attempts = $DB->get_records_select('quiz_attempts', $select, $params, '', 'id');
2107     if (!empty($attempts)) {
2108         $updates->attempts->updated = true;
2109         $updates->attempts->itemids = array_keys($attempts);
2110     }
2111     $grades = $DB->get_records_select('quiz_grades', $select, $params, '', 'id');
2112     if (!empty($grades)) {
2113         $updates->grades->updated = true;
2114         $updates->grades->itemids = array_keys($grades);
2115     }
2117     // Now, teachers should see other students updates.
2118     if (has_capability('mod/quiz:viewreports', $cm->context)) {
2119         $select = 'quiz = ? AND timemodified > ?';
2120         $params = array($cm->instance, $from);
2122         if (groups_get_activity_groupmode($cm) == SEPARATEGROUPS) {
2123             $groupusers = array_keys(groups_get_activity_shared_group_members($cm));
2124             if (empty($groupusers)) {
2125                 return $updates;
2126             }
2127             list($insql, $inparams) = $DB->get_in_or_equal($groupusers);
2128             $select .= ' AND userid ' . $insql;
2129             $params = array_merge($params, $inparams);
2130         }
2132         $updates->userattempts = (object) array('updated' => false);
2133         $attempts = $DB->get_records_select('quiz_attempts', $select, $params, '', 'id');
2134         if (!empty($attempts)) {
2135             $updates->userattempts->updated = true;
2136             $updates->userattempts->itemids = array_keys($attempts);
2137         }
2139         $updates->usergrades = (object) array('updated' => false);
2140         $grades = $DB->get_records_select('quiz_grades', $select, $params, '', 'id');
2141         if (!empty($grades)) {
2142             $updates->usergrades->updated = true;
2143             $updates->usergrades->itemids = array_keys($grades);
2144         }
2145     }
2146     return $updates;
2149 /**
2150  * Get icon mapping for font-awesome.
2151  */
2152 function mod_quiz_get_fontawesome_icon_map() {
2153     return [
2154         'mod_quiz:navflagged' => 'fa-flag',
2155     ];
2158 /**
2159  * This function receives a calendar event and returns the action associated with it, or null if there is none.
2160  *
2161  * This is used by block_myoverview in order to display the event appropriately. If null is returned then the event
2162  * is not displayed on the block.
2163  *
2164  * @param calendar_event $event
2165  * @param \core_calendar\action_factory $factory
2166  * @return \core_calendar\local\event\entities\action_interface|null
2167  */
2168 function mod_quiz_core_calendar_provide_event_action(calendar_event $event,
2169                                                      \core_calendar\action_factory $factory) {
2170     global $CFG, $USER;
2172     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
2174     $cm = get_fast_modinfo($event->courseid)->instances['quiz'][$event->instance];
2175     $quizobj = quiz::create($cm->instance, $USER->id);
2176     $quiz = $quizobj->get_quiz();
2178     // Check they have capabilities allowing them to view the quiz.
2179     if (!has_any_capability(array('mod/quiz:reviewmyattempts', 'mod/quiz:attempt'), $quizobj->get_context())) {
2180         return null;
2181     }
2183     quiz_update_effective_access($quiz, $USER->id);
2185     // Check if quiz is closed, if so don't display it.
2186     if (!empty($quiz->timeclose) && $quiz->timeclose <= time()) {
2187         return null;
2188     }
2190     $attempts = quiz_get_user_attempts($quizobj->get_quizid(), $USER->id);
2191     if (!empty($attempts)) {
2192         // The student's last attempt is finished.
2193         return null;
2194     }
2196     $name = get_string('attemptquiznow', 'quiz');
2197     $url = new \moodle_url('/mod/quiz/view.php', [
2198         'id' => $cm->id
2199     ]);
2200     $itemcount = 1;
2201     $actionable = true;
2203     // Check if the quiz is not currently actionable.
2204     if (!empty($quiz->timeopen) && $quiz->timeopen > time()) {
2205         $actionable = false;
2206     }
2208     return $factory->create_instance(
2209         $name,
2210         $url,
2211         $itemcount,
2212         $actionable
2213     );
2216 /**
2217  * Add a get_coursemodule_info function in case any quiz type wants to add 'extra' information
2218  * for the course (see resource).
2219  *
2220  * Given a course_module object, this function returns any "extra" information that may be needed
2221  * when printing this activity in a course listing.  See get_array_of_activities() in course/lib.php.
2222  *
2223  * @param stdClass $coursemodule The coursemodule object (record).
2224  * @return cached_cm_info An object on information that the courses
2225  *                        will know about (most noticeably, an icon).
2226  */
2227 function quiz_get_coursemodule_info($coursemodule) {
2228     global $DB;
2230     $dbparams = ['id' => $coursemodule->instance];
2231     $fields = 'id, name, intro, introformat, completionattemptsexhausted, completionpass';
2232     if (!$quiz = $DB->get_record('quiz', $dbparams, $fields)) {
2233         return false;
2234     }
2236     $result = new cached_cm_info();
2237     $result->name = $quiz->name;
2239     if ($coursemodule->showdescription) {
2240         // Convert intro to html. Do not filter cached version, filters run at display time.
2241         $result->content = format_module_intro('quiz', $quiz, $coursemodule->id, false);
2242     }
2244     // Populate the custom completion rules as key => value pairs, but only if the completion mode is 'automatic'.
2245     if ($coursemodule->completion == COMPLETION_TRACKING_AUTOMATIC) {
2246         $result->customdata['customcompletionrules']['completionattemptsexhausted'] = $quiz->completionattemptsexhausted;
2247         $result->customdata['customcompletionrules']['completionpass'] = $quiz->completionpass;
2248     }
2250     return $result;
2253 /**
2254  * Callback which returns human-readable strings describing the active completion custom rules for the module instance.
2255  *
2256  * @param cm_info|stdClass $cm object with fields ->completion and ->customdata['customcompletionrules']
2257  * @return array $descriptions the array of descriptions for the custom rules.
2258  */
2259 function mod_quiz_get_completion_active_rule_descriptions($cm) {
2260     // Values will be present in cm_info, and we assume these are up to date.
2261     if (empty($cm->customdata['customcompletionrules'])
2262         || $cm->completion != COMPLETION_TRACKING_AUTOMATIC) {
2263         return [];
2264     }
2266     $descriptions = [];
2267     foreach ($cm->customdata['customcompletionrules'] as $key => $val) {
2268         switch ($key) {
2269             case 'completionattemptsexhausted':
2270                 if (empty($val)) {
2271                     continue;
2272                 }
2273                 $descriptions[] = get_string('completionattemptsexhausteddesc', 'quiz');
2274                 break;
2275             case 'completionpass':
2276                 if (empty($val)) {
2277                     continue;
2278                 }
2279                 $descriptions[] = get_string('completionpassdesc', 'quiz', format_time($val));
2280                 break;
2281             default:
2282                 break;
2283         }
2284     }
2285     return $descriptions;
2288 /**
2289  * Returns the min and max values for the timestart property of a quiz
2290  * activity event.
2291  *
2292  * The min and max values will be the timeopen and timeclose properties
2293  * of the quiz, respectively, if they are set.
2294  *
2295  * If either value isn't set then null will be returned instead to
2296  * indicate that there is no cutoff for that value.
2297  *
2298  * If the vent has no valid timestart range then [false, false] will
2299  * be returned. This is the case for overriden events.
2300  *
2301  * A minimum and maximum cutoff return value will look like:
2302  * [
2303  *     [1505704373, 'The date must be after this date'],
2304  *     [1506741172, 'The date must be before this date']
2305  * ]
2306  *
2307  * @throws \moodle_exception
2308  * @param \calendar_event $event The calendar event to get the time range for
2309  * @param stdClass $quiz The module instance to get the range from
2310  * @return array
2311  */
2312 function mod_quiz_core_calendar_get_valid_event_timestart_range(\calendar_event $event, \stdClass $quiz) {
2313     global $CFG, $DB;
2314     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
2316     // Overrides do not have a valid timestart range.
2317     if (quiz_is_overriden_calendar_event($event)) {
2318         return [false, false];
2319     }
2321     $mindate = null;
2322     $maxdate = null;
2324     if ($event->eventtype == QUIZ_EVENT_TYPE_OPEN) {
2325         if (!empty($quiz->timeclose)) {
2326             $maxdate = [
2327                 $quiz->timeclose,
2328                 get_string('openafterclose', 'quiz')
2329             ];
2330         }
2331     } else if ($event->eventtype == QUIZ_EVENT_TYPE_CLOSE) {
2332         if (!empty($quiz->timeopen)) {
2333             $mindate = [
2334                 $quiz->timeopen,
2335                 get_string('closebeforeopen', 'quiz')
2336             ];
2337         }
2338     }
2340     return [$mindate, $maxdate];
2343 /**
2344  * This function will update the quiz module according to the
2345  * event that has been modified.
2346  *
2347  * It will set the timeopen or timeclose value of the quiz instance
2348  * according to the type of event provided.
2349  *
2350  * @throws \moodle_exception
2351  * @param \calendar_event $event A quiz activity calendar event
2352  * @param \stdClass $quiz A quiz activity instance
2353  */
2354 function mod_quiz_core_calendar_event_timestart_updated(\calendar_event $event, \stdClass $quiz) {
2355     global $CFG, $DB;
2356     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
2358     if (!in_array($event->eventtype, [QUIZ_EVENT_TYPE_OPEN, QUIZ_EVENT_TYPE_CLOSE])) {
2359         // This isn't an event that we care about so we can ignore it.
2360         return;
2361     }
2363     $courseid = $event->courseid;
2364     $modulename = $event->modulename;
2365     $instanceid = $event->instance;
2366     $modified = false;
2367     $closedatechanged = false;
2369     // Something weird going on. The event is for a different module so
2370     // we should ignore it.
2371     if ($modulename != 'quiz') {
2372         return;
2373     }
2375     if ($quiz->id != $instanceid) {
2376         // The provided quiz instance doesn't match the event so
2377         // there is nothing to do here.
2378         return;
2379     }
2381     // We don't update the activity if it's an override event that has
2382     // been modified.
2383     if (quiz_is_overriden_calendar_event($event)) {
2384         return;
2385     }
2387     $coursemodule = get_fast_modinfo($courseid)->instances[$modulename][$instanceid];
2388     $context = context_module::instance($coursemodule->id);
2390     // The user does not have the capability to modify this activity.
2391     if (!has_capability('moodle/course:manageactivities', $context)) {
2392         return;
2393     }
2395     if ($event->eventtype == QUIZ_EVENT_TYPE_OPEN) {
2396         // If the event is for the quiz activity opening then we should
2397         // set the start time of the quiz activity to be the new start
2398         // time of the event.
2399         if ($quiz->timeopen != $event->timestart) {
2400             $quiz->timeopen = $event->timestart;
2401             $modified = true;
2402         }
2403     } else if ($event->eventtype == QUIZ_EVENT_TYPE_CLOSE) {
2404         // If the event is for the quiz activity closing then we should
2405         // set the end time of the quiz activity to be the new start
2406         // time of the event.
2407         if ($quiz->timeclose != $event->timestart) {
2408             $quiz->timeclose = $event->timestart;
2409             $modified = true;
2410             $closedatechanged = true;
2411         }
2412     }
2414     if ($modified) {
2415         $quiz->timemodified = time();
2416         $DB->update_record('quiz', $quiz);
2418         if ($closedatechanged) {
2419             quiz_update_open_attempts(array('quizid' => $quiz->id));
2420         }
2422         // Delete any previous preview attempts.
2423         quiz_delete_previews($quiz);
2424         quiz_update_events($quiz);
2425         $event = \core\event\course_module_updated::create_from_cm($coursemodule, $context);
2426         $event->trigger();
2427     }
2430 /**
2431  * Generates the question bank in a fragment output. This allows
2432  * the question bank to be displayed in a modal.
2433  *
2434  * The only expected argument provided in the $args array is
2435  * 'querystring'. The value should be the list of parameters
2436  * URL encoded and used to build the question bank page.
2437  *
2438  * The individual list of parameters expected can be found in
2439  * question_build_edit_resources.
2440  *
2441  * @param array $args The fragment arguments.
2442  * @return string The rendered mform fragment.
2443  */
2444 function mod_quiz_output_fragment_quiz_question_bank($args) {
2445     global $CFG, $DB, $PAGE;
2446     require_once($CFG->dirroot . '/mod/quiz/locallib.php');
2447     require_once($CFG->dirroot . '/question/editlib.php');
2449     $querystring = preg_replace('/^\?/', '', $args['querystring']);
2450     $params = [];
2451     parse_str($querystring, $params);
2453     // Build the required resources. The $params are all cleaned as
2454     // part of this process.
2455     list($thispageurl, $contexts, $cmid, $cm, $quiz, $pagevars) =
2456             question_build_edit_resources('editq', '/mod/quiz/edit.php', $params);
2458     // Get the course object and related bits.
2459     $course = $DB->get_record('course', array('id' => $quiz->course), '*', MUST_EXIST);
2460     require_capability('mod/quiz:manage', $contexts->lowest());
2462     // Create quiz question bank view.
2463     $questionbank = new mod_quiz\question\bank\custom_view($contexts, $thispageurl, $course, $cm, $quiz);
2464     $questionbank->set_quiz_has_attempts(quiz_has_attempts($quiz->id));
2466     // Output.
2467     $renderer = $PAGE->get_renderer('mod_quiz', 'edit');
2468     return $renderer->question_bank_contents($questionbank, $pagevars);
2471 /**
2472  * Generates the add random question in a fragment output. This allows the
2473  * form to be rendered in javascript, for example inside a modal.
2474  *
2475  * The required arguments as keys in the $args array are:
2476  *      cat {string} The category and category context ids comma separated.
2477  *      addonpage {int} The page id to add this question to.
2478  *      returnurl {string} URL to return to after form submission.
2479  *      cmid {int} The course module id the questions are being added to.
2480  *
2481  * @param array $args The fragment arguments.
2482  * @return string The rendered mform fragment.
2483  */
2484 function mod_quiz_output_fragment_add_random_question_form($args) {
2485     global $CFG;
2486     require_once($CFG->dirroot . '/mod/quiz/addrandomform.php');
2488     $contexts = new \question_edit_contexts($args['context']);
2489     $formoptions = [
2490         'contexts' => $contexts,
2491         'cat' => $args['cat']
2492     ];
2493     $formdata = [
2494         'category' => $args['cat'],
2495         'addonpage' => $args['addonpage'],
2496         'returnurl' => $args['returnurl'],
2497         'cmid' => $args['cmid']
2498     ];
2500     $form = new quiz_add_random_form(
2501         new \moodle_url('/mod/quiz/addrandom.php'),
2502         $formoptions,
2503         'post',
2504         '',
2505         null,
2506         true,
2507         $formdata
2508     );
2509     $form->set_data($formdata);
2511     return $form->render();