Merge branch 'wip-MDL-55826-master' of git://github.com/marinaglancy/moodle
[moodle.git] / mod / quiz / locallib.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 used by the quiz module.
19  *
20  * This contains functions that are called from within the quiz module only
21  * Functions that are also called by core Moodle are in {@link lib.php}
22  * This script also loads the code in {@link questionlib.php} which holds
23  * the module-indpendent code for handling questions and which in turn
24  * initialises all the questiontype classes.
25  *
26  * @package    mod_quiz
27  * @copyright  1999 onwards Martin Dougiamas and others {@link http://moodle.com}
28  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
29  */
32 defined('MOODLE_INTERNAL') || die();
34 require_once($CFG->dirroot . '/mod/quiz/lib.php');
35 require_once($CFG->dirroot . '/mod/quiz/accessmanager.php');
36 require_once($CFG->dirroot . '/mod/quiz/accessmanager_form.php');
37 require_once($CFG->dirroot . '/mod/quiz/renderer.php');
38 require_once($CFG->dirroot . '/mod/quiz/attemptlib.php');
39 require_once($CFG->libdir . '/completionlib.php');
40 require_once($CFG->libdir . '/eventslib.php');
41 require_once($CFG->libdir . '/filelib.php');
42 require_once($CFG->libdir . '/questionlib.php');
45 /**
46  * @var int We show the countdown timer if there is less than this amount of time left before the
47  * the quiz close date. (1 hour)
48  */
49 define('QUIZ_SHOW_TIME_BEFORE_DEADLINE', '3600');
51 /**
52  * @var int If there are fewer than this many seconds left when the student submits
53  * a page of the quiz, then do not take them to the next page of the quiz. Instead
54  * close the quiz immediately.
55  */
56 define('QUIZ_MIN_TIME_TO_CONTINUE', '2');
58 /**
59  * @var int We show no image when user selects No image from dropdown menu in quiz settings.
60  */
61 define('QUIZ_SHOWIMAGE_NONE', 0);
63 /**
64  * @var int We show small image when user selects small image from dropdown menu in quiz settings.
65  */
66 define('QUIZ_SHOWIMAGE_SMALL', 1);
68 /**
69  * @var int We show Large image when user selects Large image from dropdown menu in quiz settings.
70  */
71 define('QUIZ_SHOWIMAGE_LARGE', 2);
74 // Functions related to attempts ///////////////////////////////////////////////
76 /**
77  * Creates an object to represent a new attempt at a quiz
78  *
79  * Creates an attempt object to represent an attempt at the quiz by the current
80  * user starting at the current time. The ->id field is not set. The object is
81  * NOT written to the database.
82  *
83  * @param object $quizobj the quiz object to create an attempt for.
84  * @param int $attemptnumber the sequence number for the attempt.
85  * @param object $lastattempt the previous attempt by this user, if any. Only needed
86  *         if $attemptnumber > 1 and $quiz->attemptonlast is true.
87  * @param int $timenow the time the attempt was started at.
88  * @param bool $ispreview whether this new attempt is a preview.
89  * @param int $userid  the id of the user attempting this quiz.
90  *
91  * @return object the newly created attempt object.
92  */
93 function quiz_create_attempt(quiz $quizobj, $attemptnumber, $lastattempt, $timenow, $ispreview = false, $userid = null) {
94     global $USER;
96     if ($userid === null) {
97         $userid = $USER->id;
98     }
100     $quiz = $quizobj->get_quiz();
101     if ($quiz->sumgrades < 0.000005 && $quiz->grade > 0.000005) {
102         throw new moodle_exception('cannotstartgradesmismatch', 'quiz',
103                 new moodle_url('/mod/quiz/view.php', array('q' => $quiz->id)),
104                     array('grade' => quiz_format_grade($quiz, $quiz->grade)));
105     }
107     if ($attemptnumber == 1 || !$quiz->attemptonlast) {
108         // We are not building on last attempt so create a new attempt.
109         $attempt = new stdClass();
110         $attempt->quiz = $quiz->id;
111         $attempt->userid = $userid;
112         $attempt->preview = 0;
113         $attempt->layout = '';
114     } else {
115         // Build on last attempt.
116         if (empty($lastattempt)) {
117             print_error('cannotfindprevattempt', 'quiz');
118         }
119         $attempt = $lastattempt;
120     }
122     $attempt->attempt = $attemptnumber;
123     $attempt->timestart = $timenow;
124     $attempt->timefinish = 0;
125     $attempt->timemodified = $timenow;
126     $attempt->state = quiz_attempt::IN_PROGRESS;
127     $attempt->currentpage = 0;
128     $attempt->sumgrades = null;
130     // If this is a preview, mark it as such.
131     if ($ispreview) {
132         $attempt->preview = 1;
133     }
135     $timeclose = $quizobj->get_access_manager($timenow)->get_end_time($attempt);
136     if ($timeclose === false || $ispreview) {
137         $attempt->timecheckstate = null;
138     } else {
139         $attempt->timecheckstate = $timeclose;
140     }
142     return $attempt;
144 /**
145  * Start a normal, new, quiz attempt.
146  *
147  * @param quiz      $quizobj            the quiz object to start an attempt for.
148  * @param question_usage_by_activity $quba
149  * @param object    $attempt
150  * @param integer   $attemptnumber      starting from 1
151  * @param integer   $timenow            the attempt start time
152  * @param array     $questionids        slot number => question id. Used for random questions, to force the choice
153  *                                        of a particular actual question. Intended for testing purposes only.
154  * @param array     $forcedvariantsbyslot slot number => variant. Used for questions with variants,
155  *                                          to force the choice of a particular variant. Intended for testing
156  *                                          purposes only.
157  * @throws moodle_exception
158  * @return object   modified attempt object
159  */
160 function quiz_start_new_attempt($quizobj, $quba, $attempt, $attemptnumber, $timenow,
161                                 $questionids = array(), $forcedvariantsbyslot = array()) {
163     // Usages for this user's previous quiz attempts.
164     $qubaids = new \mod_quiz\question\qubaids_for_users_attempts(
165             $quizobj->get_quizid(), $attempt->userid);
167     // Fully load all the questions in this quiz.
168     $quizobj->preload_questions();
169     $quizobj->load_questions();
171     // First load all the non-random questions.
172     $randomfound = false;
173     $slot = 0;
174     $questions = array();
175     $maxmark = array();
176     $page = array();
177     foreach ($quizobj->get_questions() as $questiondata) {
178         $slot += 1;
179         $maxmark[$slot] = $questiondata->maxmark;
180         $page[$slot] = $questiondata->page;
181         if ($questiondata->qtype == 'random') {
182             $randomfound = true;
183             continue;
184         }
185         if (!$quizobj->get_quiz()->shuffleanswers) {
186             $questiondata->options->shuffleanswers = false;
187         }
188         $questions[$slot] = question_bank::make_question($questiondata);
189     }
191     // Then find a question to go in place of each random question.
192     if ($randomfound) {
193         $slot = 0;
194         $usedquestionids = array();
195         foreach ($questions as $question) {
196             if (isset($usedquestions[$question->id])) {
197                 $usedquestionids[$question->id] += 1;
198             } else {
199                 $usedquestionids[$question->id] = 1;
200             }
201         }
202         $randomloader = new \core_question\bank\random_question_loader($qubaids, $usedquestionids);
204         foreach ($quizobj->get_questions() as $questiondata) {
205             $slot += 1;
206             if ($questiondata->qtype != 'random') {
207                 continue;
208             }
210             // Deal with fixed random choices for testing.
211             if (isset($questionids[$quba->next_slot_number()])) {
212                 if ($randomloader->is_question_available($questiondata->category,
213                         (bool) $questiondata->questiontext, $questionids[$quba->next_slot_number()])) {
214                     $questions[$slot] = question_bank::load_question(
215                             $questionids[$quba->next_slot_number()], $quizobj->get_quiz()->shuffleanswers);
216                     continue;
217                 } else {
218                     throw new coding_exception('Forced question id not available.');
219                 }
220             }
222             // Normal case, pick one at random.
223             $questionid = $randomloader->get_next_question_id($questiondata->category,
224                         (bool) $questiondata->questiontext);
225             if ($questionid === null) {
226                 throw new moodle_exception('notenoughrandomquestions', 'quiz',
227                                            $quizobj->view_url(), $questiondata);
228             }
230             $questions[$slot] = question_bank::load_question($questionid,
231                     $quizobj->get_quiz()->shuffleanswers);
232         }
233     }
235     // Finally add them all to the usage.
236     ksort($questions);
237     foreach ($questions as $slot => $question) {
238         $newslot = $quba->add_question($question, $maxmark[$slot]);
239         if ($newslot != $slot) {
240             throw new coding_exception('Slot numbers have got confused.');
241         }
242     }
244     // Start all the questions.
245     $variantstrategy = new core_question\engine\variants\least_used_strategy($quba, $qubaids);
247     if (!empty($forcedvariantsbyslot)) {
248         $forcedvariantsbyseed = question_variant_forced_choices_selection_strategy::prepare_forced_choices_array(
249             $forcedvariantsbyslot, $quba);
250         $variantstrategy = new question_variant_forced_choices_selection_strategy(
251             $forcedvariantsbyseed, $variantstrategy);
252     }
254     $quba->start_all_questions($variantstrategy, $timenow);
256     // Work out the attempt layout.
257     $sections = $quizobj->get_sections();
258     foreach ($sections as $i => $section) {
259         if (isset($sections[$i + 1])) {
260             $sections[$i]->lastslot = $sections[$i + 1]->firstslot - 1;
261         } else {
262             $sections[$i]->lastslot = count($questions);
263         }
264     }
266     $layout = array();
267     foreach ($sections as $section) {
268         if ($section->shufflequestions) {
269             $questionsinthissection = array();
270             for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
271                 $questionsinthissection[] = $slot;
272             }
273             shuffle($questionsinthissection);
274             $questionsonthispage = 0;
275             foreach ($questionsinthissection as $slot) {
276                 if ($questionsonthispage && $questionsonthispage == $quizobj->get_quiz()->questionsperpage) {
277                     $layout[] = 0;
278                     $questionsonthispage = 0;
279                 }
280                 $layout[] = $slot;
281                 $questionsonthispage += 1;
282             }
284         } else {
285             $currentpage = $page[$section->firstslot];
286             for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
287                 if ($currentpage !== null && $page[$slot] != $currentpage) {
288                     $layout[] = 0;
289                 }
290                 $layout[] = $slot;
291                 $currentpage = $page[$slot];
292             }
293         }
295         // Each section ends with a page break.
296         $layout[] = 0;
297     }
298     $attempt->layout = implode(',', $layout);
300     return $attempt;
303 /**
304  * Start a subsequent new attempt, in each attempt builds on last mode.
305  *
306  * @param question_usage_by_activity    $quba         this question usage
307  * @param object                        $attempt      this attempt
308  * @param object                        $lastattempt  last attempt
309  * @return object                       modified attempt object
310  *
311  */
312 function quiz_start_attempt_built_on_last($quba, $attempt, $lastattempt) {
313     $oldquba = question_engine::load_questions_usage_by_activity($lastattempt->uniqueid);
315     $oldnumberstonew = array();
316     foreach ($oldquba->get_attempt_iterator() as $oldslot => $oldqa) {
317         $newslot = $quba->add_question($oldqa->get_question(), $oldqa->get_max_mark());
319         $quba->start_question_based_on($newslot, $oldqa);
321         $oldnumberstonew[$oldslot] = $newslot;
322     }
324     // Update attempt layout.
325     $newlayout = array();
326     foreach (explode(',', $lastattempt->layout) as $oldslot) {
327         if ($oldslot != 0) {
328             $newlayout[] = $oldnumberstonew[$oldslot];
329         } else {
330             $newlayout[] = 0;
331         }
332     }
333     $attempt->layout = implode(',', $newlayout);
334     return $attempt;
337 /**
338  * The save started question usage and quiz attempt in db and log the started attempt.
339  *
340  * @param quiz                       $quizobj
341  * @param question_usage_by_activity $quba
342  * @param object                     $attempt
343  * @return object                    attempt object with uniqueid and id set.
344  */
345 function quiz_attempt_save_started($quizobj, $quba, $attempt) {
346     global $DB;
347     // Save the attempt in the database.
348     question_engine::save_questions_usage_by_activity($quba);
349     $attempt->uniqueid = $quba->get_id();
350     $attempt->id = $DB->insert_record('quiz_attempts', $attempt);
352     // Params used by the events below.
353     $params = array(
354         'objectid' => $attempt->id,
355         'relateduserid' => $attempt->userid,
356         'courseid' => $quizobj->get_courseid(),
357         'context' => $quizobj->get_context()
358     );
359     // Decide which event we are using.
360     if ($attempt->preview) {
361         $params['other'] = array(
362             'quizid' => $quizobj->get_quizid()
363         );
364         $event = \mod_quiz\event\attempt_preview_started::create($params);
365     } else {
366         $event = \mod_quiz\event\attempt_started::create($params);
368     }
370     // Trigger the event.
371     $event->add_record_snapshot('quiz', $quizobj->get_quiz());
372     $event->add_record_snapshot('quiz_attempts', $attempt);
373     $event->trigger();
375     return $attempt;
378 /**
379  * Returns an unfinished attempt (if there is one) for the given
380  * user on the given quiz. This function does not return preview attempts.
381  *
382  * @param int $quizid the id of the quiz.
383  * @param int $userid the id of the user.
384  *
385  * @return mixed the unfinished attempt if there is one, false if not.
386  */
387 function quiz_get_user_attempt_unfinished($quizid, $userid) {
388     $attempts = quiz_get_user_attempts($quizid, $userid, 'unfinished', true);
389     if ($attempts) {
390         return array_shift($attempts);
391     } else {
392         return false;
393     }
396 /**
397  * Delete a quiz attempt.
398  * @param mixed $attempt an integer attempt id or an attempt object
399  *      (row of the quiz_attempts table).
400  * @param object $quiz the quiz object.
401  */
402 function quiz_delete_attempt($attempt, $quiz) {
403     global $DB;
404     if (is_numeric($attempt)) {
405         if (!$attempt = $DB->get_record('quiz_attempts', array('id' => $attempt))) {
406             return;
407         }
408     }
410     if ($attempt->quiz != $quiz->id) {
411         debugging("Trying to delete attempt $attempt->id which belongs to quiz $attempt->quiz " .
412                 "but was passed quiz $quiz->id.");
413         return;
414     }
416     if (!isset($quiz->cmid)) {
417         $cm = get_coursemodule_from_instance('quiz', $quiz->id, $quiz->course);
418         $quiz->cmid = $cm->id;
419     }
421     question_engine::delete_questions_usage_by_activity($attempt->uniqueid);
422     $DB->delete_records('quiz_attempts', array('id' => $attempt->id));
424     // Log the deletion of the attempt if not a preview.
425     if (!$attempt->preview) {
426         $params = array(
427             'objectid' => $attempt->id,
428             'relateduserid' => $attempt->userid,
429             'context' => context_module::instance($quiz->cmid),
430             'other' => array(
431                 'quizid' => $quiz->id
432             )
433         );
434         $event = \mod_quiz\event\attempt_deleted::create($params);
435         $event->add_record_snapshot('quiz_attempts', $attempt);
436         $event->trigger();
437     }
439     // Search quiz_attempts for other instances by this user.
440     // If none, then delete record for this quiz, this user from quiz_grades
441     // else recalculate best grade.
442     $userid = $attempt->userid;
443     if (!$DB->record_exists('quiz_attempts', array('userid' => $userid, 'quiz' => $quiz->id))) {
444         $DB->delete_records('quiz_grades', array('userid' => $userid, 'quiz' => $quiz->id));
445     } else {
446         quiz_save_best_grade($quiz, $userid);
447     }
449     quiz_update_grades($quiz, $userid);
452 /**
453  * Delete all the preview attempts at a quiz, or possibly all the attempts belonging
454  * to one user.
455  * @param object $quiz the quiz object.
456  * @param int $userid (optional) if given, only delete the previews belonging to this user.
457  */
458 function quiz_delete_previews($quiz, $userid = null) {
459     global $DB;
460     $conditions = array('quiz' => $quiz->id, 'preview' => 1);
461     if (!empty($userid)) {
462         $conditions['userid'] = $userid;
463     }
464     $previewattempts = $DB->get_records('quiz_attempts', $conditions);
465     foreach ($previewattempts as $attempt) {
466         quiz_delete_attempt($attempt, $quiz);
467     }
470 /**
471  * @param int $quizid The quiz id.
472  * @return bool whether this quiz has any (non-preview) attempts.
473  */
474 function quiz_has_attempts($quizid) {
475     global $DB;
476     return $DB->record_exists('quiz_attempts', array('quiz' => $quizid, 'preview' => 0));
479 // Functions to do with quiz layout and pages //////////////////////////////////
481 /**
482  * Repaginate the questions in a quiz
483  * @param int $quizid the id of the quiz to repaginate.
484  * @param int $slotsperpage number of items to put on each page. 0 means unlimited.
485  */
486 function quiz_repaginate_questions($quizid, $slotsperpage) {
487     global $DB;
488     $trans = $DB->start_delegated_transaction();
490     $sections = $DB->get_records('quiz_sections', array('quizid' => $quizid), 'firstslot ASC');
491     $firstslots = array();
492     foreach ($sections as $section) {
493         if ((int)$section->firstslot === 1) {
494             continue;
495         }
496         $firstslots[] = $section->firstslot;
497     }
499     $slots = $DB->get_records('quiz_slots', array('quizid' => $quizid),
500             'slot');
501     $currentpage = 1;
502     $slotsonthispage = 0;
503     foreach ($slots as $slot) {
504         if (($firstslots && in_array($slot->slot, $firstslots)) ||
505             ($slotsonthispage && $slotsonthispage == $slotsperpage)) {
506             $currentpage += 1;
507             $slotsonthispage = 0;
508         }
509         if ($slot->page != $currentpage) {
510             $DB->set_field('quiz_slots', 'page', $currentpage, array('id' => $slot->id));
511         }
512         $slotsonthispage += 1;
513     }
515     $trans->allow_commit();
518 // Functions to do with quiz grades ////////////////////////////////////////////
520 /**
521  * Convert the raw grade stored in $attempt into a grade out of the maximum
522  * grade for this quiz.
523  *
524  * @param float $rawgrade the unadjusted grade, fof example $attempt->sumgrades
525  * @param object $quiz the quiz object. Only the fields grade, sumgrades and decimalpoints are used.
526  * @param bool|string $format whether to format the results for display
527  *      or 'question' to format a question grade (different number of decimal places.
528  * @return float|string the rescaled grade, or null/the lang string 'notyetgraded'
529  *      if the $grade is null.
530  */
531 function quiz_rescale_grade($rawgrade, $quiz, $format = true) {
532     if (is_null($rawgrade)) {
533         $grade = null;
534     } else if ($quiz->sumgrades >= 0.000005) {
535         $grade = $rawgrade * $quiz->grade / $quiz->sumgrades;
536     } else {
537         $grade = 0;
538     }
539     if ($format === 'question') {
540         $grade = quiz_format_question_grade($quiz, $grade);
541     } else if ($format) {
542         $grade = quiz_format_grade($quiz, $grade);
543     }
544     return $grade;
547 /**
548  * Get the feedback object for this grade on this quiz.
549  *
550  * @param float $grade a grade on this quiz.
551  * @param object $quiz the quiz settings.
552  * @return false|stdClass the record object or false if there is not feedback for the given grade
553  * @since  Moodle 3.1
554  */
555 function quiz_feedback_record_for_grade($grade, $quiz) {
556     global $DB;
558     // With CBM etc, it is possible to get -ve grades, which would then not match
559     // any feedback. Therefore, we replace -ve grades with 0.
560     $grade = max($grade, 0);
562     $feedback = $DB->get_record_select('quiz_feedback',
563             'quizid = ? AND mingrade <= ? AND ? < maxgrade', array($quiz->id, $grade, $grade));
565     return $feedback;
568 /**
569  * Get the feedback text that should be show to a student who
570  * got this grade on this quiz. The feedback is processed ready for diplay.
571  *
572  * @param float $grade a grade on this quiz.
573  * @param object $quiz the quiz settings.
574  * @param object $context the quiz context.
575  * @return string the comment that corresponds to this grade (empty string if there is not one.
576  */
577 function quiz_feedback_for_grade($grade, $quiz, $context) {
579     if (is_null($grade)) {
580         return '';
581     }
583     $feedback = quiz_feedback_record_for_grade($grade, $quiz);
585     if (empty($feedback->feedbacktext)) {
586         return '';
587     }
589     // Clean the text, ready for display.
590     $formatoptions = new stdClass();
591     $formatoptions->noclean = true;
592     $feedbacktext = file_rewrite_pluginfile_urls($feedback->feedbacktext, 'pluginfile.php',
593             $context->id, 'mod_quiz', 'feedback', $feedback->id);
594     $feedbacktext = format_text($feedbacktext, $feedback->feedbacktextformat, $formatoptions);
596     return $feedbacktext;
599 /**
600  * @param object $quiz the quiz database row.
601  * @return bool Whether this quiz has any non-blank feedback text.
602  */
603 function quiz_has_feedback($quiz) {
604     global $DB;
605     static $cache = array();
606     if (!array_key_exists($quiz->id, $cache)) {
607         $cache[$quiz->id] = quiz_has_grades($quiz) &&
608                 $DB->record_exists_select('quiz_feedback', "quizid = ? AND " .
609                     $DB->sql_isnotempty('quiz_feedback', 'feedbacktext', false, true),
610                 array($quiz->id));
611     }
612     return $cache[$quiz->id];
615 /**
616  * Update the sumgrades field of the quiz. This needs to be called whenever
617  * the grading structure of the quiz is changed. For example if a question is
618  * added or removed, or a question weight is changed.
619  *
620  * You should call {@link quiz_delete_previews()} before you call this function.
621  *
622  * @param object $quiz a quiz.
623  */
624 function quiz_update_sumgrades($quiz) {
625     global $DB;
627     $sql = 'UPDATE {quiz}
628             SET sumgrades = COALESCE((
629                 SELECT SUM(maxmark)
630                 FROM {quiz_slots}
631                 WHERE quizid = {quiz}.id
632             ), 0)
633             WHERE id = ?';
634     $DB->execute($sql, array($quiz->id));
635     $quiz->sumgrades = $DB->get_field('quiz', 'sumgrades', array('id' => $quiz->id));
637     if ($quiz->sumgrades < 0.000005 && quiz_has_attempts($quiz->id)) {
638         // If the quiz has been attempted, and the sumgrades has been
639         // set to 0, then we must also set the maximum possible grade to 0, or
640         // we will get a divide by zero error.
641         quiz_set_grade(0, $quiz);
642     }
645 /**
646  * Update the sumgrades field of the attempts at a quiz.
647  *
648  * @param object $quiz a quiz.
649  */
650 function quiz_update_all_attempt_sumgrades($quiz) {
651     global $DB;
652     $dm = new question_engine_data_mapper();
653     $timenow = time();
655     $sql = "UPDATE {quiz_attempts}
656             SET
657                 timemodified = :timenow,
658                 sumgrades = (
659                     {$dm->sum_usage_marks_subquery('uniqueid')}
660                 )
661             WHERE quiz = :quizid AND state = :finishedstate";
662     $DB->execute($sql, array('timenow' => $timenow, 'quizid' => $quiz->id,
663             'finishedstate' => quiz_attempt::FINISHED));
666 /**
667  * The quiz grade is the maximum that student's results are marked out of. When it
668  * changes, the corresponding data in quiz_grades and quiz_feedback needs to be
669  * rescaled. After calling this function, you probably need to call
670  * quiz_update_all_attempt_sumgrades, quiz_update_all_final_grades and
671  * quiz_update_grades.
672  *
673  * @param float $newgrade the new maximum grade for the quiz.
674  * @param object $quiz the quiz we are updating. Passed by reference so its
675  *      grade field can be updated too.
676  * @return bool indicating success or failure.
677  */
678 function quiz_set_grade($newgrade, $quiz) {
679     global $DB;
680     // This is potentially expensive, so only do it if necessary.
681     if (abs($quiz->grade - $newgrade) < 1e-7) {
682         // Nothing to do.
683         return true;
684     }
686     $oldgrade = $quiz->grade;
687     $quiz->grade = $newgrade;
689     // Use a transaction, so that on those databases that support it, this is safer.
690     $transaction = $DB->start_delegated_transaction();
692     // Update the quiz table.
693     $DB->set_field('quiz', 'grade', $newgrade, array('id' => $quiz->instance));
695     if ($oldgrade < 1) {
696         // If the old grade was zero, we cannot rescale, we have to recompute.
697         // We also recompute if the old grade was too small to avoid underflow problems.
698         quiz_update_all_final_grades($quiz);
700     } else {
701         // We can rescale the grades efficiently.
702         $timemodified = time();
703         $DB->execute("
704                 UPDATE {quiz_grades}
705                 SET grade = ? * grade, timemodified = ?
706                 WHERE quiz = ?
707         ", array($newgrade/$oldgrade, $timemodified, $quiz->id));
708     }
710     if ($oldgrade > 1e-7) {
711         // Update the quiz_feedback table.
712         $factor = $newgrade/$oldgrade;
713         $DB->execute("
714                 UPDATE {quiz_feedback}
715                 SET mingrade = ? * mingrade, maxgrade = ? * maxgrade
716                 WHERE quizid = ?
717         ", array($factor, $factor, $quiz->id));
718     }
720     // Update grade item and send all grades to gradebook.
721     quiz_grade_item_update($quiz);
722     quiz_update_grades($quiz);
724     $transaction->allow_commit();
725     return true;
728 /**
729  * Save the overall grade for a user at a quiz in the quiz_grades table
730  *
731  * @param object $quiz The quiz for which the best grade is to be calculated and then saved.
732  * @param int $userid The userid to calculate the grade for. Defaults to the current user.
733  * @param array $attempts The attempts of this user. Useful if you are
734  * looping through many users. Attempts can be fetched in one master query to
735  * avoid repeated querying.
736  * @return bool Indicates success or failure.
737  */
738 function quiz_save_best_grade($quiz, $userid = null, $attempts = array()) {
739     global $DB, $OUTPUT, $USER;
741     if (empty($userid)) {
742         $userid = $USER->id;
743     }
745     if (!$attempts) {
746         // Get all the attempts made by the user.
747         $attempts = quiz_get_user_attempts($quiz->id, $userid);
748     }
750     // Calculate the best grade.
751     $bestgrade = quiz_calculate_best_grade($quiz, $attempts);
752     $bestgrade = quiz_rescale_grade($bestgrade, $quiz, false);
754     // Save the best grade in the database.
755     if (is_null($bestgrade)) {
756         $DB->delete_records('quiz_grades', array('quiz' => $quiz->id, 'userid' => $userid));
758     } else if ($grade = $DB->get_record('quiz_grades',
759             array('quiz' => $quiz->id, 'userid' => $userid))) {
760         $grade->grade = $bestgrade;
761         $grade->timemodified = time();
762         $DB->update_record('quiz_grades', $grade);
764     } else {
765         $grade = new stdClass();
766         $grade->quiz = $quiz->id;
767         $grade->userid = $userid;
768         $grade->grade = $bestgrade;
769         $grade->timemodified = time();
770         $DB->insert_record('quiz_grades', $grade);
771     }
773     quiz_update_grades($quiz, $userid);
776 /**
777  * Calculate the overall grade for a quiz given a number of attempts by a particular user.
778  *
779  * @param object $quiz    the quiz settings object.
780  * @param array $attempts an array of all the user's attempts at this quiz in order.
781  * @return float          the overall grade
782  */
783 function quiz_calculate_best_grade($quiz, $attempts) {
785     switch ($quiz->grademethod) {
787         case QUIZ_ATTEMPTFIRST:
788             $firstattempt = reset($attempts);
789             return $firstattempt->sumgrades;
791         case QUIZ_ATTEMPTLAST:
792             $lastattempt = end($attempts);
793             return $lastattempt->sumgrades;
795         case QUIZ_GRADEAVERAGE:
796             $sum = 0;
797             $count = 0;
798             foreach ($attempts as $attempt) {
799                 if (!is_null($attempt->sumgrades)) {
800                     $sum += $attempt->sumgrades;
801                     $count++;
802                 }
803             }
804             if ($count == 0) {
805                 return null;
806             }
807             return $sum / $count;
809         case QUIZ_GRADEHIGHEST:
810         default:
811             $max = null;
812             foreach ($attempts as $attempt) {
813                 if ($attempt->sumgrades > $max) {
814                     $max = $attempt->sumgrades;
815                 }
816             }
817             return $max;
818     }
821 /**
822  * Update the final grade at this quiz for all students.
823  *
824  * This function is equivalent to calling quiz_save_best_grade for all
825  * users, but much more efficient.
826  *
827  * @param object $quiz the quiz settings.
828  */
829 function quiz_update_all_final_grades($quiz) {
830     global $DB;
832     if (!$quiz->sumgrades) {
833         return;
834     }
836     $param = array('iquizid' => $quiz->id, 'istatefinished' => quiz_attempt::FINISHED);
837     $firstlastattemptjoin = "JOIN (
838             SELECT
839                 iquiza.userid,
840                 MIN(attempt) AS firstattempt,
841                 MAX(attempt) AS lastattempt
843             FROM {quiz_attempts} iquiza
845             WHERE
846                 iquiza.state = :istatefinished AND
847                 iquiza.preview = 0 AND
848                 iquiza.quiz = :iquizid
850             GROUP BY iquiza.userid
851         ) first_last_attempts ON first_last_attempts.userid = quiza.userid";
853     switch ($quiz->grademethod) {
854         case QUIZ_ATTEMPTFIRST:
855             // Because of the where clause, there will only be one row, but we
856             // must still use an aggregate function.
857             $select = 'MAX(quiza.sumgrades)';
858             $join = $firstlastattemptjoin;
859             $where = 'quiza.attempt = first_last_attempts.firstattempt AND';
860             break;
862         case QUIZ_ATTEMPTLAST:
863             // Because of the where clause, there will only be one row, but we
864             // must still use an aggregate function.
865             $select = 'MAX(quiza.sumgrades)';
866             $join = $firstlastattemptjoin;
867             $where = 'quiza.attempt = first_last_attempts.lastattempt AND';
868             break;
870         case QUIZ_GRADEAVERAGE:
871             $select = 'AVG(quiza.sumgrades)';
872             $join = '';
873             $where = '';
874             break;
876         default:
877         case QUIZ_GRADEHIGHEST:
878             $select = 'MAX(quiza.sumgrades)';
879             $join = '';
880             $where = '';
881             break;
882     }
884     if ($quiz->sumgrades >= 0.000005) {
885         $finalgrade = $select . ' * ' . ($quiz->grade / $quiz->sumgrades);
886     } else {
887         $finalgrade = '0';
888     }
889     $param['quizid'] = $quiz->id;
890     $param['quizid2'] = $quiz->id;
891     $param['quizid3'] = $quiz->id;
892     $param['quizid4'] = $quiz->id;
893     $param['statefinished'] = quiz_attempt::FINISHED;
894     $param['statefinished2'] = quiz_attempt::FINISHED;
895     $finalgradesubquery = "
896             SELECT quiza.userid, $finalgrade AS newgrade
897             FROM {quiz_attempts} quiza
898             $join
899             WHERE
900                 $where
901                 quiza.state = :statefinished AND
902                 quiza.preview = 0 AND
903                 quiza.quiz = :quizid3
904             GROUP BY quiza.userid";
906     $changedgrades = $DB->get_records_sql("
907             SELECT users.userid, qg.id, qg.grade, newgrades.newgrade
909             FROM (
910                 SELECT userid
911                 FROM {quiz_grades} qg
912                 WHERE quiz = :quizid
913             UNION
914                 SELECT DISTINCT userid
915                 FROM {quiz_attempts} quiza2
916                 WHERE
917                     quiza2.state = :statefinished2 AND
918                     quiza2.preview = 0 AND
919                     quiza2.quiz = :quizid2
920             ) users
922             LEFT JOIN {quiz_grades} qg ON qg.userid = users.userid AND qg.quiz = :quizid4
924             LEFT JOIN (
925                 $finalgradesubquery
926             ) newgrades ON newgrades.userid = users.userid
928             WHERE
929                 ABS(newgrades.newgrade - qg.grade) > 0.000005 OR
930                 ((newgrades.newgrade IS NULL OR qg.grade IS NULL) AND NOT
931                           (newgrades.newgrade IS NULL AND qg.grade IS NULL))",
932                 // The mess on the previous line is detecting where the value is
933                 // NULL in one column, and NOT NULL in the other, but SQL does
934                 // not have an XOR operator, and MS SQL server can't cope with
935                 // (newgrades.newgrade IS NULL) <> (qg.grade IS NULL).
936             $param);
938     $timenow = time();
939     $todelete = array();
940     foreach ($changedgrades as $changedgrade) {
942         if (is_null($changedgrade->newgrade)) {
943             $todelete[] = $changedgrade->userid;
945         } else if (is_null($changedgrade->grade)) {
946             $toinsert = new stdClass();
947             $toinsert->quiz = $quiz->id;
948             $toinsert->userid = $changedgrade->userid;
949             $toinsert->timemodified = $timenow;
950             $toinsert->grade = $changedgrade->newgrade;
951             $DB->insert_record('quiz_grades', $toinsert);
953         } else {
954             $toupdate = new stdClass();
955             $toupdate->id = $changedgrade->id;
956             $toupdate->grade = $changedgrade->newgrade;
957             $toupdate->timemodified = $timenow;
958             $DB->update_record('quiz_grades', $toupdate);
959         }
960     }
962     if (!empty($todelete)) {
963         list($test, $params) = $DB->get_in_or_equal($todelete);
964         $DB->delete_records_select('quiz_grades', 'quiz = ? AND userid ' . $test,
965                 array_merge(array($quiz->id), $params));
966     }
969 /**
970  * Efficiently update check state time on all open attempts
971  *
972  * @param array $conditions optional restrictions on which attempts to update
973  *                    Allowed conditions:
974  *                      courseid => (array|int) attempts in given course(s)
975  *                      userid   => (array|int) attempts for given user(s)
976  *                      quizid   => (array|int) attempts in given quiz(s)
977  *                      groupid  => (array|int) quizzes with some override for given group(s)
978  *
979  */
980 function quiz_update_open_attempts(array $conditions) {
981     global $DB;
983     foreach ($conditions as &$value) {
984         if (!is_array($value)) {
985             $value = array($value);
986         }
987     }
989     $params = array();
990     $wheres = array("quiza.state IN ('inprogress', 'overdue')");
991     $iwheres = array("iquiza.state IN ('inprogress', 'overdue')");
993     if (isset($conditions['courseid'])) {
994         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'cid');
995         $params = array_merge($params, $inparams);
996         $wheres[] = "quiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";
997         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'icid');
998         $params = array_merge($params, $inparams);
999         $iwheres[] = "iquiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";
1000     }
1002     if (isset($conditions['userid'])) {
1003         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'uid');
1004         $params = array_merge($params, $inparams);
1005         $wheres[] = "quiza.userid $incond";
1006         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'iuid');
1007         $params = array_merge($params, $inparams);
1008         $iwheres[] = "iquiza.userid $incond";
1009     }
1011     if (isset($conditions['quizid'])) {
1012         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'qid');
1013         $params = array_merge($params, $inparams);
1014         $wheres[] = "quiza.quiz $incond";
1015         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'iqid');
1016         $params = array_merge($params, $inparams);
1017         $iwheres[] = "iquiza.quiz $incond";
1018     }
1020     if (isset($conditions['groupid'])) {
1021         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'gid');
1022         $params = array_merge($params, $inparams);
1023         $wheres[] = "quiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";
1024         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'igid');
1025         $params = array_merge($params, $inparams);
1026         $iwheres[] = "iquiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";
1027     }
1029     // SQL to compute timeclose and timelimit for each attempt:
1030     $quizausersql = quiz_get_attempt_usertime_sql(
1031             implode("\n                AND ", $iwheres));
1033     // SQL to compute the new timecheckstate
1034     $timecheckstatesql = "
1035           CASE WHEN quizauser.usertimelimit = 0 AND quizauser.usertimeclose = 0 THEN NULL
1036                WHEN quizauser.usertimelimit = 0 THEN quizauser.usertimeclose
1037                WHEN quizauser.usertimeclose = 0 THEN quiza.timestart + quizauser.usertimelimit
1038                WHEN quiza.timestart + quizauser.usertimelimit < quizauser.usertimeclose THEN quiza.timestart + quizauser.usertimelimit
1039                ELSE quizauser.usertimeclose END +
1040           CASE WHEN quiza.state = 'overdue' THEN quiz.graceperiod ELSE 0 END";
1042     // SQL to select which attempts to process
1043     $attemptselect = implode("\n                         AND ", $wheres);
1045    /*
1046     * Each database handles updates with inner joins differently:
1047     *  - mysql does not allow a FROM clause
1048     *  - postgres and mssql allow FROM but handle table aliases differently
1049     *  - oracle requires a subquery
1050     *
1051     * Different code for each database.
1052     */
1054     $dbfamily = $DB->get_dbfamily();
1055     if ($dbfamily == 'mysql') {
1056         $updatesql = "UPDATE {quiz_attempts} quiza
1057                         JOIN {quiz} quiz ON quiz.id = quiza.quiz
1058                         JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id
1059                          SET quiza.timecheckstate = $timecheckstatesql
1060                        WHERE $attemptselect";
1061     } else if ($dbfamily == 'postgres') {
1062         $updatesql = "UPDATE {quiz_attempts} quiza
1063                          SET timecheckstate = $timecheckstatesql
1064                         FROM {quiz} quiz, ( $quizausersql ) quizauser
1065                        WHERE quiz.id = quiza.quiz
1066                          AND quizauser.id = quiza.id
1067                          AND $attemptselect";
1068     } else if ($dbfamily == 'mssql') {
1069         $updatesql = "UPDATE quiza
1070                          SET timecheckstate = $timecheckstatesql
1071                         FROM {quiz_attempts} quiza
1072                         JOIN {quiz} quiz ON quiz.id = quiza.quiz
1073                         JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id
1074                        WHERE $attemptselect";
1075     } else {
1076         // oracle, sqlite and others
1077         $updatesql = "UPDATE {quiz_attempts} quiza
1078                          SET timecheckstate = (
1079                            SELECT $timecheckstatesql
1080                              FROM {quiz} quiz, ( $quizausersql ) quizauser
1081                             WHERE quiz.id = quiza.quiz
1082                               AND quizauser.id = quiza.id
1083                          )
1084                          WHERE $attemptselect";
1085     }
1087     $DB->execute($updatesql, $params);
1090 /**
1091  * Returns SQL to compute timeclose and timelimit for every attempt, taking into account user and group overrides.
1092  *
1093  * @param string $redundantwhereclauses extra where clauses to add to the subquery
1094  *      for performance. These can use the table alias iquiza for the quiz attempts table.
1095  * @return string SQL select with columns attempt.id, usertimeclose, usertimelimit.
1096  */
1097 function quiz_get_attempt_usertime_sql($redundantwhereclauses = '') {
1098     if ($redundantwhereclauses) {
1099         $redundantwhereclauses = 'WHERE ' . $redundantwhereclauses;
1100     }
1101     // The multiple qgo JOINS are necessary because we want timeclose/timelimit = 0 (unlimited) to supercede
1102     // any other group override
1103     $quizausersql = "
1104           SELECT iquiza.id,
1105            COALESCE(MAX(quo.timeclose), MAX(qgo1.timeclose), MAX(qgo2.timeclose), iquiz.timeclose) AS usertimeclose,
1106            COALESCE(MAX(quo.timelimit), MAX(qgo3.timelimit), MAX(qgo4.timelimit), iquiz.timelimit) AS usertimelimit
1108            FROM {quiz_attempts} iquiza
1109            JOIN {quiz} iquiz ON iquiz.id = iquiza.quiz
1110       LEFT JOIN {quiz_overrides} quo ON quo.quiz = iquiza.quiz AND quo.userid = iquiza.userid
1111       LEFT JOIN {groups_members} gm ON gm.userid = iquiza.userid
1112       LEFT JOIN {quiz_overrides} qgo1 ON qgo1.quiz = iquiza.quiz AND qgo1.groupid = gm.groupid AND qgo1.timeclose = 0
1113       LEFT JOIN {quiz_overrides} qgo2 ON qgo2.quiz = iquiza.quiz AND qgo2.groupid = gm.groupid AND qgo2.timeclose > 0
1114       LEFT JOIN {quiz_overrides} qgo3 ON qgo3.quiz = iquiza.quiz AND qgo3.groupid = gm.groupid AND qgo3.timelimit = 0
1115       LEFT JOIN {quiz_overrides} qgo4 ON qgo4.quiz = iquiza.quiz AND qgo4.groupid = gm.groupid AND qgo4.timelimit > 0
1116           $redundantwhereclauses
1117        GROUP BY iquiza.id, iquiz.id, iquiz.timeclose, iquiz.timelimit";
1118     return $quizausersql;
1121 /**
1122  * Return the attempt with the best grade for a quiz
1123  *
1124  * Which attempt is the best depends on $quiz->grademethod. If the grade
1125  * method is GRADEAVERAGE then this function simply returns the last attempt.
1126  * @return object         The attempt with the best grade
1127  * @param object $quiz    The quiz for which the best grade is to be calculated
1128  * @param array $attempts An array of all the attempts of the user at the quiz
1129  */
1130 function quiz_calculate_best_attempt($quiz, $attempts) {
1132     switch ($quiz->grademethod) {
1134         case QUIZ_ATTEMPTFIRST:
1135             foreach ($attempts as $attempt) {
1136                 return $attempt;
1137             }
1138             break;
1140         case QUIZ_GRADEAVERAGE: // We need to do something with it.
1141         case QUIZ_ATTEMPTLAST:
1142             foreach ($attempts as $attempt) {
1143                 $final = $attempt;
1144             }
1145             return $final;
1147         default:
1148         case QUIZ_GRADEHIGHEST:
1149             $max = -1;
1150             foreach ($attempts as $attempt) {
1151                 if ($attempt->sumgrades > $max) {
1152                     $max = $attempt->sumgrades;
1153                     $maxattempt = $attempt;
1154                 }
1155             }
1156             return $maxattempt;
1157     }
1160 /**
1161  * @return array int => lang string the options for calculating the quiz grade
1162  *      from the individual attempt grades.
1163  */
1164 function quiz_get_grading_options() {
1165     return array(
1166         QUIZ_GRADEHIGHEST => get_string('gradehighest', 'quiz'),
1167         QUIZ_GRADEAVERAGE => get_string('gradeaverage', 'quiz'),
1168         QUIZ_ATTEMPTFIRST => get_string('attemptfirst', 'quiz'),
1169         QUIZ_ATTEMPTLAST  => get_string('attemptlast', 'quiz')
1170     );
1173 /**
1174  * @param int $option one of the values QUIZ_GRADEHIGHEST, QUIZ_GRADEAVERAGE,
1175  *      QUIZ_ATTEMPTFIRST or QUIZ_ATTEMPTLAST.
1176  * @return the lang string for that option.
1177  */
1178 function quiz_get_grading_option_name($option) {
1179     $strings = quiz_get_grading_options();
1180     return $strings[$option];
1183 /**
1184  * @return array string => lang string the options for handling overdue quiz
1185  *      attempts.
1186  */
1187 function quiz_get_overdue_handling_options() {
1188     return array(
1189         'autosubmit'  => get_string('overduehandlingautosubmit', 'quiz'),
1190         'graceperiod' => get_string('overduehandlinggraceperiod', 'quiz'),
1191         'autoabandon' => get_string('overduehandlingautoabandon', 'quiz'),
1192     );
1195 /**
1196  * Get the choices for what size user picture to show.
1197  * @return array string => lang string the options for whether to display the user's picture.
1198  */
1199 function quiz_get_user_image_options() {
1200     return array(
1201         QUIZ_SHOWIMAGE_NONE  => get_string('shownoimage', 'quiz'),
1202         QUIZ_SHOWIMAGE_SMALL => get_string('showsmallimage', 'quiz'),
1203         QUIZ_SHOWIMAGE_LARGE => get_string('showlargeimage', 'quiz'),
1204     );
1207 /**
1208  * Get the choices to offer for the 'Questions per page' option.
1209  * @return array int => string.
1210  */
1211 function quiz_questions_per_page_options() {
1212     $pageoptions = array();
1213     $pageoptions[0] = get_string('neverallononepage', 'quiz');
1214     $pageoptions[1] = get_string('everyquestion', 'quiz');
1215     for ($i = 2; $i <= QUIZ_MAX_QPP_OPTION; ++$i) {
1216         $pageoptions[$i] = get_string('everynquestions', 'quiz', $i);
1217     }
1218     return $pageoptions;
1221 /**
1222  * Get the human-readable name for a quiz attempt state.
1223  * @param string $state one of the state constants like {@link quiz_attempt::IN_PROGRESS}.
1224  * @return string The lang string to describe that state.
1225  */
1226 function quiz_attempt_state_name($state) {
1227     switch ($state) {
1228         case quiz_attempt::IN_PROGRESS:
1229             return get_string('stateinprogress', 'quiz');
1230         case quiz_attempt::OVERDUE:
1231             return get_string('stateoverdue', 'quiz');
1232         case quiz_attempt::FINISHED:
1233             return get_string('statefinished', 'quiz');
1234         case quiz_attempt::ABANDONED:
1235             return get_string('stateabandoned', 'quiz');
1236         default:
1237             throw new coding_exception('Unknown quiz attempt state.');
1238     }
1241 // Other quiz functions ////////////////////////////////////////////////////////
1243 /**
1244  * @param object $quiz the quiz.
1245  * @param int $cmid the course_module object for this quiz.
1246  * @param object $question the question.
1247  * @param string $returnurl url to return to after action is done.
1248  * @param int $variant which question variant to preview (optional).
1249  * @return string html for a number of icons linked to action pages for a
1250  * question - preview and edit / view icons depending on user capabilities.
1251  */
1252 function quiz_question_action_icons($quiz, $cmid, $question, $returnurl, $variant = null) {
1253     $html = quiz_question_preview_button($quiz, $question, false, $variant) . ' ' .
1254             quiz_question_edit_button($cmid, $question, $returnurl);
1255     return $html;
1258 /**
1259  * @param int $cmid the course_module.id for this quiz.
1260  * @param object $question the question.
1261  * @param string $returnurl url to return to after action is done.
1262  * @param string $contentbeforeicon some HTML content to be added inside the link, before the icon.
1263  * @return the HTML for an edit icon, view icon, or nothing for a question
1264  *      (depending on permissions).
1265  */
1266 function quiz_question_edit_button($cmid, $question, $returnurl, $contentaftericon = '') {
1267     global $CFG, $OUTPUT;
1269     // Minor efficiency saving. Only get strings once, even if there are a lot of icons on one page.
1270     static $stredit = null;
1271     static $strview = null;
1272     if ($stredit === null) {
1273         $stredit = get_string('edit');
1274         $strview = get_string('view');
1275     }
1277     // What sort of icon should we show?
1278     $action = '';
1279     if (!empty($question->id) &&
1280             (question_has_capability_on($question, 'edit', $question->category) ||
1281                     question_has_capability_on($question, 'move', $question->category))) {
1282         $action = $stredit;
1283         $icon = '/t/edit';
1284     } else if (!empty($question->id) &&
1285             question_has_capability_on($question, 'view', $question->category)) {
1286         $action = $strview;
1287         $icon = '/i/info';
1288     }
1290     // Build the icon.
1291     if ($action) {
1292         if ($returnurl instanceof moodle_url) {
1293             $returnurl = $returnurl->out_as_local_url(false);
1294         }
1295         $questionparams = array('returnurl' => $returnurl, 'cmid' => $cmid, 'id' => $question->id);
1296         $questionurl = new moodle_url("$CFG->wwwroot/question/question.php", $questionparams);
1297         return '<a title="' . $action . '" href="' . $questionurl->out() . '" class="questioneditbutton"><img src="' .
1298                 $OUTPUT->pix_url($icon) . '" alt="' . $action . '" />' . $contentaftericon .
1299                 '</a>';
1300     } else if ($contentaftericon) {
1301         return '<span class="questioneditbutton">' . $contentaftericon . '</span>';
1302     } else {
1303         return '';
1304     }
1307 /**
1308  * @param object $quiz the quiz settings
1309  * @param object $question the question
1310  * @param int $variant which question variant to preview (optional).
1311  * @return moodle_url to preview this question with the options from this quiz.
1312  */
1313 function quiz_question_preview_url($quiz, $question, $variant = null) {
1314     // Get the appropriate display options.
1315     $displayoptions = mod_quiz_display_options::make_from_quiz($quiz,
1316             mod_quiz_display_options::DURING);
1318     $maxmark = null;
1319     if (isset($question->maxmark)) {
1320         $maxmark = $question->maxmark;
1321     }
1323     // Work out the correcte preview URL.
1324     return question_preview_url($question->id, $quiz->preferredbehaviour,
1325             $maxmark, $displayoptions, $variant);
1328 /**
1329  * @param object $quiz the quiz settings
1330  * @param object $question the question
1331  * @param bool $label if true, show the preview question label after the icon
1332  * @param int $variant which question variant to preview (optional).
1333  * @return the HTML for a preview question icon.
1334  */
1335 function quiz_question_preview_button($quiz, $question, $label = false, $variant = null) {
1336     global $PAGE;
1337     if (!question_has_capability_on($question, 'use', $question->category)) {
1338         return '';
1339     }
1341     return $PAGE->get_renderer('mod_quiz', 'edit')->question_preview_icon($quiz, $question, $label, $variant);
1344 /**
1345  * @param object $attempt the attempt.
1346  * @param object $context the quiz context.
1347  * @return int whether flags should be shown/editable to the current user for this attempt.
1348  */
1349 function quiz_get_flag_option($attempt, $context) {
1350     global $USER;
1351     if (!has_capability('moodle/question:flag', $context)) {
1352         return question_display_options::HIDDEN;
1353     } else if ($attempt->userid == $USER->id) {
1354         return question_display_options::EDITABLE;
1355     } else {
1356         return question_display_options::VISIBLE;
1357     }
1360 /**
1361  * Work out what state this quiz attempt is in - in the sense used by
1362  * quiz_get_review_options, not in the sense of $attempt->state.
1363  * @param object $quiz the quiz settings
1364  * @param object $attempt the quiz_attempt database row.
1365  * @return int one of the mod_quiz_display_options::DURING,
1366  *      IMMEDIATELY_AFTER, LATER_WHILE_OPEN or AFTER_CLOSE constants.
1367  */
1368 function quiz_attempt_state($quiz, $attempt) {
1369     if ($attempt->state == quiz_attempt::IN_PROGRESS) {
1370         return mod_quiz_display_options::DURING;
1371     } else if (time() < $attempt->timefinish + 120) {
1372         return mod_quiz_display_options::IMMEDIATELY_AFTER;
1373     } else if (!$quiz->timeclose || time() < $quiz->timeclose) {
1374         return mod_quiz_display_options::LATER_WHILE_OPEN;
1375     } else {
1376         return mod_quiz_display_options::AFTER_CLOSE;
1377     }
1380 /**
1381  * The the appropraite mod_quiz_display_options object for this attempt at this
1382  * quiz right now.
1383  *
1384  * @param object $quiz the quiz instance.
1385  * @param object $attempt the attempt in question.
1386  * @param $context the quiz context.
1387  *
1388  * @return mod_quiz_display_options
1389  */
1390 function quiz_get_review_options($quiz, $attempt, $context) {
1391     $options = mod_quiz_display_options::make_from_quiz($quiz, quiz_attempt_state($quiz, $attempt));
1393     $options->readonly = true;
1394     $options->flags = quiz_get_flag_option($attempt, $context);
1395     if (!empty($attempt->id)) {
1396         $options->questionreviewlink = new moodle_url('/mod/quiz/reviewquestion.php',
1397                 array('attempt' => $attempt->id));
1398     }
1400     // Show a link to the comment box only for closed attempts.
1401     if (!empty($attempt->id) && $attempt->state == quiz_attempt::FINISHED && !$attempt->preview &&
1402             !is_null($context) && has_capability('mod/quiz:grade', $context)) {
1403         $options->manualcomment = question_display_options::VISIBLE;
1404         $options->manualcommentlink = new moodle_url('/mod/quiz/comment.php',
1405                 array('attempt' => $attempt->id));
1406     }
1408     if (!is_null($context) && !$attempt->preview &&
1409             has_capability('mod/quiz:viewreports', $context) &&
1410             has_capability('moodle/grade:viewhidden', $context)) {
1411         // People who can see reports and hidden grades should be shown everything,
1412         // except during preview when teachers want to see what students see.
1413         $options->attempt = question_display_options::VISIBLE;
1414         $options->correctness = question_display_options::VISIBLE;
1415         $options->marks = question_display_options::MARK_AND_MAX;
1416         $options->feedback = question_display_options::VISIBLE;
1417         $options->numpartscorrect = question_display_options::VISIBLE;
1418         $options->manualcomment = question_display_options::VISIBLE;
1419         $options->generalfeedback = question_display_options::VISIBLE;
1420         $options->rightanswer = question_display_options::VISIBLE;
1421         $options->overallfeedback = question_display_options::VISIBLE;
1422         $options->history = question_display_options::VISIBLE;
1424     }
1426     return $options;
1429 /**
1430  * Combines the review options from a number of different quiz attempts.
1431  * Returns an array of two ojects, so the suggested way of calling this
1432  * funciton is:
1433  * list($someoptions, $alloptions) = quiz_get_combined_reviewoptions(...)
1434  *
1435  * @param object $quiz the quiz instance.
1436  * @param array $attempts an array of attempt objects.
1437  *
1438  * @return array of two options objects, one showing which options are true for
1439  *          at least one of the attempts, the other showing which options are true
1440  *          for all attempts.
1441  */
1442 function quiz_get_combined_reviewoptions($quiz, $attempts) {
1443     $fields = array('feedback', 'generalfeedback', 'rightanswer', 'overallfeedback');
1444     $someoptions = new stdClass();
1445     $alloptions = new stdClass();
1446     foreach ($fields as $field) {
1447         $someoptions->$field = false;
1448         $alloptions->$field = true;
1449     }
1450     $someoptions->marks = question_display_options::HIDDEN;
1451     $alloptions->marks = question_display_options::MARK_AND_MAX;
1453     // This shouldn't happen, but we need to prevent reveal information.
1454     if (empty($attempts)) {
1455         return array($someoptions, $someoptions);
1456     }
1458     foreach ($attempts as $attempt) {
1459         $attemptoptions = mod_quiz_display_options::make_from_quiz($quiz,
1460                 quiz_attempt_state($quiz, $attempt));
1461         foreach ($fields as $field) {
1462             $someoptions->$field = $someoptions->$field || $attemptoptions->$field;
1463             $alloptions->$field = $alloptions->$field && $attemptoptions->$field;
1464         }
1465         $someoptions->marks = max($someoptions->marks, $attemptoptions->marks);
1466         $alloptions->marks = min($alloptions->marks, $attemptoptions->marks);
1467     }
1468     return array($someoptions, $alloptions);
1471 // Functions for sending notification messages /////////////////////////////////
1473 /**
1474  * Sends a confirmation message to the student confirming that the attempt was processed.
1475  *
1476  * @param object $a lots of useful information that can be used in the message
1477  *      subject and body.
1478  *
1479  * @return int|false as for {@link message_send()}.
1480  */
1481 function quiz_send_confirmation($recipient, $a) {
1483     // Add information about the recipient to $a.
1484     // Don't do idnumber. we want idnumber to be the submitter's idnumber.
1485     $a->username     = fullname($recipient);
1486     $a->userusername = $recipient->username;
1488     // Prepare the message.
1489     $eventdata = new stdClass();
1490     $eventdata->component         = 'mod_quiz';
1491     $eventdata->name              = 'confirmation';
1492     $eventdata->notification      = 1;
1494     $eventdata->userfrom          = core_user::get_noreply_user();
1495     $eventdata->userto            = $recipient;
1496     $eventdata->subject           = get_string('emailconfirmsubject', 'quiz', $a);
1497     $eventdata->fullmessage       = get_string('emailconfirmbody', 'quiz', $a);
1498     $eventdata->fullmessageformat = FORMAT_PLAIN;
1499     $eventdata->fullmessagehtml   = '';
1501     $eventdata->smallmessage      = get_string('emailconfirmsmall', 'quiz', $a);
1502     $eventdata->contexturl        = $a->quizurl;
1503     $eventdata->contexturlname    = $a->quizname;
1505     // ... and send it.
1506     return message_send($eventdata);
1509 /**
1510  * Sends notification messages to the interested parties that assign the role capability
1511  *
1512  * @param object $recipient user object of the intended recipient
1513  * @param object $a associative array of replaceable fields for the templates
1514  *
1515  * @return int|false as for {@link message_send()}.
1516  */
1517 function quiz_send_notification($recipient, $submitter, $a) {
1519     // Recipient info for template.
1520     $a->useridnumber = $recipient->idnumber;
1521     $a->username     = fullname($recipient);
1522     $a->userusername = $recipient->username;
1524     // Prepare the message.
1525     $eventdata = new stdClass();
1526     $eventdata->component         = 'mod_quiz';
1527     $eventdata->name              = 'submission';
1528     $eventdata->notification      = 1;
1530     $eventdata->userfrom          = $submitter;
1531     $eventdata->userto            = $recipient;
1532     $eventdata->subject           = get_string('emailnotifysubject', 'quiz', $a);
1533     $eventdata->fullmessage       = get_string('emailnotifybody', 'quiz', $a);
1534     $eventdata->fullmessageformat = FORMAT_PLAIN;
1535     $eventdata->fullmessagehtml   = '';
1537     $eventdata->smallmessage      = get_string('emailnotifysmall', 'quiz', $a);
1538     $eventdata->contexturl        = $a->quizreviewurl;
1539     $eventdata->contexturlname    = $a->quizname;
1541     // ... and send it.
1542     return message_send($eventdata);
1545 /**
1546  * Send all the requried messages when a quiz attempt is submitted.
1547  *
1548  * @param object $course the course
1549  * @param object $quiz the quiz
1550  * @param object $attempt this attempt just finished
1551  * @param object $context the quiz context
1552  * @param object $cm the coursemodule for this quiz
1553  *
1554  * @return bool true if all necessary messages were sent successfully, else false.
1555  */
1556 function quiz_send_notification_messages($course, $quiz, $attempt, $context, $cm) {
1557     global $CFG, $DB;
1559     // Do nothing if required objects not present.
1560     if (empty($course) or empty($quiz) or empty($attempt) or empty($context)) {
1561         throw new coding_exception('$course, $quiz, $attempt, $context and $cm must all be set.');
1562     }
1564     $submitter = $DB->get_record('user', array('id' => $attempt->userid), '*', MUST_EXIST);
1566     // Check for confirmation required.
1567     $sendconfirm = false;
1568     $notifyexcludeusers = '';
1569     if (has_capability('mod/quiz:emailconfirmsubmission', $context, $submitter, false)) {
1570         $notifyexcludeusers = $submitter->id;
1571         $sendconfirm = true;
1572     }
1574     // Check for notifications required.
1575     $notifyfields = 'u.id, u.username, u.idnumber, u.email, u.emailstop, u.lang,
1576             u.timezone, u.mailformat, u.maildisplay, u.auth, u.suspended, u.deleted, ';
1577     $notifyfields .= get_all_user_name_fields(true, 'u');
1578     $groups = groups_get_all_groups($course->id, $submitter->id, $cm->groupingid);
1579     if (is_array($groups) && count($groups) > 0) {
1580         $groups = array_keys($groups);
1581     } else if (groups_get_activity_groupmode($cm, $course) != NOGROUPS) {
1582         // If the user is not in a group, and the quiz is set to group mode,
1583         // then set $groups to a non-existant id so that only users with
1584         // 'moodle/site:accessallgroups' get notified.
1585         $groups = -1;
1586     } else {
1587         $groups = '';
1588     }
1589     $userstonotify = get_users_by_capability($context, 'mod/quiz:emailnotifysubmission',
1590             $notifyfields, '', '', '', $groups, $notifyexcludeusers, false, false, true);
1592     if (empty($userstonotify) && !$sendconfirm) {
1593         return true; // Nothing to do.
1594     }
1596     $a = new stdClass();
1597     // Course info.
1598     $a->coursename      = $course->fullname;
1599     $a->courseshortname = $course->shortname;
1600     // Quiz info.
1601     $a->quizname        = $quiz->name;
1602     $a->quizreporturl   = $CFG->wwwroot . '/mod/quiz/report.php?id=' . $cm->id;
1603     $a->quizreportlink  = '<a href="' . $a->quizreporturl . '">' .
1604             format_string($quiz->name) . ' report</a>';
1605     $a->quizurl         = $CFG->wwwroot . '/mod/quiz/view.php?id=' . $cm->id;
1606     $a->quizlink        = '<a href="' . $a->quizurl . '">' . format_string($quiz->name) . '</a>';
1607     // Attempt info.
1608     $a->submissiontime  = userdate($attempt->timefinish);
1609     $a->timetaken       = format_time($attempt->timefinish - $attempt->timestart);
1610     $a->quizreviewurl   = $CFG->wwwroot . '/mod/quiz/review.php?attempt=' . $attempt->id;
1611     $a->quizreviewlink  = '<a href="' . $a->quizreviewurl . '">' .
1612             format_string($quiz->name) . ' review</a>';
1613     // Student who sat the quiz info.
1614     $a->studentidnumber = $submitter->idnumber;
1615     $a->studentname     = fullname($submitter);
1616     $a->studentusername = $submitter->username;
1618     $allok = true;
1620     // Send notifications if required.
1621     if (!empty($userstonotify)) {
1622         foreach ($userstonotify as $recipient) {
1623             $allok = $allok && quiz_send_notification($recipient, $submitter, $a);
1624         }
1625     }
1627     // Send confirmation if required. We send the student confirmation last, so
1628     // that if message sending is being intermittently buggy, which means we send
1629     // some but not all messages, and then try again later, then teachers may get
1630     // duplicate messages, but the student will always get exactly one.
1631     if ($sendconfirm) {
1632         $allok = $allok && quiz_send_confirmation($submitter, $a);
1633     }
1635     return $allok;
1638 /**
1639  * Send the notification message when a quiz attempt becomes overdue.
1640  *
1641  * @param quiz_attempt $attemptobj all the data about the quiz attempt.
1642  */
1643 function quiz_send_overdue_message($attemptobj) {
1644     global $CFG, $DB;
1646     $submitter = $DB->get_record('user', array('id' => $attemptobj->get_userid()), '*', MUST_EXIST);
1648     if (!$attemptobj->has_capability('mod/quiz:emailwarnoverdue', $submitter->id, false)) {
1649         return; // Message not required.
1650     }
1652     if (!$attemptobj->has_response_to_at_least_one_graded_question()) {
1653         return; // Message not required.
1654     }
1656     // Prepare lots of useful information that admins might want to include in
1657     // the email message.
1658     $quizname = format_string($attemptobj->get_quiz_name());
1660     $deadlines = array();
1661     if ($attemptobj->get_quiz()->timelimit) {
1662         $deadlines[] = $attemptobj->get_attempt()->timestart + $attemptobj->get_quiz()->timelimit;
1663     }
1664     if ($attemptobj->get_quiz()->timeclose) {
1665         $deadlines[] = $attemptobj->get_quiz()->timeclose;
1666     }
1667     $duedate = min($deadlines);
1668     $graceend = $duedate + $attemptobj->get_quiz()->graceperiod;
1670     $a = new stdClass();
1671     // Course info.
1672     $a->coursename         = format_string($attemptobj->get_course()->fullname);
1673     $a->courseshortname    = format_string($attemptobj->get_course()->shortname);
1674     // Quiz info.
1675     $a->quizname           = $quizname;
1676     $a->quizurl            = $attemptobj->view_url();
1677     $a->quizlink           = '<a href="' . $a->quizurl . '">' . $quizname . '</a>';
1678     // Attempt info.
1679     $a->attemptduedate     = userdate($duedate);
1680     $a->attemptgraceend    = userdate($graceend);
1681     $a->attemptsummaryurl  = $attemptobj->summary_url()->out(false);
1682     $a->attemptsummarylink = '<a href="' . $a->attemptsummaryurl . '">' . $quizname . ' review</a>';
1683     // Student's info.
1684     $a->studentidnumber    = $submitter->idnumber;
1685     $a->studentname        = fullname($submitter);
1686     $a->studentusername    = $submitter->username;
1688     // Prepare the message.
1689     $eventdata = new stdClass();
1690     $eventdata->component         = 'mod_quiz';
1691     $eventdata->name              = 'attempt_overdue';
1692     $eventdata->notification      = 1;
1694     $eventdata->userfrom          = core_user::get_noreply_user();
1695     $eventdata->userto            = $submitter;
1696     $eventdata->subject           = get_string('emailoverduesubject', 'quiz', $a);
1697     $eventdata->fullmessage       = get_string('emailoverduebody', 'quiz', $a);
1698     $eventdata->fullmessageformat = FORMAT_PLAIN;
1699     $eventdata->fullmessagehtml   = '';
1701     $eventdata->smallmessage      = get_string('emailoverduesmall', 'quiz', $a);
1702     $eventdata->contexturl        = $a->quizurl;
1703     $eventdata->contexturlname    = $a->quizname;
1705     // Send the message.
1706     return message_send($eventdata);
1709 /**
1710  * Handle the quiz_attempt_submitted event.
1711  *
1712  * This sends the confirmation and notification messages, if required.
1713  *
1714  * @param object $event the event object.
1715  */
1716 function quiz_attempt_submitted_handler($event) {
1717     global $DB;
1719     $course  = $DB->get_record('course', array('id' => $event->courseid));
1720     $attempt = $event->get_record_snapshot('quiz_attempts', $event->objectid);
1721     $quiz    = $event->get_record_snapshot('quiz', $attempt->quiz);
1722     $cm      = get_coursemodule_from_id('quiz', $event->get_context()->instanceid, $event->courseid);
1724     if (!($course && $quiz && $cm && $attempt)) {
1725         // Something has been deleted since the event was raised. Therefore, the
1726         // event is no longer relevant.
1727         return true;
1728     }
1730     // Update completion state.
1731     $completion = new completion_info($course);
1732     if ($completion->is_enabled($cm) && ($quiz->completionattemptsexhausted || $quiz->completionpass)) {
1733         $completion->update_state($cm, COMPLETION_COMPLETE, $event->userid);
1734     }
1735     return quiz_send_notification_messages($course, $quiz, $attempt,
1736             context_module::instance($cm->id), $cm);
1739 /**
1740  * Handle groups_member_added event
1741  *
1742  * @param object $event the event object.
1743  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_member_added()}.
1744  */
1745 function quiz_groups_member_added_handler($event) {
1746     debugging('quiz_groups_member_added_handler() is deprecated, please use ' .
1747         '\mod_quiz\group_observers::group_member_added() instead.', DEBUG_DEVELOPER);
1748     quiz_update_open_attempts(array('userid'=>$event->userid, 'groupid'=>$event->groupid));
1751 /**
1752  * Handle groups_member_removed event
1753  *
1754  * @param object $event the event object.
1755  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_member_removed()}.
1756  */
1757 function quiz_groups_member_removed_handler($event) {
1758     debugging('quiz_groups_member_removed_handler() is deprecated, please use ' .
1759         '\mod_quiz\group_observers::group_member_removed() instead.', DEBUG_DEVELOPER);
1760     quiz_update_open_attempts(array('userid'=>$event->userid, 'groupid'=>$event->groupid));
1763 /**
1764  * Handle groups_group_deleted event
1765  *
1766  * @param object $event the event object.
1767  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_deleted()}.
1768  */
1769 function quiz_groups_group_deleted_handler($event) {
1770     global $DB;
1771     debugging('quiz_groups_group_deleted_handler() is deprecated, please use ' .
1772         '\mod_quiz\group_observers::group_deleted() instead.', DEBUG_DEVELOPER);
1773     quiz_process_group_deleted_in_course($event->courseid);
1776 /**
1777  * Logic to happen when a/some group(s) has/have been deleted in a course.
1778  *
1779  * @param int $courseid The course ID.
1780  * @return void
1781  */
1782 function quiz_process_group_deleted_in_course($courseid) {
1783     global $DB;
1785     // It would be nice if we got the groupid that was deleted.
1786     // Instead, we just update all quizzes with orphaned group overrides.
1787     $sql = "SELECT o.id, o.quiz
1788               FROM {quiz_overrides} o
1789               JOIN {quiz} quiz ON quiz.id = o.quiz
1790          LEFT JOIN {groups} grp ON grp.id = o.groupid
1791              WHERE quiz.course = :courseid
1792                AND o.groupid IS NOT NULL
1793                AND grp.id IS NULL";
1794     $params = array('courseid' => $courseid);
1795     $records = $DB->get_records_sql_menu($sql, $params);
1796     if (!$records) {
1797         return; // Nothing to do.
1798     }
1799     $DB->delete_records_list('quiz_overrides', 'id', array_keys($records));
1800     quiz_update_open_attempts(array('quizid' => array_unique(array_values($records))));
1803 /**
1804  * Handle groups_members_removed event
1805  *
1806  * @param object $event the event object.
1807  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_member_removed()}.
1808  */
1809 function quiz_groups_members_removed_handler($event) {
1810     debugging('quiz_groups_members_removed_handler() is deprecated, please use ' .
1811         '\mod_quiz\group_observers::group_member_removed() instead.', DEBUG_DEVELOPER);
1812     if ($event->userid == 0) {
1813         quiz_update_open_attempts(array('courseid'=>$event->courseid));
1814     } else {
1815         quiz_update_open_attempts(array('courseid'=>$event->courseid, 'userid'=>$event->userid));
1816     }
1819 /**
1820  * Get the information about the standard quiz JavaScript module.
1821  * @return array a standard jsmodule structure.
1822  */
1823 function quiz_get_js_module() {
1824     global $PAGE;
1826     return array(
1827         'name' => 'mod_quiz',
1828         'fullpath' => '/mod/quiz/module.js',
1829         'requires' => array('base', 'dom', 'event-delegate', 'event-key',
1830                 'core_question_engine', 'moodle-core-formchangechecker'),
1831         'strings' => array(
1832             array('cancel', 'moodle'),
1833             array('flagged', 'question'),
1834             array('functiondisabledbysecuremode', 'quiz'),
1835             array('startattempt', 'quiz'),
1836             array('timesup', 'quiz'),
1837             array('changesmadereallygoaway', 'moodle'),
1838         ),
1839     );
1843 /**
1844  * An extension of question_display_options that includes the extra options used
1845  * by the quiz.
1846  *
1847  * @copyright  2010 The Open University
1848  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1849  */
1850 class mod_quiz_display_options extends question_display_options {
1851     /**#@+
1852      * @var integer bits used to indicate various times in relation to a
1853      * quiz attempt.
1854      */
1855     const DURING =            0x10000;
1856     const IMMEDIATELY_AFTER = 0x01000;
1857     const LATER_WHILE_OPEN =  0x00100;
1858     const AFTER_CLOSE =       0x00010;
1859     /**#@-*/
1861     /**
1862      * @var boolean if this is false, then the student is not allowed to review
1863      * anything about the attempt.
1864      */
1865     public $attempt = true;
1867     /**
1868      * @var boolean if this is false, then the student is not allowed to review
1869      * anything about the attempt.
1870      */
1871     public $overallfeedback = self::VISIBLE;
1873     /**
1874      * Set up the various options from the quiz settings, and a time constant.
1875      * @param object $quiz the quiz settings.
1876      * @param int $one of the {@link DURING}, {@link IMMEDIATELY_AFTER},
1877      * {@link LATER_WHILE_OPEN} or {@link AFTER_CLOSE} constants.
1878      * @return mod_quiz_display_options set up appropriately.
1879      */
1880     public static function make_from_quiz($quiz, $when) {
1881         $options = new self();
1883         $options->attempt = self::extract($quiz->reviewattempt, $when, true, false);
1884         $options->correctness = self::extract($quiz->reviewcorrectness, $when);
1885         $options->marks = self::extract($quiz->reviewmarks, $when,
1886                 self::MARK_AND_MAX, self::MAX_ONLY);
1887         $options->feedback = self::extract($quiz->reviewspecificfeedback, $when);
1888         $options->generalfeedback = self::extract($quiz->reviewgeneralfeedback, $when);
1889         $options->rightanswer = self::extract($quiz->reviewrightanswer, $when);
1890         $options->overallfeedback = self::extract($quiz->reviewoverallfeedback, $when);
1892         $options->numpartscorrect = $options->feedback;
1893         $options->manualcomment = $options->feedback;
1895         if ($quiz->questiondecimalpoints != -1) {
1896             $options->markdp = $quiz->questiondecimalpoints;
1897         } else {
1898             $options->markdp = $quiz->decimalpoints;
1899         }
1901         return $options;
1902     }
1904     protected static function extract($bitmask, $bit,
1905             $whenset = self::VISIBLE, $whennotset = self::HIDDEN) {
1906         if ($bitmask & $bit) {
1907             return $whenset;
1908         } else {
1909             return $whennotset;
1910         }
1911     }
1915 /**
1916  * A {@link qubaid_condition} for finding all the question usages belonging to
1917  * a particular quiz.
1918  *
1919  * @copyright  2010 The Open University
1920  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1921  */
1922 class qubaids_for_quiz extends qubaid_join {
1923     public function __construct($quizid, $includepreviews = true, $onlyfinished = false) {
1924         $where = 'quiza.quiz = :quizaquiz';
1925         $params = array('quizaquiz' => $quizid);
1927         if (!$includepreviews) {
1928             $where .= ' AND preview = 0';
1929         }
1931         if ($onlyfinished) {
1932             $where .= ' AND state == :statefinished';
1933             $params['statefinished'] = quiz_attempt::FINISHED;
1934         }
1936         parent::__construct('{quiz_attempts} quiza', 'quiza.uniqueid', $where, $params);
1937     }
1940 /**
1941  * Creates a textual representation of a question for display.
1942  *
1943  * @param object $question A question object from the database questions table
1944  * @param bool $showicon If true, show the question's icon with the question. False by default.
1945  * @param bool $showquestiontext If true (default), show question text after question name.
1946  *       If false, show only question name.
1947  * @return string
1948  */
1949 function quiz_question_tostring($question, $showicon = false, $showquestiontext = true) {
1950     $result = '';
1952     $name = shorten_text(format_string($question->name), 200);
1953     if ($showicon) {
1954         $name .= print_question_icon($question) . ' ' . $name;
1955     }
1956     $result .= html_writer::span($name, 'questionname');
1958     if ($showquestiontext) {
1959         $questiontext = question_utils::to_plain_text($question->questiontext,
1960                 $question->questiontextformat, array('noclean' => true, 'para' => false));
1961         $questiontext = shorten_text($questiontext, 200);
1962         if ($questiontext) {
1963             $result .= ' ' . html_writer::span(s($questiontext), 'questiontext');
1964         }
1965     }
1967     return $result;
1970 /**
1971  * Verify that the question exists, and the user has permission to use it.
1972  * Does not return. Throws an exception if the question cannot be used.
1973  * @param int $questionid The id of the question.
1974  */
1975 function quiz_require_question_use($questionid) {
1976     global $DB;
1977     $question = $DB->get_record('question', array('id' => $questionid), '*', MUST_EXIST);
1978     question_require_capability_on($question, 'use');
1981 /**
1982  * Verify that the question exists, and the user has permission to use it.
1983  * @param object $quiz the quiz settings.
1984  * @param int $slot which question in the quiz to test.
1985  * @return bool whether the user can use this question.
1986  */
1987 function quiz_has_question_use($quiz, $slot) {
1988     global $DB;
1989     $question = $DB->get_record_sql("
1990             SELECT q.*
1991               FROM {quiz_slots} slot
1992               JOIN {question} q ON q.id = slot.questionid
1993              WHERE slot.quizid = ? AND slot.slot = ?", array($quiz->id, $slot));
1994     if (!$question) {
1995         return false;
1996     }
1997     return question_has_capability_on($question, 'use');
2000 /**
2001  * Add a question to a quiz
2002  *
2003  * Adds a question to a quiz by updating $quiz as well as the
2004  * quiz and quiz_slots tables. It also adds a page break if required.
2005  * @param int $questionid The id of the question to be added
2006  * @param object $quiz The extended quiz object as used by edit.php
2007  *      This is updated by this function
2008  * @param int $page Which page in quiz to add the question on. If 0 (default),
2009  *      add at the end
2010  * @param float $maxmark The maximum mark to set for this question. (Optional,
2011  *      defaults to question.defaultmark.
2012  * @return bool false if the question was already in the quiz
2013  */
2014 function quiz_add_quiz_question($questionid, $quiz, $page = 0, $maxmark = null) {
2015     global $DB;
2016     $slots = $DB->get_records('quiz_slots', array('quizid' => $quiz->id),
2017             'slot', 'questionid, slot, page, id');
2018     if (array_key_exists($questionid, $slots)) {
2019         return false;
2020     }
2022     $trans = $DB->start_delegated_transaction();
2024     $maxpage = 1;
2025     $numonlastpage = 0;
2026     foreach ($slots as $slot) {
2027         if ($slot->page > $maxpage) {
2028             $maxpage = $slot->page;
2029             $numonlastpage = 1;
2030         } else {
2031             $numonlastpage += 1;
2032         }
2033     }
2035     // Add the new question instance.
2036     $slot = new stdClass();
2037     $slot->quizid = $quiz->id;
2038     $slot->questionid = $questionid;
2040     if ($maxmark !== null) {
2041         $slot->maxmark = $maxmark;
2042     } else {
2043         $slot->maxmark = $DB->get_field('question', 'defaultmark', array('id' => $questionid));
2044     }
2046     if (is_int($page) && $page >= 1) {
2047         // Adding on a given page.
2048         $lastslotbefore = 0;
2049         foreach (array_reverse($slots) as $otherslot) {
2050             if ($otherslot->page > $page) {
2051                 $DB->set_field('quiz_slots', 'slot', $otherslot->slot + 1, array('id' => $otherslot->id));
2052             } else {
2053                 $lastslotbefore = $otherslot->slot;
2054                 break;
2055             }
2056         }
2057         $slot->slot = $lastslotbefore + 1;
2058         $slot->page = min($page, $maxpage + 1);
2060         $DB->execute("
2061                 UPDATE {quiz_sections}
2062                    SET firstslot = firstslot + 1
2063                  WHERE quizid = ?
2064                    AND firstslot > ?
2065                 ", array($quiz->id, max($lastslotbefore, 1)));
2067     } else {
2068         $lastslot = end($slots);
2069         if ($lastslot) {
2070             $slot->slot = $lastslot->slot + 1;
2071         } else {
2072             $slot->slot = 1;
2073         }
2074         if ($quiz->questionsperpage && $numonlastpage >= $quiz->questionsperpage) {
2075             $slot->page = $maxpage + 1;
2076         } else {
2077             $slot->page = $maxpage;
2078         }
2079     }
2081     $DB->insert_record('quiz_slots', $slot);
2082     $trans->allow_commit();
2085 /**
2086  * Add a random question to the quiz at a given point.
2087  * @param object $quiz the quiz settings.
2088  * @param int $addonpage the page on which to add the question.
2089  * @param int $categoryid the question category to add the question from.
2090  * @param int $number the number of random questions to add.
2091  * @param bool $includesubcategories whether to include questoins from subcategories.
2092  */
2093 function quiz_add_random_questions($quiz, $addonpage, $categoryid, $number,
2094         $includesubcategories) {
2095     global $DB;
2097     $category = $DB->get_record('question_categories', array('id' => $categoryid));
2098     if (!$category) {
2099         print_error('invalidcategoryid', 'error');
2100     }
2102     $catcontext = context::instance_by_id($category->contextid);
2103     require_capability('moodle/question:useall', $catcontext);
2105     // Find existing random questions in this category that are
2106     // not used by any quiz.
2107     if ($existingquestions = $DB->get_records_sql(
2108             "SELECT q.id, q.qtype FROM {question} q
2109             WHERE qtype = 'random'
2110                 AND category = ?
2111                 AND " . $DB->sql_compare_text('questiontext') . " = ?
2112                 AND NOT EXISTS (
2113                         SELECT *
2114                           FROM {quiz_slots}
2115                          WHERE questionid = q.id)
2116             ORDER BY id", array($category->id, ($includesubcategories ? '1' : '0')))) {
2117             // Take as many of these as needed.
2118         while (($existingquestion = array_shift($existingquestions)) && $number > 0) {
2119             quiz_add_quiz_question($existingquestion->id, $quiz, $addonpage);
2120             $number -= 1;
2121         }
2122     }
2124     if ($number <= 0) {
2125         return;
2126     }
2128     // More random questions are needed, create them.
2129     for ($i = 0; $i < $number; $i += 1) {
2130         $form = new stdClass();
2131         $form->questiontext = array('text' => ($includesubcategories ? '1' : '0'), 'format' => 0);
2132         $form->category = $category->id . ',' . $category->contextid;
2133         $form->defaultmark = 1;
2134         $form->hidden = 1;
2135         $form->stamp = make_unique_id_code(); // Set the unique code (not to be changed).
2136         $question = new stdClass();
2137         $question->qtype = 'random';
2138         $question = question_bank::get_qtype('random')->save_question($question, $form);
2139         if (!isset($question->id)) {
2140             print_error('cannotinsertrandomquestion', 'quiz');
2141         }
2142         quiz_add_quiz_question($question->id, $quiz, $addonpage);
2143     }
2146 /**
2147  * Mark the activity completed (if required) and trigger the course_module_viewed event.
2148  *
2149  * @param  stdClass $quiz       quiz object
2150  * @param  stdClass $course     course object
2151  * @param  stdClass $cm         course module object
2152  * @param  stdClass $context    context object
2153  * @since Moodle 3.1
2154  */
2155 function quiz_view($quiz, $course, $cm, $context) {
2157     $params = array(
2158         'objectid' => $quiz->id,
2159         'context' => $context
2160     );
2162     $event = \mod_quiz\event\course_module_viewed::create($params);
2163     $event->add_record_snapshot('quiz', $quiz);
2164     $event->trigger();
2166     // Completion.
2167     $completion = new completion_info($course);
2168     $completion->set_module_viewed($cm);
2171 /**
2172  * Validate permissions for creating a new attempt and start a new preview attempt if required.
2173  *
2174  * @param  quiz $quizobj quiz object
2175  * @param  quiz_access_manager $accessmanager quiz access manager
2176  * @param  bool $forcenew whether was required to start a new preview attempt
2177  * @param  int $page page to jump to in the attempt
2178  * @param  bool $redirect whether to redirect or throw exceptions (for web or ws usage)
2179  * @return array an array containing the attempt information, access error messages and the page to jump to in the attempt
2180  * @throws moodle_quiz_exception
2181  * @since Moodle 3.1
2182  */
2183 function quiz_validate_new_attempt(quiz $quizobj, quiz_access_manager $accessmanager, $forcenew, $page, $redirect) {
2184     global $DB, $USER;
2185     $timenow = time();
2187     if ($quizobj->is_preview_user() && $forcenew) {
2188         $accessmanager->current_attempt_finished();
2189     }
2191     // Check capabilities.
2192     if (!$quizobj->is_preview_user()) {
2193         $quizobj->require_capability('mod/quiz:attempt');
2194     }
2196     // Check to see if a new preview was requested.
2197     if ($quizobj->is_preview_user() && $forcenew) {
2198         // To force the creation of a new preview, we mark the current attempt (if any)
2199         // as finished. It will then automatically be deleted below.
2200         $DB->set_field('quiz_attempts', 'state', quiz_attempt::FINISHED,
2201                 array('quiz' => $quizobj->get_quizid(), 'userid' => $USER->id));
2202     }
2204     // Look for an existing attempt.
2205     $attempts = quiz_get_user_attempts($quizobj->get_quizid(), $USER->id, 'all', true);
2206     $lastattempt = end($attempts);
2208     $attemptnumber = null;
2209     // If an in-progress attempt exists, check password then redirect to it.
2210     if ($lastattempt && ($lastattempt->state == quiz_attempt::IN_PROGRESS ||
2211             $lastattempt->state == quiz_attempt::OVERDUE)) {
2212         $currentattemptid = $lastattempt->id;
2213         $messages = $accessmanager->prevent_access();
2215         // If the attempt is now overdue, deal with that.
2216         $quizobj->create_attempt_object($lastattempt)->handle_if_time_expired($timenow, true);
2218         // And, if the attempt is now no longer in progress, redirect to the appropriate place.
2219         if ($lastattempt->state == quiz_attempt::ABANDONED || $lastattempt->state == quiz_attempt::FINISHED) {
2220             if ($redirect) {
2221                 redirect($quizobj->review_url($lastattempt->id));
2222             } else {
2223                 throw new moodle_quiz_exception($quizobj, 'attemptalreadyclosed');
2224             }
2225         }
2227         // If the page number was not explicitly in the URL, go to the current page.
2228         if ($page == -1) {
2229             $page = $lastattempt->currentpage;
2230         }
2232     } else {
2233         while ($lastattempt && $lastattempt->preview) {
2234             $lastattempt = array_pop($attempts);
2235         }
2237         // Get number for the next or unfinished attempt.
2238         if ($lastattempt) {
2239             $attemptnumber = $lastattempt->attempt + 1;
2240         } else {
2241             $lastattempt = false;
2242             $attemptnumber = 1;
2243         }
2244         $currentattemptid = null;
2246         $messages = $accessmanager->prevent_access() +
2247             $accessmanager->prevent_new_attempt(count($attempts), $lastattempt);
2249         if ($page == -1) {
2250             $page = 0;
2251         }
2252     }
2253     return array($currentattemptid, $attemptnumber, $lastattempt, $messages, $page);
2256 /**
2257  * Prepare and start a new attempt deleting the previous preview attempts.
2258  *
2259  * @param  quiz $quizobj quiz object
2260  * @param  int $attemptnumber the attempt number
2261  * @param  object $lastattempt last attempt object
2262  * @return object the new attempt
2263  * @since  Moodle 3.1
2264  */
2265 function quiz_prepare_and_start_new_attempt(quiz $quizobj, $attemptnumber, $lastattempt) {
2266     global $DB, $USER;
2268     // Delete any previous preview attempts belonging to this user.
2269     quiz_delete_previews($quizobj->get_quiz(), $USER->id);
2271     $quba = question_engine::make_questions_usage_by_activity('mod_quiz', $quizobj->get_context());
2272     $quba->set_preferred_behaviour($quizobj->get_quiz()->preferredbehaviour);
2274     // Create the new attempt and initialize the question sessions
2275     $timenow = time(); // Update time now, in case the server is running really slowly.
2276     $attempt = quiz_create_attempt($quizobj, $attemptnumber, $lastattempt, $timenow, $quizobj->is_preview_user());
2278     if (!($quizobj->get_quiz()->attemptonlast && $lastattempt)) {
2279         $attempt = quiz_start_new_attempt($quizobj, $quba, $attempt, $attemptnumber, $timenow);
2280     } else {
2281         $attempt = quiz_start_attempt_built_on_last($quba, $attempt, $lastattempt);
2282     }
2284     $transaction = $DB->start_delegated_transaction();
2286     $attempt = quiz_attempt_save_started($quizobj, $quba, $attempt);
2288     $transaction->allow_commit();
2290     return $attempt;