Merge branch 'MDL-70422' of https://github.com/paulholden/moodle
[moodle.git] / mod / quiz / attemptlib.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  * Back-end code for handling data about quizzes and the current user's attempt.
19  *
20  * There are classes for loading all the information about a quiz and attempts,
21  * and for displaying the navigation panel.
22  *
23  * @package   mod_quiz
24  * @copyright 2008 onwards Tim Hunt
25  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
29 defined('MOODLE_INTERNAL') || die();
32 /**
33  * Class for quiz exceptions. Just saves a couple of arguments on the
34  * constructor for a moodle_exception.
35  *
36  * @copyright 2008 Tim Hunt
37  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38  * @since     Moodle 2.0
39  */
40 class moodle_quiz_exception extends moodle_exception {
41     /**
42      * Constructor.
43      *
44      * @param quiz $quizobj the quiz the error relates to.
45      * @param string $errorcode The name of the string from error.php to print.
46      * @param mixed $a Extra words and phrases that might be required in the error string.
47      * @param string $link The url where the user will be prompted to continue.
48      *      If no url is provided the user will be directed to the site index page.
49      * @param string|null $debuginfo optional debugging information.
50      */
51     public function __construct($quizobj, $errorcode, $a = null, $link = '', $debuginfo = null) {
52         if (!$link) {
53             $link = $quizobj->view_url();
54         }
55         parent::__construct($errorcode, 'quiz', $link, $a, $debuginfo);
56     }
57 }
60 /**
61  * A class encapsulating a quiz and the questions it contains, and making the
62  * information available to scripts like view.php.
63  *
64  * Initially, it only loads a minimal amout of information about each question - loading
65  * extra information only when necessary or when asked. The class tracks which questions
66  * are loaded.
67  *
68  * @copyright  2008 Tim Hunt
69  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
70  * @since      Moodle 2.0
71  */
72 class quiz {
73     /** @var stdClass the course settings from the database. */
74     protected $course;
75     /** @var stdClass the course_module settings from the database. */
76     protected $cm;
77     /** @var stdClass the quiz settings from the database. */
78     protected $quiz;
79     /** @var context the quiz context. */
80     protected $context;
82     /** @var stdClass[] of questions augmented with slot information. */
83     protected $questions = null;
84     /** @var stdClass[] of quiz_section rows. */
85     protected $sections = null;
86     /** @var quiz_access_manager the access manager for this quiz. */
87     protected $accessmanager = null;
88     /** @var bool whether the current user has capability mod/quiz:preview. */
89     protected $ispreviewuser = null;
91     // Constructor =============================================================
92     /**
93      * Constructor, assuming we already have the necessary data loaded.
94      *
95      * @param object $quiz the row from the quiz table.
96      * @param object $cm the course_module object for this quiz.
97      * @param object $course the row from the course table for the course we belong to.
98      * @param bool $getcontext intended for testing - stops the constructor getting the context.
99      */
100     public function __construct($quiz, $cm, $course, $getcontext = true) {
101         $this->quiz = $quiz;
102         $this->cm = $cm;
103         $this->quiz->cmid = $this->cm->id;
104         $this->course = $course;
105         if ($getcontext && !empty($cm->id)) {
106             $this->context = context_module::instance($cm->id);
107         }
108     }
110     /**
111      * Static function to create a new quiz object for a specific user.
112      *
113      * @param int $quizid the the quiz id.
114      * @param int|null $userid the the userid (optional). If passed, relevant overrides are applied.
115      * @return quiz the new quiz object.
116      */
117     public static function create($quizid, $userid = null) {
118         global $DB;
120         $quiz = quiz_access_manager::load_quiz_and_settings($quizid);
121         $course = $DB->get_record('course', array('id' => $quiz->course), '*', MUST_EXIST);
122         $cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id, false, MUST_EXIST);
124         // Update quiz with override information.
125         if ($userid) {
126             $quiz = quiz_update_effective_access($quiz, $userid);
127         }
129         return new quiz($quiz, $cm, $course);
130     }
132     /**
133      * Create a {@link quiz_attempt} for an attempt at this quiz.
134      *
135      * @param object $attemptdata row from the quiz_attempts table.
136      * @return quiz_attempt the new quiz_attempt object.
137      */
138     public function create_attempt_object($attemptdata) {
139         return new quiz_attempt($attemptdata, $this->quiz, $this->cm, $this->course);
140     }
142     // Functions for loading more data =========================================
144     /**
145      * Load just basic information about all the questions in this quiz.
146      */
147     public function preload_questions() {
148         $this->questions = question_preload_questions(null,
149                 'slot.maxmark, slot.id AS slotid, slot.slot, slot.page,
150                  slot.questioncategoryid AS randomfromcategory,
151                  slot.includingsubcategories AS randomincludingsubcategories',
152                 '{quiz_slots} slot ON slot.quizid = :quizid AND q.id = slot.questionid',
153                 array('quizid' => $this->quiz->id), 'slot.slot');
154     }
156     /**
157      * Fully load some or all of the questions for this quiz. You must call
158      * {@link preload_questions()} first.
159      *
160      * @param array|null $questionids question ids of the questions to load. null for all.
161      */
162     public function load_questions($questionids = null) {
163         if ($this->questions === null) {
164             throw new coding_exception('You must call preload_questions before calling load_questions.');
165         }
166         if (is_null($questionids)) {
167             $questionids = array_keys($this->questions);
168         }
169         $questionstoprocess = array();
170         foreach ($questionids as $id) {
171             if (array_key_exists($id, $this->questions)) {
172                 $questionstoprocess[$id] = $this->questions[$id];
173             }
174         }
175         get_question_options($questionstoprocess);
176     }
178     /**
179      * Get an instance of the {@link \mod_quiz\structure} class for this quiz.
180      * @return \mod_quiz\structure describes the questions in the quiz.
181      */
182     public function get_structure() {
183         return \mod_quiz\structure::create_for_quiz($this);
184     }
186     // Simple getters ==========================================================
187     /**
188      * Get the id of the course this quiz belongs to.
189      *
190      * @return int the course id.
191      */
192     public function get_courseid() {
193         return $this->course->id;
194     }
196     /**
197      * Get the course settings object that this quiz belongs to.
198      *
199      * @return object the row of the course table.
200      */
201     public function get_course() {
202         return $this->course;
203     }
205     /**
206      * Get this quiz's id (in the quiz table).
207      *
208      * @return int the quiz id.
209      */
210     public function get_quizid() {
211         return $this->quiz->id;
212     }
214     /**
215      * Get the quiz settings object.
216      *
217      * @return stdClass the row of the quiz table.
218      */
219     public function get_quiz() {
220         return $this->quiz;
221     }
223     /**
224      * Get the quiz name.
225      *
226      * @return string the name of this quiz.
227      */
228     public function get_quiz_name() {
229         return $this->quiz->name;
230     }
232     /**
233      * Get the navigation method in use.
234      *
235      * @return int QUIZ_NAVMETHOD_FREE or QUIZ_NAVMETHOD_SEQ.
236      */
237     public function get_navigation_method() {
238         return $this->quiz->navmethod;
239     }
241     /** @return int the number of attempts allowed at this quiz (0 = infinite). */
242     public function get_num_attempts_allowed() {
243         return $this->quiz->attempts;
244     }
246     /**
247      * Get the course-module id for this quiz.
248      *
249      * @return int the course_module id.
250      */
251     public function get_cmid() {
252         return $this->cm->id;
253     }
255     /**
256      * Get the course-module object for this quiz.
257      *
258      * @return object the course_module object.
259      */
260     public function get_cm() {
261         return $this->cm;
262     }
264     /**
265      * Get the quiz context.
266      *
267      * @return context the module context for this quiz.
268      */
269     public function get_context() {
270         return $this->context;
271     }
273     /**
274      * @return bool wether the current user is someone who previews the quiz,
275      * rather than attempting it.
276      */
277     public function is_preview_user() {
278         if (is_null($this->ispreviewuser)) {
279             $this->ispreviewuser = has_capability('mod/quiz:preview', $this->context);
280         }
281         return $this->ispreviewuser;
282     }
284     /**
285      * Checks user enrollment in the current course.
286      *
287      * @param int $userid the id of the user to check.
288      * @return bool whether the user is enrolled.
289      */
290     public function is_participant($userid) {
291         return is_enrolled($this->get_context(), $userid, 'mod/quiz:attempt', $this->show_only_active_users());
292     }
294     /**
295      * Check is only active users in course should be shown.
296      *
297      * @return bool true if only active users should be shown.
298      */
299     public function show_only_active_users() {
300         return !has_capability('moodle/course:viewsuspendedusers', $this->get_context());
301     }
303     /**
304      * @return bool whether any questions have been added to this quiz.
305      */
306     public function has_questions() {
307         if ($this->questions === null) {
308             $this->preload_questions();
309         }
310         return !empty($this->questions);
311     }
313     /**
314      * @param int $id the question id.
315      * @return stdClass the question object with that id.
316      */
317     public function get_question($id) {
318         return $this->questions[$id];
319     }
321     /**
322      * @param array|null $questionids question ids of the questions to load. null for all.
323      * @return stdClass[] the question data objects.
324      */
325     public function get_questions($questionids = null) {
326         if (is_null($questionids)) {
327             $questionids = array_keys($this->questions);
328         }
329         $questions = array();
330         foreach ($questionids as $id) {
331             if (!array_key_exists($id, $this->questions)) {
332                 throw new moodle_exception('cannotstartmissingquestion', 'quiz', $this->view_url());
333             }
334             $questions[$id] = $this->questions[$id];
335             $this->ensure_question_loaded($id);
336         }
337         return $questions;
338     }
340     /**
341      * Get all the sections in this quiz.
342      *
343      * @return array 0, 1, 2, ... => quiz_sections row from the database.
344      */
345     public function get_sections() {
346         global $DB;
347         if ($this->sections === null) {
348             $this->sections = array_values($DB->get_records('quiz_sections',
349                     array('quizid' => $this->get_quizid()), 'firstslot'));
350         }
351         return $this->sections;
352     }
354     /**
355      * Return quiz_access_manager and instance of the quiz_access_manager class
356      * for this quiz at this time.
357      *
358      * @param int $timenow the current time as a unix timestamp.
359      * @return quiz_access_manager and instance of the quiz_access_manager class
360      *      for this quiz at this time.
361      */
362     public function get_access_manager($timenow) {
363         if (is_null($this->accessmanager)) {
364             $this->accessmanager = new quiz_access_manager($this, $timenow,
365                     has_capability('mod/quiz:ignoretimelimits', $this->context, null, false));
366         }
367         return $this->accessmanager;
368     }
370     /**
371      * Wrapper round the has_capability funciton that automatically passes in the quiz context.
372      *
373      * @param string $capability the name of the capability to check. For example mod/quiz:view.
374      * @param int|null $userid A user id. By default (null) checks the permissions of the current user.
375      * @param bool $doanything If false, ignore effect of admin role assignment.
376      * @return boolean true if the user has this capability. Otherwise false.
377      */
378     public function has_capability($capability, $userid = null, $doanything = true) {
379         return has_capability($capability, $this->context, $userid, $doanything);
380     }
382     /**
383      * Wrapper round the require_capability function that automatically passes in the quiz context.
384      *
385      * @param string $capability the name of the capability to check. For example mod/quiz:view.
386      * @param int|null $userid A user id. By default (null) checks the permissions of the current user.
387      * @param bool $doanything If false, ignore effect of admin role assignment.
388      */
389     public function require_capability($capability, $userid = null, $doanything = true) {
390         require_capability($capability, $this->context, $userid, $doanything);
391     }
393     // URLs related to this attempt ============================================
394     /**
395      * @return string the URL of this quiz's view page.
396      */
397     public function view_url() {
398         global $CFG;
399         return $CFG->wwwroot . '/mod/quiz/view.php?id=' . $this->cm->id;
400     }
402     /**
403      * @return string the URL of this quiz's edit page.
404      */
405     public function edit_url() {
406         global $CFG;
407         return $CFG->wwwroot . '/mod/quiz/edit.php?cmid=' . $this->cm->id;
408     }
410     /**
411      * @param int $attemptid the id of an attempt.
412      * @param int $page optional page number to go to in the attempt.
413      * @return string the URL of that attempt.
414      */
415     public function attempt_url($attemptid, $page = 0) {
416         global $CFG;
417         $url = $CFG->wwwroot . '/mod/quiz/attempt.php?attempt=' . $attemptid;
418         if ($page) {
419             $url .= '&page=' . $page;
420         }
421         $url .= '&cmid=' . $this->get_cmid();
422         return $url;
423     }
425     /**
426      * Get the URL to start/continue an attempt.
427      *
428      * @param int $page page in the attempt to start on (optional).
429      * @return moodle_url the URL of this quiz's edit page. Needs to be POSTed to with a cmid parameter.
430      */
431     public function start_attempt_url($page = 0) {
432         $params = array('cmid' => $this->cm->id, 'sesskey' => sesskey());
433         if ($page) {
434             $params['page'] = $page;
435         }
436         return new moodle_url('/mod/quiz/startattempt.php', $params);
437     }
439     /**
440      * @param int $attemptid the id of an attempt.
441      * @return string the URL of the review of that attempt.
442      */
443     public function review_url($attemptid) {
444         return new moodle_url('/mod/quiz/review.php', array('attempt' => $attemptid, 'cmid' => $this->get_cmid()));
445     }
447     /**
448      * @param int $attemptid the id of an attempt.
449      * @return string the URL of the review of that attempt.
450      */
451     public function summary_url($attemptid) {
452         return new moodle_url('/mod/quiz/summary.php', array('attempt' => $attemptid, 'cmid' => $this->get_cmid()));
453     }
455     // Bits of content =========================================================
457     /**
458      * @param bool $notused not used.
459      * @return string an empty string.
460      * @deprecated since 3.1. This sort of functionality is now entirely handled by quiz access rules.
461      */
462     public function confirm_start_attempt_message($notused) {
463         debugging('confirm_start_attempt_message is deprecated. ' .
464                 'This sort of functionality is now entirely handled by quiz access rules.');
465         return '';
466     }
468     /**
469      * If $reviewoptions->attempt is false, meaning that students can't review this
470      * attempt at the moment, return an appropriate string explaining why.
471      *
472      * @param int $when One of the mod_quiz_display_options::DURING,
473      *      IMMEDIATELY_AFTER, LATER_WHILE_OPEN or AFTER_CLOSE constants.
474      * @param bool $short if true, return a shorter string.
475      * @return string an appropraite message.
476      */
477     public function cannot_review_message($when, $short = false) {
479         if ($short) {
480             $langstrsuffix = 'short';
481             $dateformat = get_string('strftimedatetimeshort', 'langconfig');
482         } else {
483             $langstrsuffix = '';
484             $dateformat = '';
485         }
487         if ($when == mod_quiz_display_options::DURING ||
488                 $when == mod_quiz_display_options::IMMEDIATELY_AFTER) {
489             return '';
490         } else if ($when == mod_quiz_display_options::LATER_WHILE_OPEN && $this->quiz->timeclose &&
491                 $this->quiz->reviewattempt & mod_quiz_display_options::AFTER_CLOSE) {
492             return get_string('noreviewuntil' . $langstrsuffix, 'quiz',
493                     userdate($this->quiz->timeclose, $dateformat));
494         } else {
495             return get_string('noreview' . $langstrsuffix, 'quiz');
496         }
497     }
499     /**
500      * Probably not used any more, but left for backwards compatibility.
501      *
502      * @param string $title the name of this particular quiz page.
503      * @return string always returns ''.
504      */
505     public function navigation($title) {
506         global $PAGE;
507         $PAGE->navbar->add($title);
508         return '';
509     }
511     // Private methods =========================================================
512     /**
513      * Check that the definition of a particular question is loaded, and if not throw an exception.
514      *
515      * @param int $id a question id.
516      */
517     protected function ensure_question_loaded($id) {
518         if (isset($this->questions[$id]->_partiallyloaded)) {
519             throw new moodle_quiz_exception($this, 'questionnotloaded', $id);
520         }
521     }
523     /**
524      * Return all the question types used in this quiz.
525      *
526      * @param  boolean $includepotential if the quiz include random questions,
527      *      setting this flag to true will make the function to return all the
528      *      possible question types in the random questions category.
529      * @return array a sorted array including the different question types.
530      * @since  Moodle 3.1
531      */
532     public function get_all_question_types_used($includepotential = false) {
533         $questiontypes = array();
535         // To control if we need to look in categories for questions.
536         $qcategories = array();
538         // We must be careful with random questions, if we find a random question we must assume that the quiz may content
539         // any of the questions in the referenced category (or subcategories).
540         foreach ($this->get_questions() as $questiondata) {
541             if ($questiondata->qtype == 'random' and $includepotential) {
542                 $includesubcategories = (bool) $questiondata->questiontext;
543                 if (!isset($qcategories[$questiondata->category])) {
544                     $qcategories[$questiondata->category] = false;
545                 }
546                 if ($includesubcategories) {
547                     $qcategories[$questiondata->category] = true;
548                 }
549             } else {
550                 if (!in_array($questiondata->qtype, $questiontypes)) {
551                     $questiontypes[] = $questiondata->qtype;
552                 }
553             }
554         }
556         if (!empty($qcategories)) {
557             // We have to look for all the question types in these categories.
558             $categoriestolook = array();
559             foreach ($qcategories as $cat => $includesubcats) {
560                 if ($includesubcats) {
561                     $categoriestolook = array_merge($categoriestolook, question_categorylist($cat));
562                 } else {
563                     $categoriestolook[] = $cat;
564                 }
565             }
566             $questiontypesincategories = question_bank::get_all_question_types_in_categories($categoriestolook);
567             $questiontypes = array_merge($questiontypes, $questiontypesincategories);
568         }
569         $questiontypes = array_unique($questiontypes);
570         sort($questiontypes);
572         return $questiontypes;
573     }
577 /**
578  * This class extends the quiz class to hold data about the state of a particular attempt,
579  * in addition to the data about the quiz.
580  *
581  * @copyright  2008 Tim Hunt
582  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
583  * @since      Moodle 2.0
584  */
585 class quiz_attempt {
587     /** @var string to identify the in progress state. */
588     const IN_PROGRESS = 'inprogress';
589     /** @var string to identify the overdue state. */
590     const OVERDUE     = 'overdue';
591     /** @var string to identify the finished state. */
592     const FINISHED    = 'finished';
593     /** @var string to identify the abandoned state. */
594     const ABANDONED   = 'abandoned';
596     /** @var int maximum number of slots in the quiz for the review page to default to show all. */
597     const MAX_SLOTS_FOR_DEFAULT_REVIEW_SHOW_ALL = 50;
599     /** @var quiz object containing the quiz settings. */
600     protected $quizobj;
602     /** @var stdClass the quiz_attempts row. */
603     protected $attempt;
605     /** @var question_usage_by_activity the question usage for this quiz attempt. */
606     protected $quba;
608     /**
609      * @var array of slot information. These objects contain ->slot (int),
610      *      ->requireprevious (bool), ->questionids (int) the original question for random questions,
611      *      ->firstinsection (bool), ->section (stdClass from $this->sections).
612      *      This does not contain page - get that from {@link get_question_page()} -
613      *      or maxmark - get that from $this->quba.
614      */
615     protected $slots;
617     /** @var array of quiz_sections rows, with a ->lastslot field added. */
618     protected $sections;
620     /** @var array page no => array of slot numbers on the page in order. */
621     protected $pagelayout;
623     /** @var array slot => displayed question number for this slot. (E.g. 1, 2, 3 or 'i'.) */
624     protected $questionnumbers;
626     /** @var array slot => page number for this slot. */
627     protected $questionpages;
629     /** @var mod_quiz_display_options cache for the appropriate review options. */
630     protected $reviewoptions = null;
632     // Constructor =============================================================
633     /**
634      * Constructor assuming we already have the necessary data loaded.
635      *
636      * @param object $attempt the row of the quiz_attempts table.
637      * @param object $quiz the quiz object for this attempt and user.
638      * @param object $cm the course_module object for this quiz.
639      * @param object $course the row from the course table for the course we belong to.
640      * @param bool $loadquestions (optional) if true, the default, load all the details
641      *      of the state of each question. Else just set up the basic details of the attempt.
642      */
643     public function __construct($attempt, $quiz, $cm, $course, $loadquestions = true) {
644         $this->attempt = $attempt;
645         $this->quizobj = new quiz($quiz, $cm, $course);
647         if ($loadquestions) {
648             $this->load_questions();
649         }
650     }
652     /**
653      * Used by {create()} and {create_from_usage_id()}.
654      *
655      * @param array $conditions passed to $DB->get_record('quiz_attempts', $conditions).
656      * @return quiz_attempt the desired instance of this class.
657      */
658     protected static function create_helper($conditions) {
659         global $DB;
661         $attempt = $DB->get_record('quiz_attempts', $conditions, '*', MUST_EXIST);
662         $quiz = quiz_access_manager::load_quiz_and_settings($attempt->quiz);
663         $course = $DB->get_record('course', array('id' => $quiz->course), '*', MUST_EXIST);
664         $cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id, false, MUST_EXIST);
666         // Update quiz with override information.
667         $quiz = quiz_update_effective_access($quiz, $attempt->userid);
669         return new quiz_attempt($attempt, $quiz, $cm, $course);
670     }
672     /**
673      * Static function to create a new quiz_attempt object given an attemptid.
674      *
675      * @param int $attemptid the attempt id.
676      * @return quiz_attempt the new quiz_attempt object
677      */
678     public static function create($attemptid) {
679         return self::create_helper(array('id' => $attemptid));
680     }
682     /**
683      * Static function to create a new quiz_attempt object given a usage id.
684      *
685      * @param int $usageid the attempt usage id.
686      * @return quiz_attempt the new quiz_attempt object
687      */
688     public static function create_from_usage_id($usageid) {
689         return self::create_helper(array('uniqueid' => $usageid));
690     }
692     /**
693      * @param string $state one of the state constants like IN_PROGRESS.
694      * @return string the human-readable state name.
695      */
696     public static function state_name($state) {
697         return quiz_attempt_state_name($state);
698     }
700     /**
701      * This method can be called later if the object was constructed with $loadqusetions = false.
702      */
703     public function load_questions() {
704         global $DB;
706         if (isset($this->quba)) {
707             throw new coding_exception('This quiz attempt has already had the questions loaded.');
708         }
710         $this->quba = question_engine::load_questions_usage_by_activity($this->attempt->uniqueid);
711         $this->slots = $DB->get_records('quiz_slots',
712                 array('quizid' => $this->get_quizid()), 'slot',
713                 'slot, id, requireprevious, questionid, includingsubcategories');
714         $this->sections = array_values($DB->get_records('quiz_sections',
715                 array('quizid' => $this->get_quizid()), 'firstslot'));
717         $this->link_sections_and_slots();
718         $this->determine_layout();
719         $this->number_questions();
720     }
722     /**
723      * Let each slot know which section it is part of.
724      */
725     protected function link_sections_and_slots() {
726         foreach ($this->sections as $i => $section) {
727             if (isset($this->sections[$i + 1])) {
728                 $section->lastslot = $this->sections[$i + 1]->firstslot - 1;
729             } else {
730                 $section->lastslot = count($this->slots);
731             }
732             for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
733                 $this->slots[$slot]->section = $section;
734             }
735         }
736     }
738     /**
739      * Parse attempt->layout to populate the other arrays the represent the layout.
740      */
741     protected function determine_layout() {
742         $this->pagelayout = array();
744         // Break up the layout string into pages.
745         $pagelayouts = explode(',0', $this->attempt->layout);
747         // Strip off any empty last page (normally there is one).
748         if (end($pagelayouts) == '') {
749             array_pop($pagelayouts);
750         }
752         // File the ids into the arrays.
753         // Tracking which is the first slot in each section in this attempt is
754         // trickier than you might guess, since the slots in this section
755         // may be shuffled, so $section->firstslot (the lowest numbered slot in
756         // the section) may not be the first one.
757         $unseensections = $this->sections;
758         $this->pagelayout = array();
759         foreach ($pagelayouts as $page => $pagelayout) {
760             $pagelayout = trim($pagelayout, ',');
761             if ($pagelayout == '') {
762                 continue;
763             }
764             $this->pagelayout[$page] = explode(',', $pagelayout);
765             foreach ($this->pagelayout[$page] as $slot) {
766                 $sectionkey = array_search($this->slots[$slot]->section, $unseensections);
767                 if ($sectionkey !== false) {
768                     $this->slots[$slot]->firstinsection = true;
769                     unset($unseensections[$sectionkey]);
770                 } else {
771                     $this->slots[$slot]->firstinsection = false;
772                 }
773             }
774         }
775     }
777     /**
778      * Work out the number to display for each question/slot.
779      */
780     protected function number_questions() {
781         $number = 1;
782         foreach ($this->pagelayout as $page => $slots) {
783             foreach ($slots as $slot) {
784                 if ($length = $this->is_real_question($slot)) {
785                     $this->questionnumbers[$slot] = $number;
786                     $number += $length;
787                 } else {
788                     $this->questionnumbers[$slot] = get_string('infoshort', 'quiz');
789                 }
790                 $this->questionpages[$slot] = $page;
791             }
792         }
793     }
795     /**
796      * If the given page number is out of range (before the first page, or after
797      * the last page, chnage it to be within range).
798      *
799      * @param int $page the requested page number.
800      * @return int a safe page number to use.
801      */
802     public function force_page_number_into_range($page) {
803         return min(max($page, 0), count($this->pagelayout) - 1);
804     }
806     // Simple getters ==========================================================
807     public function get_quiz() {
808         return $this->quizobj->get_quiz();
809     }
811     public function get_quizobj() {
812         return $this->quizobj;
813     }
815     /** @return int the course id. */
816     public function get_courseid() {
817         return $this->quizobj->get_courseid();
818     }
820     /**
821      * Get the course settings object.
822      *
823      * @return stdClass the course settings object.
824      */
825     public function get_course() {
826         return $this->quizobj->get_course();
827     }
829     /** @return int the quiz id. */
830     public function get_quizid() {
831         return $this->quizobj->get_quizid();
832     }
834     /** @return string the name of this quiz. */
835     public function get_quiz_name() {
836         return $this->quizobj->get_quiz_name();
837     }
839     /** @return int the quiz navigation method. */
840     public function get_navigation_method() {
841         return $this->quizobj->get_navigation_method();
842     }
844     /** @return object the course_module object. */
845     public function get_cm() {
846         return $this->quizobj->get_cm();
847     }
849     /**
850      * Get the course-module id.
851      *
852      * @return int the course_module id.
853      */
854     public function get_cmid() {
855         return $this->quizobj->get_cmid();
856     }
858     /**
859      * @return bool whether the current user is someone who previews the quiz,
860      * rather than attempting it.
861      */
862     public function is_preview_user() {
863         return $this->quizobj->is_preview_user();
864     }
866     /** @return int the number of attempts allowed at this quiz (0 = infinite). */
867     public function get_num_attempts_allowed() {
868         return $this->quizobj->get_num_attempts_allowed();
869     }
871     /** @return int number fo pages in this quiz. */
872     public function get_num_pages() {
873         return count($this->pagelayout);
874     }
876     /**
877      * @param int $timenow the current time as a unix timestamp.
878      * @return quiz_access_manager and instance of the quiz_access_manager class
879      *      for this quiz at this time.
880      */
881     public function get_access_manager($timenow) {
882         return $this->quizobj->get_access_manager($timenow);
883     }
885     /** @return int the attempt id. */
886     public function get_attemptid() {
887         return $this->attempt->id;
888     }
890     /** @return int the attempt unique id. */
891     public function get_uniqueid() {
892         return $this->attempt->uniqueid;
893     }
895     /** @return object the row from the quiz_attempts table. */
896     public function get_attempt() {
897         return $this->attempt;
898     }
900     /** @return int the number of this attemp (is it this user's first, second, ... attempt). */
901     public function get_attempt_number() {
902         return $this->attempt->attempt;
903     }
905     /** @return string one of the quiz_attempt::IN_PROGRESS, FINISHED, OVERDUE or ABANDONED constants. */
906     public function get_state() {
907         return $this->attempt->state;
908     }
910     /** @return int the id of the user this attempt belongs to. */
911     public function get_userid() {
912         return $this->attempt->userid;
913     }
915     /** @return int the current page of the attempt. */
916     public function get_currentpage() {
917         return $this->attempt->currentpage;
918     }
920     public function get_sum_marks() {
921         return $this->attempt->sumgrades;
922     }
924     /**
925      * @return bool whether this attempt has been finished (true) or is still
926      *     in progress (false). Be warned that this is not just state == self::FINISHED,
927      *     it also includes self::ABANDONED.
928      */
929     public function is_finished() {
930         return $this->attempt->state == self::FINISHED || $this->attempt->state == self::ABANDONED;
931     }
933     /** @return bool whether this attempt is a preview attempt. */
934     public function is_preview() {
935         return $this->attempt->preview;
936     }
938     /**
939      * Is this someone dealing with their own attempt or preview?
940      *
941      * @return bool true => own attempt/preview. false => reviewing someone else's.
942      */
943     public function is_own_attempt() {
944         global $USER;
945         return $this->attempt->userid == $USER->id;
946     }
948     /**
949      * @return bool whether this attempt is a preview belonging to the current user.
950      */
951     public function is_own_preview() {
952         return $this->is_own_attempt() &&
953                 $this->is_preview_user() && $this->attempt->preview;
954     }
956     /**
957      * Is the current user allowed to review this attempt. This applies when
958      * {@link is_own_attempt()} returns false.
959      *
960      * @return bool whether the review should be allowed.
961      */
962     public function is_review_allowed() {
963         if (!$this->has_capability('mod/quiz:viewreports')) {
964             return false;
965         }
967         $cm = $this->get_cm();
968         if ($this->has_capability('moodle/site:accessallgroups') ||
969                 groups_get_activity_groupmode($cm) != SEPARATEGROUPS) {
970             return true;
971         }
973         // Check the users have at least one group in common.
974         $teachersgroups = groups_get_activity_allowed_groups($cm);
975         $studentsgroups = groups_get_all_groups(
976                 $cm->course, $this->attempt->userid, $cm->groupingid);
977         return $teachersgroups && $studentsgroups &&
978                 array_intersect(array_keys($teachersgroups), array_keys($studentsgroups));
979     }
981     /**
982      * Has the student, in this attempt, engaged with the quiz in a non-trivial way?
983      *
984      * That is, is there any question worth a non-zero number of marks, where
985      * the student has made some response that we have saved?
986      *
987      * @return bool true if we have saved a response for at least one graded question.
988      */
989     public function has_response_to_at_least_one_graded_question() {
990         foreach ($this->quba->get_attempt_iterator() as $qa) {
991             if ($qa->get_max_mark() == 0) {
992                 continue;
993             }
994             if ($qa->get_num_steps() > 1) {
995                 return true;
996             }
997         }
998         return false;
999     }
1001     /**
1002      * Get extra summary information about this attempt.
1003      *
1004      * Some behaviours may be able to provide interesting summary information
1005      * about the attempt as a whole, and this method provides access to that data.
1006      * To see how this works, try setting a quiz to one of the CBM behaviours,
1007      * and then look at the extra information displayed at the top of the quiz
1008      * review page once you have sumitted an attempt.
1009      *
1010      * In the return value, the array keys are identifiers of the form
1011      * qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
1012      * The values are arrays with two items, title and content. Each of these
1013      * will be either a string, or a renderable.
1014      *
1015      * @param question_display_options $options the display options for this quiz attempt at this time.
1016      * @return array as described above.
1017      */
1018     public function get_additional_summary_data(question_display_options $options) {
1019         return $this->quba->get_summary_information($options);
1020     }
1022     /**
1023      * Get the overall feedback corresponding to a particular mark.
1024      *
1025      * @param number $grade a particular grade.
1026      * @return string the feedback.
1027      */
1028     public function get_overall_feedback($grade) {
1029         return quiz_feedback_for_grade($grade, $this->get_quiz(),
1030                 $this->quizobj->get_context());
1031     }
1033     /**
1034      * Wrapper round the has_capability funciton that automatically passes in the quiz context.
1035      *
1036      * @param string $capability the name of the capability to check. For example mod/forum:view.
1037      * @param int|null $userid A user id. By default (null) checks the permissions of the current user.
1038      * @param bool $doanything If false, ignore effect of admin role assignment.
1039      * @return boolean true if the user has this capability. Otherwise false.
1040      */
1041     public function has_capability($capability, $userid = null, $doanything = true) {
1042         return $this->quizobj->has_capability($capability, $userid, $doanything);
1043     }
1045     /**
1046      * Wrapper round the require_capability function that automatically passes in the quiz context.
1047      *
1048      * @param string $capability the name of the capability to check. For example mod/forum:view.
1049      * @param int|null $userid A user id. By default (null) checks the permissions of the current user.
1050      * @param bool $doanything If false, ignore effect of admin role assignment.
1051      */
1052     public function require_capability($capability, $userid = null, $doanything = true) {
1053         $this->quizobj->require_capability($capability, $userid, $doanything);
1054     }
1056     /**
1057      * Check the appropriate capability to see whether this user may review their own attempt.
1058      * If not, prints an error.
1059      */
1060     public function check_review_capability() {
1061         if ($this->get_attempt_state() == mod_quiz_display_options::IMMEDIATELY_AFTER) {
1062             $capability = 'mod/quiz:attempt';
1063         } else {
1064             $capability = 'mod/quiz:reviewmyattempts';
1065         }
1067         // These next tests are in a slighly funny order. The point is that the
1068         // common and most performance-critical case is students attempting a quiz
1069         // so we want to check that permisison first.
1071         if ($this->has_capability($capability)) {
1072             // User has the permission that lets you do the quiz as a student. Fine.
1073             return;
1074         }
1076         if ($this->has_capability('mod/quiz:viewreports') ||
1077                 $this->has_capability('mod/quiz:preview')) {
1078             // User has the permission that lets teachers review. Fine.
1079             return;
1080         }
1082         // They should not be here. Trigger the standard no-permission error
1083         // but using the name of the student capability.
1084         // We know this will fail. We just want the stadard exception thown.
1085         $this->require_capability($capability);
1086     }
1088     /**
1089      * Checks whether a user may navigate to a particular slot.
1090      *
1091      * @param int $slot the target slot (currently does not affect the answer).
1092      * @return bool true if the navigation should be allowed.
1093      */
1094     public function can_navigate_to($slot) {
1095         if ($this->attempt->state == self::OVERDUE) {
1096             // When the attempt is overdue, students can only see the
1097             // attempt summary page and cannot navigate anywhere else.
1098             return false;
1099         }
1101         switch ($this->get_navigation_method()) {
1102             case QUIZ_NAVMETHOD_FREE:
1103                 return true;
1104                 break;
1105             case QUIZ_NAVMETHOD_SEQ:
1106                 return false;
1107                 break;
1108         }
1109         return true;
1110     }
1112     /**
1113      * @return int one of the mod_quiz_display_options::DURING,
1114      *      IMMEDIATELY_AFTER, LATER_WHILE_OPEN or AFTER_CLOSE constants.
1115      */
1116     public function get_attempt_state() {
1117         return quiz_attempt_state($this->get_quiz(), $this->attempt);
1118     }
1120     /**
1121      * Wrapper that the correct mod_quiz_display_options for this quiz at the
1122      * moment.
1123      *
1124      * @param bool $reviewing true for options when reviewing, false for when attempting.
1125      * @return question_display_options the render options for this user on this attempt.
1126      */
1127     public function get_display_options($reviewing) {
1128         if ($reviewing) {
1129             if (is_null($this->reviewoptions)) {
1130                 $this->reviewoptions = quiz_get_review_options($this->get_quiz(),
1131                         $this->attempt, $this->quizobj->get_context());
1132                 if ($this->is_own_preview()) {
1133                     // It should  always be possible for a teacher to review their
1134                     // own preview irrespective of the review options settings.
1135                     $this->reviewoptions->attempt = true;
1136                 }
1137             }
1138             return $this->reviewoptions;
1140         } else {
1141             $options = mod_quiz_display_options::make_from_quiz($this->get_quiz(),
1142                     mod_quiz_display_options::DURING);
1143             $options->flags = quiz_get_flag_option($this->attempt, $this->quizobj->get_context());
1144             return $options;
1145         }
1146     }
1148     /**
1149      * Wrapper that the correct mod_quiz_display_options for this quiz at the
1150      * moment.
1151      *
1152      * @param bool $reviewing true for review page, else attempt page.
1153      * @param int $slot which question is being displayed.
1154      * @param moodle_url $thispageurl to return to after the editing form is
1155      *      submitted or cancelled. If null, no edit link will be generated.
1156      *
1157      * @return question_display_options the render options for this user on this
1158      *      attempt, with extra info to generate an edit link, if applicable.
1159      */
1160     public function get_display_options_with_edit_link($reviewing, $slot, $thispageurl) {
1161         $options = clone($this->get_display_options($reviewing));
1163         if (!$thispageurl) {
1164             return $options;
1165         }
1167         if (!($reviewing || $this->is_preview())) {
1168             return $options;
1169         }
1171         $question = $this->quba->get_question($slot, false);
1172         if (!question_has_capability_on($question, 'edit', $question->category)) {
1173             return $options;
1174         }
1176         $options->editquestionparams['cmid'] = $this->get_cmid();
1177         $options->editquestionparams['returnurl'] = $thispageurl;
1179         return $options;
1180     }
1182     /**
1183      * @param int $page page number
1184      * @return bool true if this is the last page of the quiz.
1185      */
1186     public function is_last_page($page) {
1187         return $page == count($this->pagelayout) - 1;
1188     }
1190     /**
1191      * Return the list of slot numbers for either a given page of the quiz, or for the
1192      * whole quiz.
1193      *
1194      * @param mixed $page string 'all' or integer page number.
1195      * @return array the requested list of slot numbers.
1196      */
1197     public function get_slots($page = 'all') {
1198         if ($page === 'all') {
1199             $numbers = array();
1200             foreach ($this->pagelayout as $numbersonpage) {
1201                 $numbers = array_merge($numbers, $numbersonpage);
1202             }
1203             return $numbers;
1204         } else {
1205             return $this->pagelayout[$page];
1206         }
1207     }
1209     /**
1210      * Return the list of slot numbers for either a given page of the quiz, or for the
1211      * whole quiz.
1212      *
1213      * @param mixed $page string 'all' or integer page number.
1214      * @return array the requested list of slot numbers.
1215      */
1216     public function get_active_slots($page = 'all') {
1217         $activeslots = array();
1218         foreach ($this->get_slots($page) as $slot) {
1219             if (!$this->is_blocked_by_previous_question($slot)) {
1220                 $activeslots[] = $slot;
1221             }
1222         }
1223         return $activeslots;
1224     }
1226     /**
1227      * Helper method for unit tests. Get the underlying question usage object.
1228      *
1229      * @return question_usage_by_activity the usage.
1230      */
1231     public function get_question_usage() {
1232         if (!(PHPUNIT_TEST || defined('BEHAT_TEST'))) {
1233             throw new coding_exception('get_question_usage is only for use in unit tests. ' .
1234                     'For other operations, use the quiz_attempt api, or extend it properly.');
1235         }
1236         return $this->quba;
1237     }
1239     /**
1240      * Get the question_attempt object for a particular question in this attempt.
1241      *
1242      * @param int $slot the number used to identify this question within this attempt.
1243      * @return question_attempt the requested question_attempt.
1244      */
1245     public function get_question_attempt($slot) {
1246         return $this->quba->get_question_attempt($slot);
1247     }
1249     /**
1250      * Get all the question_attempt objects that have ever appeared in a given slot.
1251      *
1252      * This relates to the 'Try another question like this one' feature.
1253      *
1254      * @param int $slot the number used to identify this question within this attempt.
1255      * @return question_attempt[] the attempts.
1256      */
1257     public function all_question_attempts_originally_in_slot($slot) {
1258         $qas = array();
1259         foreach ($this->quba->get_attempt_iterator() as $qa) {
1260             if ($qa->get_metadata('originalslot') == $slot) {
1261                 $qas[] = $qa;
1262             }
1263         }
1264         $qas[] = $this->quba->get_question_attempt($slot);
1265         return $qas;
1266     }
1268     /**
1269      * Is a particular question in this attempt a real question, or something like a description.
1270      *
1271      * @param int $slot the number used to identify this question within this attempt.
1272      * @return int whether that question is a real question. Actually returns the
1273      *     question length, which could theoretically be greater than one.
1274      */
1275     public function is_real_question($slot) {
1276         return $this->quba->get_question($slot, false)->length;
1277     }
1279     /**
1280      * Is a particular question in this attempt a real question, or something like a description.
1281      *
1282      * @param int $slot the number used to identify this question within this attempt.
1283      * @return bool whether that question is a real question.
1284      */
1285     public function is_question_flagged($slot) {
1286         return $this->quba->get_question_attempt($slot)->is_flagged();
1287     }
1289     /**
1290      * Checks whether the question in this slot requires the previous
1291      * question to have been completed.
1292      *
1293      * @param int $slot the number used to identify this question within this attempt.
1294      * @return bool whether the previous question must have been completed before
1295      *      this one can be seen.
1296      */
1297     public function is_blocked_by_previous_question($slot) {
1298         return $slot > 1 && isset($this->slots[$slot]) && $this->slots[$slot]->requireprevious &&
1299                 !$this->slots[$slot]->section->shufflequestions &&
1300                 !$this->slots[$slot - 1]->section->shufflequestions &&
1301                 $this->get_navigation_method() != QUIZ_NAVMETHOD_SEQ &&
1302                 !$this->get_question_state($slot - 1)->is_finished() &&
1303                 $this->quba->can_question_finish_during_attempt($slot - 1);
1304     }
1306     /**
1307      * Is it possible for this question to be re-started within this attempt?
1308      *
1309      * @param int $slot the number used to identify this question within this attempt.
1310      * @return bool whether the student should be given the option to restart this question now.
1311      */
1312     public function can_question_be_redone_now($slot) {
1313         return $this->get_quiz()->canredoquestions && !$this->is_finished() &&
1314                 $this->get_question_state($slot)->is_finished();
1315     }
1317     /**
1318      * Given a slot in this attempt, which may or not be a redone question, return the original slot.
1319      *
1320      * @param int $slot identifies a particular question in this attempt.
1321      * @return int the slot where this question was originally.
1322      */
1323     public function get_original_slot($slot) {
1324         $originalslot = $this->quba->get_question_attempt_metadata($slot, 'originalslot');
1325         if ($originalslot) {
1326             return $originalslot;
1327         } else {
1328             return $slot;
1329         }
1330     }
1332     /**
1333      * Get the displayed question number for a slot.
1334      *
1335      * @param int $slot the number used to identify this question within this attempt.
1336      * @return string the displayed question number for the question in this slot.
1337      *      For example '1', '2', '3' or 'i'.
1338      */
1339     public function get_question_number($slot) {
1340         return $this->questionnumbers[$slot];
1341     }
1343     /**
1344      * If the section heading, if any, that should come just before this slot.
1345      *
1346      * @param int $slot identifies a particular question in this attempt.
1347      * @return string the required heading, or null if there is not one here.
1348      */
1349     public function get_heading_before_slot($slot) {
1350         if ($this->slots[$slot]->firstinsection) {
1351             return $this->slots[$slot]->section->heading;
1352         } else {
1353             return null;
1354         }
1355     }
1357     /**
1358      * Return the page of the quiz where this question appears.
1359      *
1360      * @param int $slot the number used to identify this question within this attempt.
1361      * @return int the page of the quiz this question appears on.
1362      */
1363     public function get_question_page($slot) {
1364         return $this->questionpages[$slot];
1365     }
1367     /**
1368      * Return the grade obtained on a particular question, if the user is permitted
1369      * to see it. You must previously have called load_question_states to load the
1370      * state data about this question.
1371      *
1372      * @param int $slot the number used to identify this question within this attempt.
1373      * @return string the formatted grade, to the number of decimal places specified
1374      *      by the quiz.
1375      */
1376     public function get_question_name($slot) {
1377         return $this->quba->get_question($slot, false)->name;
1378     }
1380     /**
1381      * Return the {@link question_state} that this question is in.
1382      *
1383      * @param int $slot the number used to identify this question within this attempt.
1384      * @return question_state the state this question is in.
1385      */
1386     public function get_question_state($slot) {
1387         return $this->quba->get_question_state($slot);
1388     }
1390     /**
1391      * Return the grade obtained on a particular question, if the user is permitted
1392      * to see it. You must previously have called load_question_states to load the
1393      * state data about this question.
1394      *
1395      * @param int $slot the number used to identify this question within this attempt.
1396      * @param bool $showcorrectness Whether right/partial/wrong states should
1397      *      be distinguished.
1398      * @return string the formatted grade, to the number of decimal places specified
1399      *      by the quiz.
1400      */
1401     public function get_question_status($slot, $showcorrectness) {
1402         return $this->quba->get_question_state_string($slot, $showcorrectness);
1403     }
1405     /**
1406      * Return the grade obtained on a particular question, if the user is permitted
1407      * to see it. You must previously have called load_question_states to load the
1408      * state data about this question.
1409      *
1410      * @param int $slot the number used to identify this question within this attempt.
1411      * @param bool $showcorrectness Whether right/partial/wrong states should
1412      *      be distinguished.
1413      * @return string class name for this state.
1414      */
1415     public function get_question_state_class($slot, $showcorrectness) {
1416         return $this->quba->get_question_state_class($slot, $showcorrectness);
1417     }
1419     /**
1420      * Return the grade obtained on a particular question.
1421      *
1422      * You must previously have called load_question_states to load the state
1423      * data about this question.
1424      *
1425      * @param int $slot the number used to identify this question within this attempt.
1426      * @return string the formatted grade, to the number of decimal places specified by the quiz.
1427      */
1428     public function get_question_mark($slot) {
1429         return quiz_format_question_grade($this->get_quiz(), $this->quba->get_question_mark($slot));
1430     }
1432     /**
1433      * Get the time of the most recent action performed on a question.
1434      *
1435      * @param int $slot the number used to identify this question within this usage.
1436      * @return int timestamp.
1437      */
1438     public function get_question_action_time($slot) {
1439         return $this->quba->get_question_action_time($slot);
1440     }
1442     /**
1443      * Return the question type name for a given slot within the current attempt.
1444      *
1445      * @param int $slot the number used to identify this question within this attempt.
1446      * @return string the question type name.
1447      * @since  Moodle 3.1
1448      */
1449     public function get_question_type_name($slot) {
1450         return $this->quba->get_question($slot, false)->get_type_name();
1451     }
1453     /**
1454      * Get the time remaining for an in-progress attempt, if the time is short
1455      * enough that it would be worth showing a timer.
1456      *
1457      * @param int $timenow the time to consider as 'now'.
1458      * @return int|false the number of seconds remaining for this attempt.
1459      *      False if there is no limit.
1460      */
1461     public function get_time_left_display($timenow) {
1462         if ($this->attempt->state != self::IN_PROGRESS) {
1463             return false;
1464         }
1465         return $this->get_access_manager($timenow)->get_time_left_display($this->attempt, $timenow);
1466     }
1469     /**
1470      * @return int the time when this attempt was submitted. 0 if it has not been
1471      * submitted yet.
1472      */
1473     public function get_submitted_date() {
1474         return $this->attempt->timefinish;
1475     }
1477     /**
1478      * If the attempt is in an applicable state, work out the time by which the
1479      * student should next do something.
1480      *
1481      * @return int timestamp by which the student needs to do something.
1482      */
1483     public function get_due_date() {
1484         $deadlines = array();
1485         if ($this->quizobj->get_quiz()->timelimit) {
1486             $deadlines[] = $this->attempt->timestart + $this->quizobj->get_quiz()->timelimit;
1487         }
1488         if ($this->quizobj->get_quiz()->timeclose) {
1489             $deadlines[] = $this->quizobj->get_quiz()->timeclose;
1490         }
1491         if ($deadlines) {
1492             $duedate = min($deadlines);
1493         } else {
1494             return false;
1495         }
1497         switch ($this->attempt->state) {
1498             case self::IN_PROGRESS:
1499                 return $duedate;
1501             case self::OVERDUE:
1502                 return $duedate + $this->quizobj->get_quiz()->graceperiod;
1504             default:
1505                 throw new coding_exception('Unexpected state: ' . $this->attempt->state);
1506         }
1507     }
1509     // URLs related to this attempt ============================================
1510     /**
1511      * @return string quiz view url.
1512      */
1513     public function view_url() {
1514         return $this->quizobj->view_url();
1515     }
1517     /**
1518      * Get the URL to start or continue an attempt.
1519      *
1520      * @param int|null $slot which question in the attempt to go to after starting (optional).
1521      * @param int $page which page in the attempt to go to after starting.
1522      * @return string the URL of this quiz's edit page. Needs to be POSTed to with a cmid parameter.
1523      */
1524     public function start_attempt_url($slot = null, $page = -1) {
1525         if ($page == -1 && !is_null($slot)) {
1526             $page = $this->get_question_page($slot);
1527         } else {
1528             $page = 0;
1529         }
1530         return $this->quizobj->start_attempt_url($page);
1531     }
1533     /**
1534      * Generates the title of the attempt page.
1535      *
1536      * @param int $page the page number (starting with 0) in the attempt.
1537      * @return string attempt page title.
1538      */
1539     public function attempt_page_title(int $page) : string {
1540         if ($this->get_num_pages() > 1) {
1541             $a = new stdClass();
1542             $a->name = $this->get_quiz_name();
1543             $a->currentpage = $page + 1;
1544             $a->totalpages = $this->get_num_pages();
1545             $title = get_string('attempttitlepaged', 'quiz', $a);
1546         } else {
1547             $title = get_string('attempttitle', 'quiz', $this->get_quiz_name());
1548         }
1550         return $title;
1551     }
1553     /**
1554      * @param int|null $slot if specified, the slot number of a specific question to link to.
1555      * @param int $page if specified, a particular page to link to. If not given deduced
1556      *      from $slot, or goes to the first page.
1557      * @param int $thispage if not -1, the current page. Will cause links to other things on
1558      * this page to be output as only a fragment.
1559      * @return string the URL to continue this attempt.
1560      */
1561     public function attempt_url($slot = null, $page = -1, $thispage = -1) {
1562         return $this->page_and_question_url('attempt', $slot, $page, false, $thispage);
1563     }
1565     /**
1566      * Generates the title of the summary page.
1567      *
1568      * @return string summary page title.
1569      */
1570     public function summary_page_title() : string {
1571         return get_string('attemptsummarytitle', 'quiz', $this->get_quiz_name());
1572     }
1574     /**
1575      * @return moodle_url the URL of this quiz's summary page.
1576      */
1577     public function summary_url() {
1578         return new moodle_url('/mod/quiz/summary.php', array('attempt' => $this->attempt->id, 'cmid' => $this->get_cmid()));
1579     }
1581     /**
1582      * @return moodle_url the URL of this quiz's summary page.
1583      */
1584     public function processattempt_url() {
1585         return new moodle_url('/mod/quiz/processattempt.php');
1586     }
1588     /**
1589      * Generates the title of the review page.
1590      *
1591      * @param int $page the page number (starting with 0) in the attempt.
1592      * @param bool $showall whether the review page contains the entire attempt on one page.
1593      * @return string title of the review page.
1594      */
1595     public function review_page_title(int $page, bool $showall = false) : string {
1596         if (!$showall && $this->get_num_pages() > 1) {
1597             $a = new stdClass();
1598             $a->name = $this->get_quiz_name();
1599             $a->currentpage = $page + 1;
1600             $a->totalpages = $this->get_num_pages();
1601             $title = get_string('attemptreviewtitlepaged', 'quiz', $a);
1602         } else {
1603             $title = get_string('attemptreviewtitle', 'quiz', $this->get_quiz_name());
1604         }
1606         return $title;
1607     }
1609     /**
1610      * @param int|null $slot indicates which question to link to.
1611      * @param int $page if specified, the URL of this particular page of the attempt, otherwise
1612      *      the URL will go to the first page.  If -1, deduce $page from $slot.
1613      * @param bool|null $showall if true, the URL will be to review the entire attempt on one page,
1614      *      and $page will be ignored. If null, a sensible default will be chosen.
1615      * @param int $thispage if not -1, the current page. Will cause links to other things on
1616      *      this page to be output as only a fragment.
1617      * @return string the URL to review this attempt.
1618      */
1619     public function review_url($slot = null, $page = -1, $showall = null, $thispage = -1) {
1620         return $this->page_and_question_url('review', $slot, $page, $showall, $thispage);
1621     }
1623     /**
1624      * By default, should this script show all questions on one page for this attempt?
1625      *
1626      * @param string $script the script name, e.g. 'attempt', 'summary', 'review'.
1627      * @return bool whether show all on one page should be on by default.
1628      */
1629     public function get_default_show_all($script) {
1630         return $script == 'review' && count($this->questionpages) < self::MAX_SLOTS_FOR_DEFAULT_REVIEW_SHOW_ALL;
1631     }
1633     // Bits of content =========================================================
1635     /**
1636      * If $reviewoptions->attempt is false, meaning that students can't review this
1637      * attempt at the moment, return an appropriate string explaining why.
1638      *
1639      * @param bool $short if true, return a shorter string.
1640      * @return string an appropriate message.
1641      */
1642     public function cannot_review_message($short = false) {
1643         return $this->quizobj->cannot_review_message(
1644                 $this->get_attempt_state(), $short);
1645     }
1647     /**
1648      * Initialise the JS etc. required all the questions on a page.
1649      *
1650      * @param int|string $page a page number, or 'all'.
1651      * @param bool $showall if true forces page number to all.
1652      * @return string HTML to output - mostly obsolete, will probably be an empty string.
1653      */
1654     public function get_html_head_contributions($page = 'all', $showall = false) {
1655         if ($showall) {
1656             $page = 'all';
1657         }
1658         $result = '';
1659         foreach ($this->get_slots($page) as $slot) {
1660             $result .= $this->quba->render_question_head_html($slot);
1661         }
1662         $result .= question_engine::initialise_js();
1663         return $result;
1664     }
1666     /**
1667      * Initialise the JS etc. required by one question.
1668      *
1669      * @param int $slot the question slot number.
1670      * @return string HTML to output - but this is mostly obsolete. Will probably be an empty string.
1671      */
1672     public function get_question_html_head_contributions($slot) {
1673         return $this->quba->render_question_head_html($slot) .
1674                 question_engine::initialise_js();
1675     }
1677     /**
1678      * Print the HTML for the start new preview button, if the current user
1679      * is allowed to see one.
1680      *
1681      * @return string HTML for the button.
1682      */
1683     public function restart_preview_button() {
1684         global $OUTPUT;
1685         if ($this->is_preview() && $this->is_preview_user()) {
1686             return $OUTPUT->single_button(new moodle_url(
1687                     $this->start_attempt_url(), array('forcenew' => true)),
1688                     get_string('startnewpreview', 'quiz'));
1689         } else {
1690             return '';
1691         }
1692     }
1694     /**
1695      * Generate the HTML that displayes the question in its current state, with
1696      * the appropriate display options.
1697      *
1698      * @param int $slot identifies the question in the attempt.
1699      * @param bool $reviewing is the being printed on an attempt or a review page.
1700      * @param mod_quiz_renderer $renderer the quiz renderer.
1701      * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1702      * @return string HTML for the question in its current state.
1703      */
1704     public function render_question($slot, $reviewing, mod_quiz_renderer $renderer, $thispageurl = null) {
1705         if ($this->is_blocked_by_previous_question($slot)) {
1706             $placeholderqa = $this->make_blocked_question_placeholder($slot);
1708             $displayoptions = $this->get_display_options($reviewing);
1709             $displayoptions->manualcomment = question_display_options::HIDDEN;
1710             $displayoptions->history = question_display_options::HIDDEN;
1711             $displayoptions->readonly = true;
1713             return html_writer::div($placeholderqa->render($displayoptions,
1714                     $this->get_question_number($this->get_original_slot($slot))),
1715                     'mod_quiz-blocked_question_warning');
1716         }
1718         return $this->render_question_helper($slot, $reviewing, $thispageurl, $renderer, null);
1719     }
1721     /**
1722      * Helper used by {@link render_question()} and {@link render_question_at_step()}.
1723      *
1724      * @param int $slot identifies the question in the attempt.
1725      * @param bool $reviewing is the being printed on an attempt or a review page.
1726      * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1727      * @param mod_quiz_renderer $renderer the quiz renderer.
1728      * @param int|null $seq the seq number of the past state to display.
1729      * @return string HTML fragment.
1730      */
1731     protected function render_question_helper($slot, $reviewing, $thispageurl,
1732             mod_quiz_renderer $renderer, $seq) {
1733         $originalslot = $this->get_original_slot($slot);
1734         $number = $this->get_question_number($originalslot);
1735         $displayoptions = $this->get_display_options_with_edit_link($reviewing, $slot, $thispageurl);
1737         if ($slot != $originalslot) {
1738             $originalmaxmark = $this->get_question_attempt($slot)->get_max_mark();
1739             $this->get_question_attempt($slot)->set_max_mark($this->get_question_attempt($originalslot)->get_max_mark());
1740         }
1742         if ($this->can_question_be_redone_now($slot)) {
1743             $displayoptions->extrainfocontent = $renderer->redo_question_button(
1744                     $slot, $displayoptions->readonly);
1745         }
1747         if ($displayoptions->history && $displayoptions->questionreviewlink) {
1748             $links = $this->links_to_other_redos($slot, $displayoptions->questionreviewlink);
1749             if ($links) {
1750                 $displayoptions->extrahistorycontent = html_writer::tag('p',
1751                         get_string('redoesofthisquestion', 'quiz', $renderer->render($links)));
1752             }
1753         }
1755         if ($seq === null) {
1756             $output = $this->quba->render_question($slot, $displayoptions, $number);
1757         } else {
1758             $output = $this->quba->render_question_at_step($slot, $seq, $displayoptions, $number);
1759         }
1761         if ($slot != $originalslot) {
1762             $this->get_question_attempt($slot)->set_max_mark($originalmaxmark);
1763         }
1765         return $output;
1766     }
1768     /**
1769      * Create a fake question to be displayed in place of a question that is blocked
1770      * until the previous question has been answered.
1771      *
1772      * @param int $slot int slot number of the question to replace.
1773      * @return question_attempt the placeholder question attempt.
1774      */
1775     protected function make_blocked_question_placeholder($slot) {
1776         $replacedquestion = $this->get_question_attempt($slot)->get_question(false);
1778         question_bank::load_question_definition_classes('description');
1779         $question = new qtype_description_question();
1780         $question->id = $replacedquestion->id;
1781         $question->category = null;
1782         $question->parent = 0;
1783         $question->qtype = question_bank::get_qtype('description');
1784         $question->name = '';
1785         $question->questiontext = get_string('questiondependsonprevious', 'quiz');
1786         $question->questiontextformat = FORMAT_HTML;
1787         $question->generalfeedback = '';
1788         $question->defaultmark = $this->quba->get_question_max_mark($slot);
1789         $question->length = $replacedquestion->length;
1790         $question->penalty = 0;
1791         $question->stamp = '';
1792         $question->version = 0;
1793         $question->hidden = 0;
1794         $question->timecreated = null;
1795         $question->timemodified = null;
1796         $question->createdby = null;
1797         $question->modifiedby = null;
1799         $placeholderqa = new question_attempt($question, $this->quba->get_id(),
1800                 null, $this->quba->get_question_max_mark($slot));
1801         $placeholderqa->set_slot($slot);
1802         $placeholderqa->start($this->get_quiz()->preferredbehaviour, 1);
1803         $placeholderqa->set_flagged($this->is_question_flagged($slot));
1804         return $placeholderqa;
1805     }
1807     /**
1808      * Like {@link render_question()} but displays the question at the past step
1809      * indicated by $seq, rather than showing the latest step.
1810      *
1811      * @param int $slot the slot number of a question in this quiz attempt.
1812      * @param int $seq the seq number of the past state to display.
1813      * @param bool $reviewing is the being printed on an attempt or a review page.
1814      * @param mod_quiz_renderer $renderer the quiz renderer.
1815      * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1816      * @return string HTML for the question in its current state.
1817      */
1818     public function render_question_at_step($slot, $seq, $reviewing,
1819             mod_quiz_renderer $renderer, $thispageurl = null) {
1820         return $this->render_question_helper($slot, $reviewing, $thispageurl, $renderer, $seq);
1821     }
1823     /**
1824      * Wrapper round print_question from lib/questionlib.php.
1825      *
1826      * @param int $slot the id of a question in this quiz attempt.
1827      * @return string HTML of the question.
1828      */
1829     public function render_question_for_commenting($slot) {
1830         $options = $this->get_display_options(true);
1831         $options->hide_all_feedback();
1832         $options->manualcomment = question_display_options::EDITABLE;
1833         return $this->quba->render_question($slot, $options,
1834                 $this->get_question_number($slot));
1835     }
1837     /**
1838      * Check wheter access should be allowed to a particular file.
1839      *
1840      * @param int $slot the slot of a question in this quiz attempt.
1841      * @param bool $reviewing is the being printed on an attempt or a review page.
1842      * @param int $contextid the file context id from the request.
1843      * @param string $component the file component from the request.
1844      * @param string $filearea the file area from the request.
1845      * @param array $args extra part components from the request.
1846      * @param bool $forcedownload whether to force download.
1847      * @return string HTML for the question in its current state.
1848      */
1849     public function check_file_access($slot, $reviewing, $contextid, $component,
1850             $filearea, $args, $forcedownload) {
1851         $options = $this->get_display_options($reviewing);
1853         // Check permissions - warning there is similar code in review.php and
1854         // reviewquestion.php. If you change on, change them all.
1855         if ($reviewing && $this->is_own_attempt() && !$options->attempt) {
1856             return false;
1857         }
1859         if ($reviewing && !$this->is_own_attempt() && !$this->is_review_allowed()) {
1860             return false;
1861         }
1863         return $this->quba->check_file_access($slot, $options,
1864                 $component, $filearea, $args, $forcedownload);
1865     }
1867     /**
1868      * Get the navigation panel object for this attempt.
1869      *
1870      * @param mod_quiz_renderer $output the quiz renderer to use to output things.
1871      * @param string $panelclass The type of panel, quiz_attempt_nav_panel or quiz_review_nav_panel
1872      * @param int $page the current page number.
1873      * @param bool $showall whether we are showing the whole quiz on one page. (Used by review.php.)
1874      * @return block_contents the requested object.
1875      */
1876     public function get_navigation_panel(mod_quiz_renderer $output,
1877              $panelclass, $page, $showall = false) {
1878         $panel = new $panelclass($this, $this->get_display_options(true), $page, $showall);
1880         $bc = new block_contents();
1881         $bc->attributes['id'] = 'mod_quiz_navblock';
1882         $bc->attributes['role'] = 'navigation';
1883         $bc->attributes['aria-labelledby'] = 'mod_quiz_navblock_title';
1884         $bc->title = html_writer::span(get_string('quiznavigation', 'quiz'), '', array('id' => 'mod_quiz_navblock_title'));
1885         $bc->content = $output->navigation_panel($panel);
1886         return $bc;
1887     }
1889     /**
1890      * Return an array of variant URLs to other attempts at this quiz.
1891      *
1892      * The $url passed in must contain an attempt parameter.
1893      *
1894      * The {@link mod_quiz_links_to_other_attempts} object returned contains an
1895      * array with keys that are the attempt number, 1, 2, 3.
1896      * The array values are either a {@link moodle_url} with the attempt parameter
1897      * updated to point to the attempt id of the other attempt, or null corresponding
1898      * to the current attempt number.
1899      *
1900      * @param moodle_url $url a URL.
1901      * @return mod_quiz_links_to_other_attempts|bool containing array int => null|moodle_url.
1902      *      False if none.
1903      */
1904     public function links_to_other_attempts(moodle_url $url) {
1905         $attempts = quiz_get_user_attempts($this->get_quiz()->id, $this->attempt->userid, 'all');
1906         if (count($attempts) <= 1) {
1907             return false;
1908         }
1910         $links = new mod_quiz_links_to_other_attempts();
1911         foreach ($attempts as $at) {
1912             if ($at->id == $this->attempt->id) {
1913                 $links->links[$at->attempt] = null;
1914             } else {
1915                 $links->links[$at->attempt] = new moodle_url($url, array('attempt' => $at->id));
1916             }
1917         }
1918         return $links;
1919     }
1921     /**
1922      * Return an array of variant URLs to other redos of the question in a particular slot.
1923      *
1924      * The $url passed in must contain a slot parameter.
1925      *
1926      * The {@link mod_quiz_links_to_other_attempts} object returned contains an
1927      * array with keys that are the redo number, 1, 2, 3.
1928      * The array values are either a {@link moodle_url} with the slot parameter
1929      * updated to point to the slot that has that redo of this question; or null
1930      * corresponding to the redo identified by $slot.
1931      *
1932      * @param int $slot identifies a question in this attempt.
1933      * @param moodle_url $baseurl the base URL to modify to generate each link.
1934      * @return mod_quiz_links_to_other_attempts|null containing array int => null|moodle_url,
1935      *      or null if the question in this slot has not been redone.
1936      */
1937     public function links_to_other_redos($slot, moodle_url $baseurl) {
1938         $originalslot = $this->get_original_slot($slot);
1940         $qas = $this->all_question_attempts_originally_in_slot($originalslot);
1941         if (count($qas) <= 1) {
1942             return null;
1943         }
1945         $links = new mod_quiz_links_to_other_attempts();
1946         $index = 1;
1947         foreach ($qas as $qa) {
1948             if ($qa->get_slot() == $slot) {
1949                 $links->links[$index] = null;
1950             } else {
1951                 $url = new moodle_url($baseurl, array('slot' => $qa->get_slot()));
1952                 $links->links[$index] = new action_link($url, $index,
1953                         new popup_action('click', $url, 'reviewquestion',
1954                                 array('width' => 450, 'height' => 650)),
1955                         array('title' => get_string('reviewresponse', 'question')));
1956             }
1957             $index++;
1958         }
1959         return $links;
1960     }
1962     // Methods for processing ==================================================
1964     /**
1965      * Check this attempt, to see if there are any state transitions that should
1966      * happen automatically. This function will update the attempt checkstatetime.
1967      * @param int $timestamp the timestamp that should be stored as the modified
1968      * @param bool $studentisonline is the student currently interacting with Moodle?
1969      */
1970     public function handle_if_time_expired($timestamp, $studentisonline) {
1972         $timeclose = $this->get_access_manager($timestamp)->get_end_time($this->attempt);
1974         if ($timeclose === false || $this->is_preview()) {
1975             $this->update_timecheckstate(null);
1976             return; // No time limit.
1977         }
1978         if ($timestamp < $timeclose) {
1979             $this->update_timecheckstate($timeclose);
1980             return; // Time has not yet expired.
1981         }
1983         // If the attempt is already overdue, look to see if it should be abandoned ...
1984         if ($this->attempt->state == self::OVERDUE) {
1985             $timeoverdue = $timestamp - $timeclose;
1986             $graceperiod = $this->quizobj->get_quiz()->graceperiod;
1987             if ($timeoverdue >= $graceperiod) {
1988                 $this->process_abandon($timestamp, $studentisonline);
1989             } else {
1990                 // Overdue time has not yet expired
1991                 $this->update_timecheckstate($timeclose + $graceperiod);
1992             }
1993             return; // ... and we are done.
1994         }
1996         if ($this->attempt->state != self::IN_PROGRESS) {
1997             $this->update_timecheckstate(null);
1998             return; // Attempt is already in a final state.
1999         }
2001         // Otherwise, we were in quiz_attempt::IN_PROGRESS, and time has now expired.
2002         // Transition to the appropriate state.
2003         switch ($this->quizobj->get_quiz()->overduehandling) {
2004             case 'autosubmit':
2005                 $this->process_finish($timestamp, false);
2006                 return;
2008             case 'graceperiod':
2009                 $this->process_going_overdue($timestamp, $studentisonline);
2010                 return;
2012             case 'autoabandon':
2013                 $this->process_abandon($timestamp, $studentisonline);
2014                 return;
2015         }
2017         // This is an overdue attempt with no overdue handling defined, so just abandon.
2018         $this->process_abandon($timestamp, $studentisonline);
2019         return;
2020     }
2022     /**
2023      * Process all the actions that were submitted as part of the current request.
2024      *
2025      * @param int $timestamp the timestamp that should be stored as the modified.
2026      *      time in the database for these actions. If null, will use the current time.
2027      * @param bool $becomingoverdue
2028      * @param array|null $simulatedresponses If not null, then we are testing, and this is an array of simulated data.
2029      *      There are two formats supported here, for historical reasons. The newer approach is to pass an array created by
2030      *      {@link core_question_generator::get_simulated_post_data_for_questions_in_usage()}.
2031      *      the second is to pass an array slot no => contains arrays representing student
2032      *      responses which will be passed to {@link question_definition::prepare_simulated_post_data()}.
2033      *      This second method will probably get deprecated one day.
2034      */
2035     public function process_submitted_actions($timestamp, $becomingoverdue = false, $simulatedresponses = null) {
2036         global $DB;
2038         $transaction = $DB->start_delegated_transaction();
2040         if ($simulatedresponses !== null) {
2041             if (is_int(key($simulatedresponses))) {
2042                 // Legacy approach. Should be removed one day.
2043                 $simulatedpostdata = $this->quba->prepare_simulated_post_data($simulatedresponses);
2044             } else {
2045                 $simulatedpostdata = $simulatedresponses;
2046             }
2047         } else {
2048             $simulatedpostdata = null;
2049         }
2051         $this->quba->process_all_actions($timestamp, $simulatedpostdata);
2052         question_engine::save_questions_usage_by_activity($this->quba);
2054         $this->attempt->timemodified = $timestamp;
2055         if ($this->attempt->state == self::FINISHED) {
2056             $this->attempt->sumgrades = $this->quba->get_total_mark();
2057         }
2058         if ($becomingoverdue) {
2059             $this->process_going_overdue($timestamp, true);
2060         } else {
2061             $DB->update_record('quiz_attempts', $this->attempt);
2062         }
2064         if (!$this->is_preview() && $this->attempt->state == self::FINISHED) {
2065             quiz_save_best_grade($this->get_quiz(), $this->get_userid());
2066         }
2068         $transaction->allow_commit();
2069     }
2071     /**
2072      * Replace a question in an attempt with a new attempt at the same question.
2073      *
2074      * Well, for randomised questions, it won't be the same question, it will be
2075      * a different randomised selection.
2076      *
2077      * @param int $slot the question to restart.
2078      * @param int $timestamp the timestamp to record for this action.
2079      */
2080     public function process_redo_question($slot, $timestamp) {
2081         global $DB;
2083         if (!$this->can_question_be_redone_now($slot)) {
2084             throw new coding_exception('Attempt to restart the question in slot ' . $slot .
2085                     ' when it is not in a state to be restarted.');
2086         }
2088         $qubaids = new \mod_quiz\question\qubaids_for_users_attempts(
2089                 $this->get_quizid(), $this->get_userid(), 'all', true);
2091         $transaction = $DB->start_delegated_transaction();
2093         // Choose the replacement question.
2094         $questiondata = $DB->get_record('question',
2095                 array('id' => $this->slots[$slot]->questionid));
2096         if ($questiondata->qtype != 'random') {
2097             $newqusetionid = $questiondata->id;
2098         } else {
2099             $tagids = quiz_retrieve_slot_tag_ids($this->slots[$slot]->id);
2101             $randomloader = new \core_question\bank\random_question_loader($qubaids, array());
2102             $newqusetionid = $randomloader->get_next_question_id($questiondata->category,
2103                     (bool) $questiondata->questiontext, $tagids);
2104             if ($newqusetionid === null) {
2105                 throw new moodle_exception('notenoughrandomquestions', 'quiz',
2106                         $this->quizobj->view_url(), $questiondata);
2107             }
2108         }
2110         // Add the question to the usage. It is important we do this before we choose a variant.
2111         $newquestion = question_bank::load_question($newqusetionid);
2112         $newslot = $this->quba->add_question_in_place_of_other($slot, $newquestion);
2114         // Choose the variant.
2115         if ($newquestion->get_num_variants() == 1) {
2116             $variant = 1;
2117         } else {
2118             $variantstrategy = new core_question\engine\variants\least_used_strategy(
2119                     $this->quba, $qubaids);
2120             $variant = $variantstrategy->choose_variant($newquestion->get_num_variants(),
2121                     $newquestion->get_variants_selection_seed());
2122         }
2124         // Start the question.
2125         $this->quba->start_question($slot, $variant);
2126         $this->quba->set_max_mark($newslot, 0);
2127         $this->quba->set_question_attempt_metadata($newslot, 'originalslot', $slot);
2128         question_engine::save_questions_usage_by_activity($this->quba);
2130         $transaction->allow_commit();
2131     }
2133     /**
2134      * Process all the autosaved data that was part of the current request.
2135      *
2136      * @param int $timestamp the timestamp that should be stored as the modified.
2137      * time in the database for these actions. If null, will use the current time.
2138      */
2139     public function process_auto_save($timestamp) {
2140         global $DB;
2142         $transaction = $DB->start_delegated_transaction();
2144         $this->quba->process_all_autosaves($timestamp);
2145         question_engine::save_questions_usage_by_activity($this->quba);
2147         $transaction->allow_commit();
2148     }
2150     /**
2151      * Update the flagged state for all question_attempts in this usage, if their
2152      * flagged state was changed in the request.
2153      */
2154     public function save_question_flags() {
2155         global $DB;
2157         $transaction = $DB->start_delegated_transaction();
2158         $this->quba->update_question_flags();
2159         question_engine::save_questions_usage_by_activity($this->quba);
2160         $transaction->allow_commit();
2161     }
2163     public function process_finish($timestamp, $processsubmitted) {
2164         global $DB;
2166         $transaction = $DB->start_delegated_transaction();
2168         if ($processsubmitted) {
2169             $this->quba->process_all_actions($timestamp);
2170         }
2171         $this->quba->finish_all_questions($timestamp);
2173         question_engine::save_questions_usage_by_activity($this->quba);
2175         $this->attempt->timemodified = $timestamp;
2176         $this->attempt->timefinish = $timestamp;
2177         $this->attempt->sumgrades = $this->quba->get_total_mark();
2178         $this->attempt->state = self::FINISHED;
2179         $this->attempt->timecheckstate = null;
2180         $DB->update_record('quiz_attempts', $this->attempt);
2182         if (!$this->is_preview()) {
2183             quiz_save_best_grade($this->get_quiz(), $this->attempt->userid);
2185             // Trigger event.
2186             $this->fire_state_transition_event('\mod_quiz\event\attempt_submitted', $timestamp);
2188             // Tell any access rules that care that the attempt is over.
2189             $this->get_access_manager($timestamp)->current_attempt_finished();
2190         }
2192         $transaction->allow_commit();
2193     }
2195     /**
2196      * Update this attempt timecheckstate if necessary.
2197      *
2198      * @param int|null $time the timestamp to set.
2199      */
2200     public function update_timecheckstate($time) {
2201         global $DB;
2202         if ($this->attempt->timecheckstate !== $time) {
2203             $this->attempt->timecheckstate = $time;
2204             $DB->set_field('quiz_attempts', 'timecheckstate', $time, array('id' => $this->attempt->id));
2205         }
2206     }
2208     /**
2209      * Mark this attempt as now overdue.
2210      *
2211      * @param int $timestamp the time to deem as now.
2212      * @param bool $studentisonline is the student currently interacting with Moodle?
2213      */
2214     public function process_going_overdue($timestamp, $studentisonline) {
2215         global $DB;
2217         $transaction = $DB->start_delegated_transaction();
2218         $this->attempt->timemodified = $timestamp;
2219         $this->attempt->state = self::OVERDUE;
2220         // If we knew the attempt close time, we could compute when the graceperiod ends.
2221         // Instead we'll just fix it up through cron.
2222         $this->attempt->timecheckstate = $timestamp;
2223         $DB->update_record('quiz_attempts', $this->attempt);
2225         $this->fire_state_transition_event('\mod_quiz\event\attempt_becameoverdue', $timestamp);
2227         $transaction->allow_commit();
2229         quiz_send_overdue_message($this);
2230     }
2232     /**
2233      * Mark this attempt as abandoned.
2234      *
2235      * @param int $timestamp the time to deem as now.
2236      * @param bool $studentisonline is the student currently interacting with Moodle?
2237      */
2238     public function process_abandon($timestamp, $studentisonline) {
2239         global $DB;
2241         $transaction = $DB->start_delegated_transaction();
2242         $this->attempt->timemodified = $timestamp;
2243         $this->attempt->state = self::ABANDONED;
2244         $this->attempt->timecheckstate = null;
2245         $DB->update_record('quiz_attempts', $this->attempt);
2247         $this->fire_state_transition_event('\mod_quiz\event\attempt_abandoned', $timestamp);
2249         $transaction->allow_commit();
2250     }
2252     /**
2253      * Fire a state transition event.
2254      *
2255      * @param string $eventclass the event class name.
2256      * @param int $timestamp the timestamp to include in the event.
2257      */
2258     protected function fire_state_transition_event($eventclass, $timestamp) {
2259         global $USER;
2260         $quizrecord = $this->get_quiz();
2261         $params = array(
2262             'context' => $this->get_quizobj()->get_context(),
2263             'courseid' => $this->get_courseid(),
2264             'objectid' => $this->attempt->id,
2265             'relateduserid' => $this->attempt->userid,
2266             'other' => array(
2267                 'submitterid' => CLI_SCRIPT ? null : $USER->id,
2268                 'quizid' => $quizrecord->id
2269             )
2270         );
2272         $event = $eventclass::create($params);
2273         $event->add_record_snapshot('quiz', $this->get_quiz());
2274         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2275         $event->trigger();
2276     }
2278     // Private methods =========================================================
2280     /**
2281      * Get a URL for a particular question on a particular page of the quiz.
2282      * Used by {@link attempt_url()} and {@link review_url()}.
2283      *
2284      * @param string $script. Used in the URL like /mod/quiz/$script.php.
2285      * @param int $slot identifies the specific question on the page to jump to.
2286      *      0 to just use the $page parameter.
2287      * @param int $page -1 to look up the page number from the slot, otherwise
2288      *      the page number to go to.
2289      * @param bool|null $showall if true, return a URL with showall=1, and not page number.
2290      *      if null, then an intelligent default will be chosen.
2291      * @param int $thispage the page we are currently on. Links to questions on this
2292      *      page will just be a fragment #q123. -1 to disable this.
2293      * @return moodle_url The requested URL.
2294      */
2295     protected function page_and_question_url($script, $slot, $page, $showall, $thispage) {
2297         $defaultshowall = $this->get_default_show_all($script);
2298         if ($showall === null && ($page == 0 || $page == -1)) {
2299             $showall = $defaultshowall;
2300         }
2302         // Fix up $page.
2303         if ($page == -1) {
2304             if ($slot !== null && !$showall) {
2305                 $page = $this->get_question_page($slot);
2306             } else {
2307                 $page = 0;
2308             }
2309         }
2311         if ($showall) {
2312             $page = 0;
2313         }
2315         // Add a fragment to scroll down to the question.
2316         $fragment = '';
2317         if ($slot !== null) {
2318             if ($slot == reset($this->pagelayout[$page])) {
2319                 // First question on page, go to top.
2320                 $fragment = '#';
2321             } else {
2322                 $qa = $this->get_question_attempt($slot);
2323                 $fragment = '#' . $qa->get_outer_question_div_unique_id();
2324             }
2325         }
2327         // Work out the correct start to the URL.
2328         if ($thispage == $page) {
2329             return new moodle_url($fragment);
2331         } else {
2332             $url = new moodle_url('/mod/quiz/' . $script . '.php' . $fragment,
2333                     array('attempt' => $this->attempt->id, 'cmid' => $this->get_cmid()));
2334             if ($page == 0 && $showall != $defaultshowall) {
2335                 $url->param('showall', (int) $showall);
2336             } else if ($page > 0) {
2337                 $url->param('page', $page);
2338             }
2339             return $url;
2340         }
2341     }
2343     /**
2344      * Process responses during an attempt at a quiz.
2345      *
2346      * @param  int $timenow time when the processing started.
2347      * @param  bool $finishattempt whether to finish the attempt or not.
2348      * @param  bool $timeup true if form was submitted by timer.
2349      * @param  int $thispage current page number.
2350      * @return string the attempt state once the data has been processed.
2351      * @since  Moodle 3.1
2352      */
2353     public function process_attempt($timenow, $finishattempt, $timeup, $thispage) {
2354         global $DB;
2356         $transaction = $DB->start_delegated_transaction();
2358         // If there is only a very small amount of time left, there is no point trying
2359         // to show the student another page of the quiz. Just finish now.
2360         $graceperiodmin = null;
2361         $accessmanager = $this->get_access_manager($timenow);
2362         $timeclose = $accessmanager->get_end_time($this->get_attempt());
2364         // Don't enforce timeclose for previews.
2365         if ($this->is_preview()) {
2366             $timeclose = false;
2367         }
2368         $toolate = false;
2369         if ($timeclose !== false && $timenow > $timeclose - QUIZ_MIN_TIME_TO_CONTINUE) {
2370             $timeup = true;
2371             $graceperiodmin = get_config('quiz', 'graceperiodmin');
2372             if ($timenow > $timeclose + $graceperiodmin) {
2373                 $toolate = true;
2374             }
2375         }
2377         // If time is running out, trigger the appropriate action.
2378         $becomingoverdue = false;
2379         $becomingabandoned = false;
2380         if ($timeup) {
2381             if ($this->get_quiz()->overduehandling == 'graceperiod') {
2382                 if (is_null($graceperiodmin)) {
2383                     $graceperiodmin = get_config('quiz', 'graceperiodmin');
2384                 }
2385                 if ($timenow > $timeclose + $this->get_quiz()->graceperiod + $graceperiodmin) {
2386                     // Grace period has run out.
2387                     $finishattempt = true;
2388                     $becomingabandoned = true;
2389                 } else {
2390                     $becomingoverdue = true;
2391                 }
2392             } else {
2393                 $finishattempt = true;
2394             }
2395         }
2397         // Don't log - we will end with a redirect to a page that is logged.
2399         if (!$finishattempt) {
2400             // Just process the responses for this page and go to the next page.
2401             if (!$toolate) {
2402                 try {
2403                     $this->process_submitted_actions($timenow, $becomingoverdue);
2405                 } catch (question_out_of_sequence_exception $e) {
2406                     throw new moodle_exception('submissionoutofsequencefriendlymessage', 'question',
2407                             $this->attempt_url(null, $thispage));
2409                 } catch (Exception $e) {
2410                     // This sucks, if we display our own custom error message, there is no way
2411                     // to display the original stack trace.
2412                     $debuginfo = '';
2413                     if (!empty($e->debuginfo)) {
2414                         $debuginfo = $e->debuginfo;
2415                     }
2416                     throw new moodle_exception('errorprocessingresponses', 'question',
2417                             $this->attempt_url(null, $thispage), $e->getMessage(), $debuginfo);
2418                 }
2420                 if (!$becomingoverdue) {
2421                     foreach ($this->get_slots() as $slot) {
2422                         if (optional_param('redoslot' . $slot, false, PARAM_BOOL)) {
2423                             $this->process_redo_question($slot, $timenow);
2424                         }
2425                     }
2426                 }
2428             } else {
2429                 // The student is too late.
2430                 $this->process_going_overdue($timenow, true);
2431             }
2433             $transaction->allow_commit();
2435             return $becomingoverdue ? self::OVERDUE : self::IN_PROGRESS;
2436         }
2438         // Update the quiz attempt record.
2439         try {
2440             if ($becomingabandoned) {
2441                 $this->process_abandon($timenow, true);
2442             } else {
2443                 $this->process_finish($timenow, !$toolate);
2444             }
2446         } catch (question_out_of_sequence_exception $e) {
2447             throw new moodle_exception('submissionoutofsequencefriendlymessage', 'question',
2448                     $this->attempt_url(null, $thispage));
2450         } catch (Exception $e) {
2451             // This sucks, if we display our own custom error message, there is no way
2452             // to display the original stack trace.
2453             $debuginfo = '';
2454             if (!empty($e->debuginfo)) {
2455                 $debuginfo = $e->debuginfo;
2456             }
2457             throw new moodle_exception('errorprocessingresponses', 'question',
2458                     $this->attempt_url(null, $thispage), $e->getMessage(), $debuginfo);
2459         }
2461         // Send the user to the review page.
2462         $transaction->allow_commit();
2464         return $becomingabandoned ? self::ABANDONED : self::FINISHED;
2465     }
2467     /**
2468      * Check a page access to see if is an out of sequence access.
2469      *
2470      * @param  int $page page number.
2471      * @return boolean false is is an out of sequence access, true otherwise.
2472      * @since Moodle 3.1
2473      */
2474     public function check_page_access($page) {
2475         if ($this->get_currentpage() != $page) {
2476             if ($this->get_navigation_method() == QUIZ_NAVMETHOD_SEQ && $this->get_currentpage() > $page) {
2477                 return false;
2478             }
2479         }
2480         return true;
2481     }
2483     /**
2484      * Update attempt page.
2485      *
2486      * @param  int $page page number.
2487      * @return boolean true if everything was ok, false otherwise (out of sequence access).
2488      * @since Moodle 3.1
2489      */
2490     public function set_currentpage($page) {
2491         global $DB;
2493         if ($this->check_page_access($page)) {
2494             $DB->set_field('quiz_attempts', 'currentpage', $page, array('id' => $this->get_attemptid()));
2495             return true;
2496         }
2497         return false;
2498     }
2500     /**
2501      * Trigger the attempt_viewed event.
2502      *
2503      * @since Moodle 3.1
2504      */
2505     public function fire_attempt_viewed_event() {
2506         $params = array(
2507             'objectid' => $this->get_attemptid(),
2508             'relateduserid' => $this->get_userid(),
2509             'courseid' => $this->get_courseid(),
2510             'context' => context_module::instance($this->get_cmid()),
2511             'other' => array(
2512                 'quizid' => $this->get_quizid()
2513             )
2514         );
2515         $event = \mod_quiz\event\attempt_viewed::create($params);
2516         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2517         $event->trigger();
2518     }
2520     /**
2521      * Trigger the attempt_summary_viewed event.
2522      *
2523      * @since Moodle 3.1
2524      */
2525     public function fire_attempt_summary_viewed_event() {
2527         $params = array(
2528             'objectid' => $this->get_attemptid(),
2529             'relateduserid' => $this->get_userid(),
2530             'courseid' => $this->get_courseid(),
2531             'context' => context_module::instance($this->get_cmid()),
2532             'other' => array(
2533                 'quizid' => $this->get_quizid()
2534             )
2535         );
2536         $event = \mod_quiz\event\attempt_summary_viewed::create($params);
2537         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2538         $event->trigger();
2539     }
2541     /**
2542      * Trigger the attempt_reviewed event.
2543      *
2544      * @since Moodle 3.1
2545      */
2546     public function fire_attempt_reviewed_event() {
2548         $params = array(
2549             'objectid' => $this->get_attemptid(),
2550             'relateduserid' => $this->get_userid(),
2551             'courseid' => $this->get_courseid(),
2552             'context' => context_module::instance($this->get_cmid()),
2553             'other' => array(
2554                 'quizid' => $this->get_quizid()
2555             )
2556         );
2557         $event = \mod_quiz\event\attempt_reviewed::create($params);
2558         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2559         $event->trigger();
2560     }
2562     /**
2563      * Update the timemodifiedoffline attempt field.
2564      *
2565      * This function should be used only when web services are being used.
2566      *
2567      * @param int $time time stamp.
2568      * @return boolean false if the field is not updated because web services aren't being used.
2569      * @since Moodle 3.2
2570      */
2571     public function set_offline_modified_time($time) {
2572         // Update the timemodifiedoffline field only if web services are being used.
2573         if (WS_SERVER) {
2574             $this->attempt->timemodifiedoffline = $time;
2575             return true;
2576         }
2577         return false;
2578     }
2583 /**
2584  * Represents a heading in the navigation panel.
2585  *
2586  * @copyright  2015 The Open University
2587  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2588  * @since      Moodle 2.9
2589  */
2590 class quiz_nav_section_heading implements renderable {
2591     /** @var string the heading text. */
2592     public $heading;
2594     /**
2595      * Constructor.
2596      * @param string $heading the heading text
2597      */
2598     public function __construct($heading) {
2599         $this->heading = $heading;
2600     }
2604 /**
2605  * Represents a single link in the navigation panel.
2606  *
2607  * @copyright  2011 The Open University
2608  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2609  * @since      Moodle 2.1
2610  */
2611 class quiz_nav_question_button implements renderable {
2612     /** @var string id="..." to add to the HTML for this button. */
2613     public $id;
2614     /** @var string number to display in this button. Either the question number of 'i'. */
2615     public $number;
2616     /** @var string class to add to the class="" attribute to represnt the question state. */
2617     public $stateclass;
2618     /** @var string Textual description of the question state, e.g. to use as a tool tip. */
2619     public $statestring;
2620     /** @var int the page number this question is on. */
2621     public $page;
2622     /** @var bool true if this question is on the current page. */
2623     public $currentpage;
2624     /** @var bool true if this question has been flagged. */
2625     public $flagged;
2626     /** @var moodle_url the link this button goes to, or null if there should not be a link. */
2627     public $url;
2628     /** @var int QUIZ_NAVMETHOD_FREE or QUIZ_NAVMETHOD_SEQ. */
2629     public $navmethod;
2633 /**
2634  * Represents the navigation panel, and builds a {@link block_contents} to allow
2635  * it to be output.
2636  *
2637  * @copyright  2008 Tim Hunt
2638  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2639  * @since      Moodle 2.0
2640  */
2641 abstract class quiz_nav_panel_base {
2642     /** @var quiz_attempt */
2643     protected $attemptobj;
2644     /** @var question_display_options */
2645     protected $options;
2646     /** @var integer */
2647     protected $page;
2648     /** @var boolean */
2649     protected $showall;
2651     public function __construct(quiz_attempt $attemptobj,
2652             question_display_options $options, $page, $showall) {
2653         $this->attemptobj = $attemptobj;
2654         $this->options = $options;
2655         $this->page = $page;
2656         $this->showall = $showall;
2657     }
2659     /**
2660      * Get the buttons and section headings to go in the quiz navigation block.
2661      *
2662      * @return renderable[] the buttons, possibly interleaved with section headings.
2663      */
2664     public function get_question_buttons() {
2665         $buttons = array();
2666         foreach ($this->attemptobj->get_slots() as $slot) {
2667             if ($heading = $this->attemptobj->get_heading_before_slot($slot)) {
2668                 $buttons[] = new quiz_nav_section_heading(format_string($heading));
2669             }
2671             $qa = $this->attemptobj->get_question_attempt($slot);
2672             $showcorrectness = $this->options->correctness && $qa->has_marks();
2674             $button = new quiz_nav_question_button();
2675             $button->id          = 'quiznavbutton' . $slot;
2676             $button->number      = $this->attemptobj->get_question_number($slot);
2677             $button->stateclass  = $qa->get_state_class($showcorrectness);
2678             $button->navmethod   = $this->attemptobj->get_navigation_method();
2679             if (!$showcorrectness && $button->stateclass == 'notanswered') {
2680                 $button->stateclass = 'complete';
2681             }
2682             $button->statestring = $this->get_state_string($qa, $showcorrectness);
2683             $button->page        = $this->attemptobj->get_question_page($slot);
2684             $button->currentpage = $this->showall || $button->page == $this->page;
2685             $button->flagged     = $qa->is_flagged();
2686             $button->url         = $this->get_question_url($slot);
2687             if ($this->attemptobj->is_blocked_by_previous_question($slot)) {
2688                 $button->url = null;
2689                 $button->stateclass = 'blocked';
2690                 $button->statestring = get_string('questiondependsonprevious', 'quiz');
2691             }
2692             $buttons[] = $button;
2693         }
2695         return $buttons;
2696     }
2698     protected function get_state_string(question_attempt $qa, $showcorrectness) {
2699         if ($qa->get_question(false)->length > 0) {
2700             return $qa->get_state_string($showcorrectness);
2701         }
2703         // Special case handling for 'information' items.
2704         if ($qa->get_state() == question_state::$todo) {
2705             return get_string('notyetviewed', 'quiz');
2706         } else {
2707             return get_string('viewed', 'quiz');
2708         }
2709     }
2711     /**
2712      * Hook for subclasses to override.
2713      *
2714      * @param mod_quiz_renderer $output the quiz renderer to use.
2715      * @return string HTML to output.
2716      */
2717     public function render_before_button_bits(mod_quiz_renderer $output) {
2718         return '';
2719     }
2721     abstract public function render_end_bits(mod_quiz_renderer $output);
2723     /**
2724      * Render the restart preview button.
2725      *
2726      * @param mod_quiz_renderer $output the quiz renderer to use.
2727      * @return string HTML to output.
2728      */
2729     protected function render_restart_preview_link($output) {
2730         if (!$this->attemptobj->is_own_preview()) {
2731             return '';
2732         }
2733         return $output->restart_preview_button(new moodle_url(
2734                 $this->attemptobj->start_attempt_url(), array('forcenew' => true)));
2735     }
2737     protected abstract function get_question_url($slot);
2739     public function user_picture() {
2740         global $DB;
2741         if ($this->attemptobj->get_quiz()->showuserpicture == QUIZ_SHOWIMAGE_NONE) {
2742             return null;
2743         }
2744         $user = $DB->get_record('user', array('id' => $this->attemptobj->get_userid()));
2745         $userpicture = new user_picture($user);
2746         $userpicture->courseid = $this->attemptobj->get_courseid();
2747         if ($this->attemptobj->get_quiz()->showuserpicture == QUIZ_SHOWIMAGE_LARGE) {
2748             $userpicture->size = true;
2749         }
2750         return $userpicture;
2751     }
2753     /**
2754      * Return 'allquestionsononepage' as CSS class name when $showall is set,
2755      * otherwise, return 'multipages' as CSS class name.
2756      *
2757      * @return string, CSS class name
2758      */
2759     public function get_button_container_class() {
2760         // Quiz navigation is set on 'Show all questions on one page'.
2761         if ($this->showall) {
2762             return 'allquestionsononepage';
2763         }
2764         // Quiz navigation is set on 'Show one page at a time'.
2765         return 'multipages';
2766     }
2770 /**
2771  * Specialisation of {@link quiz_nav_panel_base} for the attempt quiz page.
2772  *
2773  * @copyright  2008 Tim Hunt
2774  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2775  * @since      Moodle 2.0
2776  */
2777 class quiz_attempt_nav_panel extends quiz_nav_panel_base {
2778     public function get_question_url($slot) {
2779         if ($this->attemptobj->can_navigate_to($slot)) {
2780             return $this->attemptobj->attempt_url($slot, -1, $this->page);
2781         } else {
2782             return null;
2783         }
2784     }
2786     public function render_before_button_bits(mod_quiz_renderer $output) {
2787         return html_writer::tag('div', get_string('navnojswarning', 'quiz'),
2788                 array('id' => 'quiznojswarning'));
2789     }
2791     public function render_end_bits(mod_quiz_renderer $output) {
2792         if ($this->page == -1) {
2793             // Don't link from the summary page to itself.
2794             return '';
2795         }
2796         return html_writer::link($this->attemptobj->summary_url(),
2797                 get_string('endtest', 'quiz'), array('class' => 'endtestlink aalink')) .
2798                 $this->render_restart_preview_link($output);
2799     }
2803 /**
2804  * Specialisation of {@link quiz_nav_panel_base} for the review quiz page.
2805  *
2806  * @copyright  2008 Tim Hunt
2807  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2808  * @since      Moodle 2.0
2809  */
2810 class quiz_review_nav_panel extends quiz_nav_panel_base {
2811     public function get_question_url($slot) {
2812         return $this->attemptobj->review_url($slot, -1, $this->showall, $this->page);
2813     }
2815     public function render_end_bits(mod_quiz_renderer $output) {
2816         $html = '';
2817         if ($this->attemptobj->get_num_pages() > 1) {
2818             if ($this->showall) {
2819                 $html .= html_writer::link($this->attemptobj->review_url(null, 0, false),
2820                         get_string('showeachpage', 'quiz'));
2821             } else {
2822                 $html .= html_writer::link($this->attemptobj->review_url(null, 0, true),
2823                         get_string('showall', 'quiz'));
2824             }
2825         }
2826         $html .= $output->finish_review_link($this->attemptobj);
2827         $html .= $this->render_restart_preview_link($output);
2828         return $html;
2829     }