[Summary view]

Differences Between: [Versions 402 and 403]

   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/>.
  16  
  17  namespace mod_quiz;
  18  
  19  use action_link;
  20  use block_contents;
  21  use cm_info;
  22  use coding_exception;
  23  use context_module;
  24  use Exception;
  25  use html_writer;
  26  use mod_quiz\output\links_to_other_attempts;
  27  use mod_quiz\output\renderer;
  28  use mod_quiz\question\bank\qbank_helper;
  29  use mod_quiz\question\display_options;
  30  use moodle_exception;
  31  use moodle_url;
  32  use popup_action;
  33  use qtype_description_question;
  34  use question_attempt;
  35  use question_bank;
  36  use question_display_options;
  37  use question_engine;
  38  use question_out_of_sequence_exception;
  39  use question_state;
  40  use question_usage_by_activity;
  41  use stdClass;
  42  
  43  /**
  44   * This class represents one user's attempt at a particular quiz.
  45   *
  46   * @package   mod_quiz
  47   * @copyright 2008 Tim Hunt
  48   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  49   */
  50  class quiz_attempt {
  51  
  52      /** @var string to identify the in progress state. */
  53      const IN_PROGRESS = 'inprogress';
  54      /** @var string to identify the overdue state. */
  55      const OVERDUE     = 'overdue';
  56      /** @var string to identify the finished state. */
  57      const FINISHED    = 'finished';
  58      /** @var string to identify the abandoned state. */
  59      const ABANDONED   = 'abandoned';
  60  
  61      /** @var int maximum number of slots in the quiz for the review page to default to show all. */
  62      const MAX_SLOTS_FOR_DEFAULT_REVIEW_SHOW_ALL = 50;
  63  
  64      /** @var quiz_settings object containing the quiz settings. */
  65      protected $quizobj;
  66  
  67      /** @var stdClass the quiz_attempts row. */
  68      protected $attempt;
  69  
  70      /** @var question_usage_by_activity the question usage for this quiz attempt. */
  71      protected $quba;
  72  
  73      /**
  74       * @var array of slot information. These objects contain ->slot (int),
  75       *      ->requireprevious (bool), ->questionids (int) the original question for random questions,
  76       *      ->firstinsection (bool), ->section (stdClass from $this->sections).
  77       *      This does not contain page - get that from {@see get_question_page()} -
  78       *      or maxmark - get that from $this->quba.
  79       */
  80      protected $slots;
  81  
  82      /** @var array of quiz_sections rows, with a ->lastslot field added. */
  83      protected $sections;
  84  
  85      /** @var array page no => array of slot numbers on the page in order. */
  86      protected $pagelayout;
  87  
  88      /** @var array slot => displayed question number for this slot. (E.g. 1, 2, 3 or 'i'.) */
  89      protected $questionnumbers;
  90  
  91      /** @var array slot => page number for this slot. */
  92      protected $questionpages;
  93  
  94      /** @var display_options cache for the appropriate review options. */
  95      protected $reviewoptions = null;
  96  
  97      // Constructor =============================================================.
  98      /**
  99       * Constructor assuming we already have the necessary data loaded.
 100       *
 101       * @param stdClass $attempt the row of the quiz_attempts table.
 102       * @param stdClass $quiz the quiz object for this attempt and user.
 103       * @param cm_info $cm the course_module object for this quiz.
 104       * @param stdClass $course the row from the course table for the course we belong to.
 105       * @param bool $loadquestions (optional) if true, the default, load all the details
 106       *      of the state of each question. Else just set up the basic details of the attempt.
 107       */
 108      public function __construct($attempt, $quiz, $cm, $course, $loadquestions = true) {
 109          $this->attempt = $attempt;
 110          $this->quizobj = new quiz_settings($quiz, $cm, $course);
 111  
 112          if ($loadquestions) {
 113              $this->load_questions();
 114          }
 115      }
 116  
 117      /**
 118       * Used by {create()} and {create_from_usage_id()}.
 119       *
 120       * @param array $conditions passed to $DB->get_record('quiz_attempts', $conditions).
 121       * @return quiz_attempt the desired instance of this class.
 122       */
 123      protected static function create_helper($conditions) {
 124          global $DB;
 125  
 126          $attempt = $DB->get_record('quiz_attempts', $conditions, '*', MUST_EXIST);
 127          $quiz = access_manager::load_quiz_and_settings($attempt->quiz);
 128          $course = get_course($quiz->course);
 129          $cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id, false, MUST_EXIST);
 130  
 131          // Update quiz with override information.
 132          $quiz = quiz_update_effective_access($quiz, $attempt->userid);
 133  
 134          return new quiz_attempt($attempt, $quiz, $cm, $course);
 135      }
 136  
 137      /**
 138       * Static function to create a new quiz_attempt object given an attemptid.
 139       *
 140       * @param int $attemptid the attempt id.
 141       * @return quiz_attempt the new quiz_attempt object
 142       */
 143      public static function create($attemptid) {
 144          return self::create_helper(['id' => $attemptid]);
 145      }
 146  
 147      /**
 148       * Static function to create a new quiz_attempt object given a usage id.
 149       *
 150       * @param int $usageid the attempt usage id.
 151       * @return quiz_attempt the new quiz_attempt object
 152       */
 153      public static function create_from_usage_id($usageid) {
 154          return self::create_helper(['uniqueid' => $usageid]);
 155      }
 156  
 157      /**
 158       * Get a human-readable name for one of the quiz attempt states.
 159       *
 160       * @param string $state one of the state constants like IN_PROGRESS.
 161       * @return string the human-readable state name.
 162       */
 163      public static function state_name($state) {
 164          return quiz_attempt_state_name($state);
 165      }
 166  
 167      /**
 168       * This method can be called later if the object was constructed with $loadquestions = false.
 169       */
 170      public function load_questions() {
 171          global $DB;
 172  
 173          if (isset($this->quba)) {
 174              throw new coding_exception('This quiz attempt has already had the questions loaded.');
 175          }
 176  
 177          $this->quba = question_engine::load_questions_usage_by_activity($this->attempt->uniqueid);
 178          $this->slots = $DB->get_records('quiz_slots',
 179                  ['quizid' => $this->get_quizid()], 'slot', 'slot, id, requireprevious, displaynumber');
 180          $this->sections = array_values($DB->get_records('quiz_sections',
 181                  ['quizid' => $this->get_quizid()], 'firstslot'));
 182  
 183          $this->link_sections_and_slots();
 184          $this->determine_layout();
 185          $this->number_questions();
 186      }
 187  
 188      /**
 189       * Preload all attempt step users to show in Response history.
 190       */
 191      public function preload_all_attempt_step_users(): void {
 192          $this->quba->preload_all_step_users();
 193      }
 194  
 195      /**
 196       * Let each slot know which section it is part of.
 197       */
 198      protected function link_sections_and_slots() {
 199          foreach ($this->sections as $i => $section) {
 200              if (isset($this->sections[$i + 1])) {
 201                  $section->lastslot = $this->sections[$i + 1]->firstslot - 1;
 202              } else {
 203                  $section->lastslot = count($this->slots);
 204              }
 205              for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
 206                  $this->slots[$slot]->section = $section;
 207              }
 208          }
 209      }
 210  
 211      /**
 212       * Parse attempt->layout to populate the other arrays that represent the layout.
 213       */
 214      protected function determine_layout() {
 215  
 216          // Break up the layout string into pages.
 217          $pagelayouts = explode(',0', $this->attempt->layout);
 218  
 219          // Strip off any empty last page (normally there is one).
 220          if (end($pagelayouts) == '') {
 221              array_pop($pagelayouts);
 222          }
 223  
 224          // File the ids into the arrays.
 225          // Tracking which is the first slot in each section in this attempt is
 226          // trickier than you might guess, since the slots in this section
 227          // may be shuffled, so $section->firstslot (the lowest numbered slot in
 228          // the section) may not be the first one.
 229          $unseensections = $this->sections;
 230          $this->pagelayout = [];
 231          foreach ($pagelayouts as $page => $pagelayout) {
 232              $pagelayout = trim($pagelayout, ',');
 233              if ($pagelayout == '') {
 234                  continue;
 235              }
 236              $this->pagelayout[$page] = explode(',', $pagelayout);
 237              foreach ($this->pagelayout[$page] as $slot) {
 238                  $sectionkey = array_search($this->slots[$slot]->section, $unseensections);
 239                  if ($sectionkey !== false) {
 240                      $this->slots[$slot]->firstinsection = true;
 241                      unset($unseensections[$sectionkey]);
 242                  } else {
 243                      $this->slots[$slot]->firstinsection = false;
 244                  }
 245              }
 246          }
 247      }
 248  
 249      /**
 250       * Work out the number to display for each question/slot.
 251       */
 252      protected function number_questions() {
 253          $number = 1;
 254          foreach ($this->pagelayout as $page => $slots) {
 255              foreach ($slots as $slot) {
 256                  if ($length = $this->is_real_question($slot)) {
 257                      // Whether question numbering is customised or is numeric and automatically incremented.
 258                      if ($this->slots[$slot]->displaynumber !== null && $this->slots[$slot]->displaynumber !== '' &&
 259                              !$this->slots[$slot]->section->shufflequestions) {
 260                          $this->questionnumbers[$slot] = $this->slots[$slot]->displaynumber;
 261                      } else {
 262                          $this->questionnumbers[$slot] = (string) $number;
 263                      }
 264                      $number += $length;
 265                  } else {
 266                      $this->questionnumbers[$slot] = get_string('infoshort', 'quiz');
 267                  }
 268                  $this->questionpages[$slot] = $page;
 269              }
 270          }
 271      }
 272  
 273      /**
 274       * If the given page number is out of range (before the first page, or after
 275       * the last page, change it to be within range).
 276       *
 277       * @param int $page the requested page number.
 278       * @return int a safe page number to use.
 279       */
 280      public function force_page_number_into_range($page) {
 281          return min(max($page, 0), count($this->pagelayout) - 1);
 282      }
 283  
 284      // Simple getters ==========================================================.
 285  
 286      /**
 287       * Get the raw quiz settings object.
 288       *
 289       * @return stdClass
 290       */
 291      public function get_quiz() {
 292          return $this->quizobj->get_quiz();
 293      }
 294  
 295      /**
 296       * Get the {@see seb_quiz_settings} object for this quiz.
 297       *
 298       * @return quiz_settings
 299       */
 300      public function get_quizobj() {
 301          return $this->quizobj;
 302      }
 303  
 304      /**
 305       * Git the id of the course this quiz belongs to.
 306       *
 307       * @return int the course id.
 308       */
 309      public function get_courseid() {
 310          return $this->quizobj->get_courseid();
 311      }
 312  
 313      /**
 314       * Get the course settings object.
 315       *
 316       * @return stdClass the course settings object.
 317       */
 318      public function get_course() {
 319          return $this->quizobj->get_course();
 320      }
 321  
 322      /**
 323       * Get the quiz id.
 324       *
 325       * @return int the quiz id.
 326       */
 327      public function get_quizid() {
 328          return $this->quizobj->get_quizid();
 329      }
 330  
 331      /**
 332       * Get the name of this quiz.
 333       *
 334       * @return string Quiz name, directly from the database (format_string must be called before output).
 335       */
 336      public function get_quiz_name() {
 337          return $this->quizobj->get_quiz_name();
 338      }
 339  
 340      /**
 341       * Get the quiz navigation method.
 342       *
 343       * @return int QUIZ_NAVMETHOD_FREE or QUIZ_NAVMETHOD_SEQ.
 344       */
 345      public function get_navigation_method() {
 346          return $this->quizobj->get_navigation_method();
 347      }
 348  
 349      /**
 350       * Get the course_module for this quiz.
 351       *
 352       * @return cm_info the course_module object.
 353       */
 354      public function get_cm() {
 355          return $this->quizobj->get_cm();
 356      }
 357  
 358      /**
 359       * Get the course-module id.
 360       *
 361       * @return int the course_module id.
 362       */
 363      public function get_cmid() {
 364          return $this->quizobj->get_cmid();
 365      }
 366  
 367      /**
 368       * Get the quiz context.
 369       *
 370       * @return context_module the context of the quiz this attempt belongs to.
 371       */
 372      public function get_context(): context_module {
 373          return $this->quizobj->get_context();
 374      }
 375  
 376      /**
 377       * Is the current user is someone who previews the quiz, rather than attempting it?
 378       *
 379       * @return bool true user is a preview user. False, if they can do real attempts.
 380       */
 381      public function is_preview_user() {
 382          return $this->quizobj->is_preview_user();
 383      }
 384  
 385      /**
 386       * Get the number of attempts the user is allowed at this quiz.
 387       *
 388       * @return int the number of attempts allowed at this quiz (0 = infinite).
 389       */
 390      public function get_num_attempts_allowed() {
 391          return $this->quizobj->get_num_attempts_allowed();
 392      }
 393  
 394      /**
 395       * Get the number of quizzes in the quiz attempt.
 396       *
 397       * @return int number pages.
 398       */
 399      public function get_num_pages() {
 400          return count($this->pagelayout);
 401      }
 402  
 403      /**
 404       * Get the access_manager for this quiz attempt.
 405       *
 406       * @param int $timenow the current time as a unix timestamp.
 407       * @return access_manager and instance of the access_manager class
 408       *      for this quiz at this time.
 409       */
 410      public function get_access_manager($timenow) {
 411          return $this->quizobj->get_access_manager($timenow);
 412      }
 413  
 414      /**
 415       * Get the id of this attempt.
 416       *
 417       * @return int the attempt id.
 418       */
 419      public function get_attemptid() {
 420          return $this->attempt->id;
 421      }
 422  
 423      /**
 424       * Get the question-usage id corresponding to this quiz attempt.
 425       *
 426       * @return int the attempt unique id.
 427       */
 428      public function get_uniqueid() {
 429          return $this->attempt->uniqueid;
 430      }
 431  
 432      /**
 433       * Get the raw quiz attempt object.
 434       *
 435       * @return stdClass the row from the quiz_attempts table.
 436       */
 437      public function get_attempt() {
 438          return $this->attempt;
 439      }
 440  
 441      /**
 442       * Get the attempt number.
 443       *
 444       * @return int the number of this attempt (is it this user's first, second, ... attempt).
 445       */
 446      public function get_attempt_number() {
 447          return $this->attempt->attempt;
 448      }
 449  
 450      /**
 451       * Get the state of this attempt.
 452       *
 453       * @return string {@see IN_PROGRESS}, {@see FINISHED}, {@see OVERDUE} or {@see ABANDONED}.
 454       */
 455      public function get_state() {
 456          return $this->attempt->state;
 457      }
 458  
 459      /**
 460       * Get the id of the user this attempt belongs to.
 461       * @return int user id.
 462       */
 463      public function get_userid() {
 464          return $this->attempt->userid;
 465      }
 466  
 467      /**
 468       * Get the current page of the attempt
 469       * @return int page number.
 470       */
 471      public function get_currentpage() {
 472          return $this->attempt->currentpage;
 473      }
 474  
 475      /**
 476       * Get the total number of marks that the user had scored on all the questions.
 477       *
 478       * @return float
 479       */
 480      public function get_sum_marks() {
 481          return $this->attempt->sumgrades;
 482      }
 483  
 484      /**
 485       * Has this attempt been finished?
 486       *
 487       * States {@see FINISHED} and {@see ABANDONED} are both considered finished in this state.
 488       * Other states are not.
 489       *
 490       * @return bool
 491       */
 492      public function is_finished() {
 493          return $this->attempt->state == self::FINISHED || $this->attempt->state == self::ABANDONED;
 494      }
 495  
 496      /**
 497       * Is this attempt a preview?
 498       *
 499       * @return bool true if it is.
 500       */
 501      public function is_preview() {
 502          return $this->attempt->preview;
 503      }
 504  
 505      /**
 506       * Does this attempt belong to the current user?
 507       *
 508       * @return bool true => own attempt/preview. false => reviewing someone else's.
 509       */
 510      public function is_own_attempt() {
 511          global $USER;
 512          return $this->attempt->userid == $USER->id;
 513      }
 514  
 515      /**
 516       * Is this attempt is a preview belonging to the current user.
 517       *
 518       * @return bool true if it is.
 519       */
 520      public function is_own_preview() {
 521          return $this->is_own_attempt() &&
 522                  $this->is_preview_user() && $this->attempt->preview;
 523      }
 524  
 525      /**
 526       * Is the current user allowed to review this attempt. This applies when
 527       * {@see is_own_attempt()} returns false.
 528       *
 529       * @return bool whether the review should be allowed.
 530       */
 531      public function is_review_allowed() {
 532          if (!$this->has_capability('mod/quiz:viewreports')) {
 533              return false;
 534          }
 535  
 536          $cm = $this->get_cm();
 537          if ($this->has_capability('moodle/site:accessallgroups') ||
 538                  groups_get_activity_groupmode($cm) != SEPARATEGROUPS) {
 539              return true;
 540          }
 541  
 542          // Check the users have at least one group in common.
 543          $teachersgroups = groups_get_activity_allowed_groups($cm);
 544          $studentsgroups = groups_get_all_groups(
 545                  $cm->course, $this->attempt->userid, $cm->groupingid);
 546          return $teachersgroups && $studentsgroups &&
 547                  array_intersect(array_keys($teachersgroups), array_keys($studentsgroups));
 548      }
 549  
 550      /**
 551       * Has the student, in this attempt, engaged with the quiz in a non-trivial way?
 552       *
 553       * That is, is there any question worth a non-zero number of marks, where
 554       * the student has made some response that we have saved?
 555       *
 556       * @return bool true if we have saved a response for at least one graded question.
 557       */
 558      public function has_response_to_at_least_one_graded_question() {
 559          foreach ($this->quba->get_attempt_iterator() as $qa) {
 560              if ($qa->get_max_mark() == 0) {
 561                  continue;
 562              }
 563              if ($qa->get_num_steps() > 1) {
 564                  return true;
 565              }
 566          }
 567          return false;
 568      }
 569  
 570      /**
 571       * Do any questions in this attempt need to be graded manually?
 572       *
 573       * @return bool True if we have at least one question still needs manual grading.
 574       */
 575      public function requires_manual_grading(): bool {
 576          return $this->quba->get_total_mark() === null;
 577      }
 578  
 579      /**
 580       * Get extra summary information about this attempt.
 581       *
 582       * Some behaviours may be able to provide interesting summary information
 583       * about the attempt as a whole, and this method provides access to that data.
 584       * To see how this works, try setting a quiz to one of the CBM behaviours,
 585       * and then look at the extra information displayed at the top of the quiz
 586       * review page once you have submitted an attempt.
 587       *
 588       * In the return value, the array keys are identifiers of the form
 589       * qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
 590       * The values are arrays with two items, title and content. Each of these
 591       * will be either a string, or a renderable.
 592       *
 593       * @param question_display_options $options the display options for this quiz attempt at this time.
 594       * @return array as described above.
 595       */
 596      public function get_additional_summary_data(question_display_options $options) {
 597          return $this->quba->get_summary_information($options);
 598      }
 599  
 600      /**
 601       * Get the overall feedback corresponding to a particular mark.
 602       *
 603       * @param number $grade a particular grade.
 604       * @return string the feedback.
 605       */
 606      public function get_overall_feedback($grade) {
 607          return quiz_feedback_for_grade($grade, $this->get_quiz(),
 608                  $this->quizobj->get_context());
 609      }
 610  
 611      /**
 612       * Wrapper round the has_capability function that automatically passes in the quiz context.
 613       *
 614       * @param string $capability the name of the capability to check. For example mod/forum:view.
 615       * @param int|null $userid A user id. If null checks the permissions of the current user.
 616       * @param bool $doanything If false, ignore effect of admin role assignment.
 617       * @return boolean true if the user has this capability, otherwise false.
 618       */
 619      public function has_capability($capability, $userid = null, $doanything = true) {
 620          return $this->quizobj->has_capability($capability, $userid, $doanything);
 621      }
 622  
 623      /**
 624       * Wrapper round the require_capability function that automatically passes in the quiz context.
 625       *
 626       * @param string $capability the name of the capability to check. For example mod/forum:view.
 627       * @param int|null $userid A user id. If null checks the permissions of the current user.
 628       * @param bool $doanything If false, ignore effect of admin role assignment.
 629       */
 630      public function require_capability($capability, $userid = null, $doanything = true) {
 631          $this->quizobj->require_capability($capability, $userid, $doanything);
 632      }
 633  
 634      /**
 635       * Check the appropriate capability to see whether this user may review their own attempt.
 636       * If not, prints an error.
 637       */
 638      public function check_review_capability() {
 639          if ($this->get_attempt_state() == display_options::IMMEDIATELY_AFTER) {
 640              $capability = 'mod/quiz:attempt';
 641          } else {
 642              $capability = 'mod/quiz:reviewmyattempts';
 643          }
 644  
 645          // These next tests are in a slightly funny order. The point is that the
 646          // common and most performance-critical case is students attempting a quiz,
 647          // so we want to check that permission first.
 648  
 649          if ($this->has_capability($capability)) {
 650              // User has the permission that lets you do the quiz as a student. Fine.
 651              return;
 652          }
 653  
 654          if ($this->has_capability('mod/quiz:viewreports') ||
 655                  $this->has_capability('mod/quiz:preview')) {
 656              // User has the permission that lets teachers review. Fine.
 657              return;
 658          }
 659  
 660          // They should not be here. Trigger the standard no-permission error
 661          // but using the name of the student capability.
 662          // We know this will fail. We just want the standard exception thrown.
 663          $this->require_capability($capability);
 664      }
 665  
 666      /**
 667       * Checks whether a user may navigate to a particular slot.
 668       *
 669       * @param int $slot the target slot (currently does not affect the answer).
 670       * @return bool true if the navigation should be allowed.
 671       */
 672      public function can_navigate_to($slot) {
 673          if ($this->attempt->state == self::OVERDUE) {
 674              // When the attempt is overdue, students can only see the
 675              // attempt summary page and cannot navigate anywhere else.
 676              return false;
 677          }
 678  
 679          return $this->get_navigation_method() == QUIZ_NAVMETHOD_FREE;
 680      }
 681  
 682      /**
 683       * Get where we are time-wise in relation to this attempt and the quiz settings.
 684       *
 685       * @return int one of {@see display_options::DURING}, {@see display_options::IMMEDIATELY_AFTER},
 686       *      {@see display_options::LATER_WHILE_OPEN} or {@see display_options::AFTER_CLOSE}.
 687       */
 688      public function get_attempt_state() {
 689          return quiz_attempt_state($this->get_quiz(), $this->attempt);
 690      }
 691  
 692      /**
 693       * Wrapper that the correct display_options for this quiz at the
 694       * moment.
 695       *
 696       * @param bool $reviewing true for options when reviewing, false for when attempting.
 697       * @return question_display_options the render options for this user on this attempt.
 698       */
 699      public function get_display_options($reviewing) {
 700          if ($reviewing) {
 701              if (is_null($this->reviewoptions)) {
 702                  $this->reviewoptions = quiz_get_review_options($this->get_quiz(),
 703                          $this->attempt, $this->quizobj->get_context());
 704                  if ($this->is_own_preview()) {
 705                      // It should  always be possible for a teacher to review their
 706                      // own preview irrespective of the review options settings.
 707                      $this->reviewoptions->attempt = true;
 708                  }
 709              }
 710              return $this->reviewoptions;
 711  
 712          } else {
 713              $options = display_options::make_from_quiz($this->get_quiz(),
 714                      display_options::DURING);
 715              $options->flags = quiz_get_flag_option($this->attempt, $this->quizobj->get_context());
 716              return $options;
 717          }
 718      }
 719  
 720      /**
 721       * Wrapper that the correct display_options for this quiz at the
 722       * moment.
 723       *
 724       * @param bool $reviewing true for review page, else attempt page.
 725       * @param int $slot which question is being displayed.
 726       * @param moodle_url $thispageurl to return to after the editing form is
 727       *      submitted or cancelled. If null, no edit link will be generated.
 728       *
 729       * @return question_display_options the render options for this user on this
 730       *      attempt, with extra info to generate an edit link, if applicable.
 731       */
 732      public function get_display_options_with_edit_link($reviewing, $slot, $thispageurl) {
 733          $options = clone($this->get_display_options($reviewing));
 734  
 735          if (!$thispageurl) {
 736              return $options;
 737          }
 738  
 739          if (!($reviewing || $this->is_preview())) {
 740              return $options;
 741          }
 742  
 743          $question = $this->quba->get_question($slot, false);
 744          if (!question_has_capability_on($question, 'edit', $question->category)) {
 745              return $options;
 746          }
 747  
 748          $options->editquestionparams['cmid'] = $this->get_cmid();
 749          $options->editquestionparams['returnurl'] = $thispageurl;
 750  
 751          return $options;
 752      }
 753  
 754      /**
 755       * Is a particular page the last one in the quiz?
 756       *
 757       * @param int $page a page number
 758       * @return bool true if that is the last page of the quiz.
 759       */
 760      public function is_last_page($page) {
 761          return $page == count($this->pagelayout) - 1;
 762      }
 763  
 764      /**
 765       * Return the list of slot numbers for either a given page of the quiz, or for the
 766       * whole quiz.
 767       *
 768       * @param mixed $page string 'all' or integer page number.
 769       * @return array the requested list of slot numbers.
 770       */
 771      public function get_slots($page = 'all') {
 772          if ($page === 'all') {
 773              $numbers = [];
 774              foreach ($this->pagelayout as $numbersonpage) {
 775                  $numbers = array_merge($numbers, $numbersonpage);
 776              }
 777              return $numbers;
 778          } else {
 779              return $this->pagelayout[$page];
 780          }
 781      }
 782  
 783      /**
 784       * Return the list of slot numbers for either a given page of the quiz, or for the
 785       * whole quiz.
 786       *
 787       * @param mixed $page string 'all' or integer page number.
 788       * @return array the requested list of slot numbers.
 789       */
 790      public function get_active_slots($page = 'all') {
 791          $activeslots = [];
 792          foreach ($this->get_slots($page) as $slot) {
 793              if (!$this->is_blocked_by_previous_question($slot)) {
 794                  $activeslots[] = $slot;
 795              }
 796          }
 797          return $activeslots;
 798      }
 799  
 800      /**
 801       * Helper method for unit tests. Get the underlying question usage object.
 802       *
 803       * @return question_usage_by_activity the usage.
 804       */
 805      public function get_question_usage() {
 806          if (!(PHPUNIT_TEST || defined('BEHAT_TEST'))) {
 807              throw new coding_exception('get_question_usage is only for use in unit tests. ' .
 808                      'For other operations, use the quiz_attempt api, or extend it properly.');
 809          }
 810          return $this->quba;
 811      }
 812  
 813      /**
 814       * Get the question_attempt object for a particular question in this attempt.
 815       *
 816       * @param int $slot the number used to identify this question within this attempt.
 817       * @return question_attempt the requested question_attempt.
 818       */
 819      public function get_question_attempt($slot) {
 820          return $this->quba->get_question_attempt($slot);
 821      }
 822  
 823      /**
 824       * Get all the question_attempt objects that have ever appeared in a given slot.
 825       *
 826       * This relates to the 'Try another question like this one' feature.
 827       *
 828       * @param int $slot the number used to identify this question within this attempt.
 829       * @return question_attempt[] the attempts.
 830       */
 831      public function all_question_attempts_originally_in_slot($slot) {
 832          $qas = [];
 833          foreach ($this->quba->get_attempt_iterator() as $qa) {
 834              if ($qa->get_metadata('originalslot') == $slot) {
 835                  $qas[] = $qa;
 836              }
 837          }
 838          $qas[] = $this->quba->get_question_attempt($slot);
 839          return $qas;
 840      }
 841  
 842      /**
 843       * Is a particular question in this attempt a real question, or something like a description.
 844       *
 845       * @param int $slot the number used to identify this question within this attempt.
 846       * @return int whether that question is a real question. Actually returns the
 847       *     question length, which could theoretically be greater than one.
 848       */
 849      public function is_real_question($slot) {
 850          return $this->quba->get_question($slot, false)->length;
 851      }
 852  
 853      /**
 854       * Is a particular question in this attempt a real question, or something like a description.
 855       *
 856       * @param int $slot the number used to identify this question within this attempt.
 857       * @return bool whether that question is a real question.
 858       */
 859      public function is_question_flagged($slot) {
 860          return $this->quba->get_question_attempt($slot)->is_flagged();
 861      }
 862  
 863      /**
 864       * Checks whether the question in this slot requires the previous
 865       * question to have been completed.
 866       *
 867       * @param int $slot the number used to identify this question within this attempt.
 868       * @return bool whether the previous question must have been completed before
 869       *      this one can be seen.
 870       */
 871      public function is_blocked_by_previous_question($slot) {
 872          return $slot > 1 && isset($this->slots[$slot]) && $this->slots[$slot]->requireprevious &&
 873              !$this->slots[$slot]->section->shufflequestions &&
 874              !$this->slots[$slot - 1]->section->shufflequestions &&
 875              $this->get_navigation_method() != QUIZ_NAVMETHOD_SEQ &&
 876              !$this->get_question_state($slot - 1)->is_finished() &&
 877              $this->quba->can_question_finish_during_attempt($slot - 1);
 878      }
 879  
 880      /**
 881       * Is it possible for this question to be re-started within this attempt?
 882       *
 883       * @param int $slot the number used to identify this question within this attempt.
 884       * @return bool whether the student should be given the option to restart this question now.
 885       */
 886      public function can_question_be_redone_now($slot) {
 887          return $this->get_quiz()->canredoquestions && !$this->is_finished() &&
 888                  $this->get_question_state($slot)->is_finished();
 889      }
 890  
 891      /**
 892       * Given a slot in this attempt, which may or not be a redone question, return the original slot.
 893       *
 894       * @param int $slot identifies a particular question in this attempt.
 895       * @return int the slot where this question was originally.
 896       */
 897      public function get_original_slot($slot) {
 898          $originalslot = $this->quba->get_question_attempt_metadata($slot, 'originalslot');
 899          if ($originalslot) {
 900              return $originalslot;
 901          } else {
 902              return $slot;
 903          }
 904      }
 905  
 906      /**
 907       * Get the displayed question number for a slot.
 908       *
 909       * @param int $slot the number used to identify this question within this attempt.
 910       * @return string the displayed question number for the question in this slot.
 911       *      For example '1', '2', '3' or 'i'.
 912       */
 913      public function get_question_number($slot): string {
 914          return $this->questionnumbers[$slot];
 915      }
 916  
 917      /**
 918       * If the section heading, if any, that should come just before this slot.
 919       *
 920       * @param int $slot identifies a particular question in this attempt.
 921       * @return string|null the required heading, or null if there is not one here.
 922       */
 923      public function get_heading_before_slot($slot) {
 924          if ($this->slots[$slot]->firstinsection) {
 925              return $this->slots[$slot]->section->heading;
 926          } else {
 927              return null;
 928          }
 929      }
 930  
 931      /**
 932       * Return the page of the quiz where this question appears.
 933       *
 934       * @param int $slot the number used to identify this question within this attempt.
 935       * @return int the page of the quiz this question appears on.
 936       */
 937      public function get_question_page($slot) {
 938          return $this->questionpages[$slot];
 939      }
 940  
 941      /**
 942       * Return the grade obtained on a particular question, if the user is permitted
 943       * to see it. You must previously have called load_question_states to load the
 944       * state data about this question.
 945       *
 946       * @param int $slot the number used to identify this question within this attempt.
 947       * @return string the formatted grade, to the number of decimal places specified
 948       *      by the quiz.
 949       */
 950      public function get_question_name($slot) {
 951          return $this->quba->get_question($slot, false)->name;
 952      }
 953  
 954      /**
 955       * Return the {@see question_state} that this question is in.
 956       *
 957       * @param int $slot the number used to identify this question within this attempt.
 958       * @return question_state the state this question is in.
 959       */
 960      public function get_question_state($slot) {
 961          return $this->quba->get_question_state($slot);
 962      }
 963  
 964      /**
 965       * Return the grade obtained on a particular question, if the user is permitted
 966       * to see it. You must previously have called load_question_states to load the
 967       * state data about this question.
 968       *
 969       * @param int $slot the number used to identify this question within this attempt.
 970       * @param bool $showcorrectness Whether right/partial/wrong states should
 971       *      be distinguished.
 972       * @return string the formatted grade, to the number of decimal places specified
 973       *      by the quiz.
 974       */
 975      public function get_question_status($slot, $showcorrectness) {
 976          return $this->quba->get_question_state_string($slot, $showcorrectness);
 977      }
 978  
 979      /**
 980       * Return the grade obtained on a particular question, if the user is permitted
 981       * to see it. You must previously have called load_question_states to load the
 982       * state data about this question.
 983       *
 984       * @param int $slot the number used to identify this question within this attempt.
 985       * @param bool $showcorrectness Whether right/partial/wrong states should
 986       *      be distinguished.
 987       * @return string class name for this state.
 988       */
 989      public function get_question_state_class($slot, $showcorrectness) {
 990          return $this->quba->get_question_state_class($slot, $showcorrectness);
 991      }
 992  
 993      /**
 994       * Return the grade obtained on a particular question.
 995       *
 996       * You must previously have called load_question_states to load the state
 997       * data about this question.
 998       *
 999       * @param int $slot the number used to identify this question within this attempt.
1000       * @return string the formatted grade, to the number of decimal places specified by the quiz.
1001       */
1002      public function get_question_mark($slot) {
1003          return quiz_format_question_grade($this->get_quiz(), $this->quba->get_question_mark($slot));
1004      }
1005  
1006      /**
1007       * Get the time of the most recent action performed on a question.
1008       *
1009       * @param int $slot the number used to identify this question within this usage.
1010       * @return int timestamp.
1011       */
1012      public function get_question_action_time($slot) {
1013          return $this->quba->get_question_action_time($slot);
1014      }
1015  
1016      /**
1017       * Return the question type name for a given slot within the current attempt.
1018       *
1019       * @param int $slot the number used to identify this question within this attempt.
1020       * @return string the question type name.
1021       */
1022      public function get_question_type_name($slot) {
1023          return $this->quba->get_question($slot, false)->get_type_name();
1024      }
1025  
1026      /**
1027       * Get the time remaining for an in-progress attempt, if the time is short
1028       * enough that it would be worth showing a timer.
1029       *
1030       * @param int $timenow the time to consider as 'now'.
1031       * @return int|false the number of seconds remaining for this attempt.
1032       *      False if there is no limit.
1033       */
1034      public function get_time_left_display($timenow) {
1035          if ($this->attempt->state != self::IN_PROGRESS) {
1036              return false;
1037          }
1038          return $this->get_access_manager($timenow)->get_time_left_display($this->attempt, $timenow);
1039      }
1040  
1041  
1042      /**
1043       * Get the time when this attempt was submitted.
1044       *
1045       * @return int timestamp, or 0 if it has not been submitted yet.
1046       */
1047      public function get_submitted_date() {
1048          return $this->attempt->timefinish;
1049      }
1050  
1051      /**
1052       * If the attempt is in an applicable state, work out the time by which the
1053       * student should next do something.
1054       *
1055       * @return int timestamp by which the student needs to do something.
1056       */
1057      public function get_due_date() {
1058          $deadlines = [];
1059          if ($this->quizobj->get_quiz()->timelimit) {
1060              $deadlines[] = $this->attempt->timestart + $this->quizobj->get_quiz()->timelimit;
1061          }
1062          if ($this->quizobj->get_quiz()->timeclose) {
1063              $deadlines[] = $this->quizobj->get_quiz()->timeclose;
1064          }
1065          if ($deadlines) {
1066              $duedate = min($deadlines);
1067          } else {
1068              return false;
1069          }
1070  
1071          switch ($this->attempt->state) {
1072              case self::IN_PROGRESS:
1073                  return $duedate;
1074  
1075              case self::OVERDUE:
1076                  return $duedate + $this->quizobj->get_quiz()->graceperiod;
1077  
1078              default:
1079                  throw new coding_exception('Unexpected state: ' . $this->attempt->state);
1080          }
1081      }
1082  
1083      // URLs related to this attempt ============================================.
1084  
1085      /**
1086       * Get the URL of this quiz's view.php page.
1087       *
1088       * @return moodle_url quiz view url.
1089       */
1090      public function view_url() {
1091          return $this->quizobj->view_url();
1092      }
1093  
1094      /**
1095       * Get the URL to start or continue an attempt.
1096       *
1097       * @param int|null $slot which question in the attempt to go to after starting (optional).
1098       * @param int $page which page in the attempt to go to after starting.
1099       * @return moodle_url the URL of this quiz's edit page. Needs to be POSTed to with a cmid parameter.
1100       */
1101      public function start_attempt_url($slot = null, $page = -1) {
1102          if ($page == -1 && !is_null($slot)) {
1103              $page = $this->get_question_page($slot);
1104          } else {
1105              $page = 0;
1106          }
1107          return $this->quizobj->start_attempt_url($page);
1108      }
1109  
1110      /**
1111       * Generates the title of the attempt page.
1112       *
1113       * @param int $page the page number (starting with 0) in the attempt.
1114       * @return string attempt page title.
1115       */
1116      public function attempt_page_title(int $page) : string {
1117          if ($this->get_num_pages() > 1) {
1118              $a = new stdClass();
1119              $a->name = $this->get_quiz_name();
1120              $a->currentpage = $page + 1;
1121              $a->totalpages = $this->get_num_pages();
1122              $title = get_string('attempttitlepaged', 'quiz', $a);
1123          } else {
1124              $title = get_string('attempttitle', 'quiz', $this->get_quiz_name());
1125          }
1126  
1127          return $title;
1128      }
1129  
1130      /**
1131       * Get the URL of a particular page within this attempt.
1132       *
1133       * @param int|null $slot if specified, the slot number of a specific question to link to.
1134       * @param int $page if specified, a particular page to link to. If not given deduced
1135       *      from $slot, or goes to the first page.
1136       * @param int $thispage if not -1, the current page. Will cause links to other things on
1137       *      this page to be output as only a fragment.
1138       * @return moodle_url the URL to continue this attempt.
1139       */
1140      public function attempt_url($slot = null, $page = -1, $thispage = -1) {
1141          return $this->page_and_question_url('attempt', $slot, $page, false, $thispage);
1142      }
1143  
1144      /**
1145       * Generates the title of the summary page.
1146       *
1147       * @return string summary page title.
1148       */
1149      public function summary_page_title() : string {
1150          return get_string('attemptsummarytitle', 'quiz', $this->get_quiz_name());
1151      }
1152  
1153      /**
1154       * Get the URL of the summary page of this attempt.
1155       *
1156       * @return moodle_url the URL of this quiz's summary page.
1157       */
1158      public function summary_url() {
1159          return new moodle_url('/mod/quiz/summary.php', ['attempt' => $this->attempt->id, 'cmid' => $this->get_cmid()]);
1160      }
1161  
1162      /**
1163       * Get the URL to which the attempt data should be submitted.
1164       *
1165       * @return moodle_url the URL of this quiz's summary page.
1166       */
1167      public function processattempt_url() {
1168          return new moodle_url('/mod/quiz/processattempt.php');
1169      }
1170  
1171      /**
1172       * Generates the title of the review page.
1173       *
1174       * @param int $page the page number (starting with 0) in the attempt.
1175       * @param bool $showall whether the review page contains the entire attempt on one page.
1176       * @return string title of the review page.
1177       */
1178      public function review_page_title(int $page, bool $showall = false) : string {
1179          if (!$showall && $this->get_num_pages() > 1) {
1180              $a = new stdClass();
1181              $a->name = $this->get_quiz_name();
1182              $a->currentpage = $page + 1;
1183              $a->totalpages = $this->get_num_pages();
1184              $title = get_string('attemptreviewtitlepaged', 'quiz', $a);
1185          } else {
1186              $title = get_string('attemptreviewtitle', 'quiz', $this->get_quiz_name());
1187          }
1188  
1189          return $title;
1190      }
1191  
1192      /**
1193       * Get the URL of a particular page in the review of this attempt.
1194       *
1195       * @param int|null $slot indicates which question to link to.
1196       * @param int $page if specified, the URL of this particular page of the attempt, otherwise
1197       *      the URL will go to the first page.  If -1, deduce $page from $slot.
1198       * @param bool|null $showall if true, the URL will be to review the entire attempt on one page,
1199       *      and $page will be ignored. If null, a sensible default will be chosen.
1200       * @param int $thispage if not -1, the current page. Will cause links to other things on
1201       *      this page to be output as only a fragment.
1202       * @return moodle_url the URL to review this attempt.
1203       */
1204      public function review_url($slot = null, $page = -1, $showall = null, $thispage = -1) {
1205          return $this->page_and_question_url('review', $slot, $page, $showall, $thispage);
1206      }
1207  
1208      /**
1209       * By default, should this script show all questions on one page for this attempt?
1210       *
1211       * @param string $script the script name, e.g. 'attempt', 'summary', 'review'.
1212       * @return bool whether show all on one page should be on by default.
1213       */
1214      public function get_default_show_all($script) {
1215          return $script === 'review' && count($this->questionpages) < self::MAX_SLOTS_FOR_DEFAULT_REVIEW_SHOW_ALL;
1216      }
1217  
1218      // Bits of content =========================================================.
1219  
1220      /**
1221       * If $reviewoptions->attempt is false, meaning that students can't review this
1222       * attempt at the moment, return an appropriate string explaining why.
1223       *
1224       * @param bool $short if true, return a shorter string.
1225       * @return string an appropriate message.
1226       */
1227      public function cannot_review_message($short = false) {
1228          return $this->quizobj->cannot_review_message(
1229                  $this->get_attempt_state(), $short);
1230      }
1231  
1232      /**
1233       * Initialise the JS etc. required all the questions on a page.
1234       *
1235       * @param int|string $page a page number, or 'all'.
1236       * @param bool $showall if true, forces page number to all.
1237       * @return string HTML to output - mostly obsolete, will probably be an empty string.
1238       */
1239      public function get_html_head_contributions($page = 'all', $showall = false) {
1240          if ($showall) {
1241              $page = 'all';
1242          }
1243          $result = '';
1244          foreach ($this->get_slots($page) as $slot) {
1245              $result .= $this->quba->render_question_head_html($slot);
1246          }
1247          $result .= question_engine::initialise_js();
1248          return $result;
1249      }
1250  
1251      /**
1252       * Initialise the JS etc. required by one question.
1253       *
1254       * @param int $slot the question slot number.
1255       * @return string HTML to output - but this is mostly obsolete. Will probably be an empty string.
1256       */
1257      public function get_question_html_head_contributions($slot) {
1258          return $this->quba->render_question_head_html($slot) .
1259                  question_engine::initialise_js();
1260      }
1261  
1262      /**
1263       * Print the HTML for the start new preview button, if the current user
1264       * is allowed to see one.
1265       *
1266       * @return string HTML for the button.
1267       */
1268      public function restart_preview_button() {
1269          global $OUTPUT;
1270          if ($this->is_preview() && $this->is_preview_user()) {
1271              return $OUTPUT->single_button(new moodle_url(
1272                      $this->start_attempt_url(), ['forcenew' => true]),
1273                      get_string('startnewpreview', 'quiz'));
1274          } else {
1275              return '';
1276          }
1277      }
1278  
1279      /**
1280       * Generate the HTML that displays the question in its current state, with
1281       * the appropriate display options.
1282       *
1283       * @param int $slot identifies the question in the attempt.
1284       * @param bool $reviewing is the being printed on an attempt or a review page.
1285       * @param renderer $renderer the quiz renderer.
1286       * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1287       * @return string HTML for the question in its current state.
1288       */
1289      public function render_question($slot, $reviewing, renderer $renderer, $thispageurl = null) {
1290          if ($this->is_blocked_by_previous_question($slot)) {
1291              $placeholderqa = $this->make_blocked_question_placeholder($slot);
1292  
1293              $displayoptions = $this->get_display_options($reviewing);
1294              $displayoptions->manualcomment = question_display_options::HIDDEN;
1295              $displayoptions->history = question_display_options::HIDDEN;
1296              $displayoptions->readonly = true;
1297              $displayoptions->versioninfo = question_display_options::HIDDEN;
1298  
1299              return html_writer::div($placeholderqa->render($displayoptions,
1300                      $this->get_question_number($this->get_original_slot($slot))),
1301                      'mod_quiz-blocked_question_warning');
1302          }
1303  
1304          return $this->render_question_helper($slot, $reviewing, $thispageurl, $renderer, null);
1305      }
1306  
1307      /**
1308       * Helper used by {@see render_question()} and {@see render_question_at_step()}.
1309       *
1310       * @param int $slot identifies the question in the attempt.
1311       * @param bool $reviewing is the being printed on an attempt or a review page.
1312       * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1313       * @param renderer $renderer the quiz renderer.
1314       * @param int|null $seq the seq number of the past state to display.
1315       * @return string HTML fragment.
1316       */
1317      protected function render_question_helper($slot, $reviewing, $thispageurl,
1318              renderer $renderer, $seq) {
1319          $originalslot = $this->get_original_slot($slot);
1320          $number = $this->get_question_number($originalslot);
1321          $displayoptions = $this->get_display_options_with_edit_link($reviewing, $slot, $thispageurl);
1322  
1323          if ($slot != $originalslot) {
1324              $originalmaxmark = $this->get_question_attempt($slot)->get_max_mark();
1325              $this->get_question_attempt($slot)->set_max_mark($this->get_question_attempt($originalslot)->get_max_mark());
1326          }
1327  
1328          if ($this->can_question_be_redone_now($slot)) {
1329              $displayoptions->extrainfocontent = $renderer->redo_question_button(
1330                      $slot, $displayoptions->readonly);
1331          }
1332  
1333          if ($displayoptions->history && $displayoptions->questionreviewlink) {
1334              $links = $this->links_to_other_redos($slot, $displayoptions->questionreviewlink);
1335              if ($links) {
1336                  $displayoptions->extrahistorycontent = html_writer::tag('p',
1337                          get_string('redoesofthisquestion', 'quiz', $renderer->render($links)));
1338              }
1339          }
1340  
1341          if ($seq === null) {
1342              $output = $this->quba->render_question($slot, $displayoptions, $number);
1343          } else {
1344              $output = $this->quba->render_question_at_step($slot, $seq, $displayoptions, $number);
1345          }
1346  
1347          if ($slot != $originalslot) {
1348              $this->get_question_attempt($slot)->set_max_mark($originalmaxmark);
1349          }
1350  
1351          return $output;
1352      }
1353  
1354      /**
1355       * Create a fake question to be displayed in place of a question that is blocked
1356       * until the previous question has been answered.
1357       *
1358       * @param int $slot int slot number of the question to replace.
1359       * @return question_attempt the placeholder question attempt.
1360       */
1361      protected function make_blocked_question_placeholder($slot) {
1362          $replacedquestion = $this->get_question_attempt($slot)->get_question(false);
1363  
1364          question_bank::load_question_definition_classes('description');
1365          $question = new qtype_description_question();
1366          $question->id = $replacedquestion->id;
1367          $question->category = null;
1368          $question->parent = 0;
1369          $question->qtype = question_bank::get_qtype('description');
1370          $question->name = '';
1371          $question->questiontext = get_string('questiondependsonprevious', 'quiz');
1372          $question->questiontextformat = FORMAT_HTML;
1373          $question->generalfeedback = '';
1374          $question->defaultmark = $this->quba->get_question_max_mark($slot);
1375          $question->length = $replacedquestion->length;
1376          $question->penalty = 0;
1377          $question->stamp = '';
1378          $question->status = \core_question\local\bank\question_version_status::QUESTION_STATUS_READY;
1379          $question->timecreated = null;
1380          $question->timemodified = null;
1381          $question->createdby = null;
1382          $question->modifiedby = null;
1383  
1384          $placeholderqa = new question_attempt($question, $this->quba->get_id(),
1385                  null, $this->quba->get_question_max_mark($slot));
1386          $placeholderqa->set_slot($slot);
1387          $placeholderqa->start($this->get_quiz()->preferredbehaviour, 1);
1388          $placeholderqa->set_flagged($this->is_question_flagged($slot));
1389          return $placeholderqa;
1390      }
1391  
1392      /**
1393       * Like {@see render_question()} but displays the question at the past step
1394       * indicated by $seq, rather than showing the latest step.
1395       *
1396       * @param int $slot the slot number of a question in this quiz attempt.
1397       * @param int $seq the seq number of the past state to display.
1398       * @param bool $reviewing is the being printed on an attempt or a review page.
1399       * @param renderer $renderer the quiz renderer.
1400       * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1401       * @return string HTML for the question in its current state.
1402       */
1403      public function render_question_at_step($slot, $seq, $reviewing,
1404              renderer $renderer, $thispageurl = null) {
1405          return $this->render_question_helper($slot, $reviewing, $thispageurl, $renderer, $seq);
1406      }
1407  
1408      /**
1409       * Wrapper round print_question from lib/questionlib.php.
1410       *
1411       * @param int $slot the id of a question in this quiz attempt.
1412       * @return string HTML of the question.
1413       */
1414      public function render_question_for_commenting($slot) {
1415          $options = $this->get_display_options(true);
1416          $options->generalfeedback = question_display_options::HIDDEN;
1417          $options->manualcomment = question_display_options::EDITABLE;
1418          return $this->quba->render_question($slot, $options,
1419                  $this->get_question_number($slot));
1420      }
1421  
1422      /**
1423       * Check whether access should be allowed to a particular file.
1424       *
1425       * @param int $slot the slot of a question in this quiz attempt.
1426       * @param bool $reviewing is the being printed on an attempt or a review page.
1427       * @param int $contextid the file context id from the request.
1428       * @param string $component the file component from the request.
1429       * @param string $filearea the file area from the request.
1430       * @param array $args extra part components from the request.
1431       * @param bool $forcedownload whether to force download.
1432       * @return bool true if the file can be accessed.
1433       */
1434      public function check_file_access($slot, $reviewing, $contextid, $component,
1435              $filearea, $args, $forcedownload) {
1436          $options = $this->get_display_options($reviewing);
1437  
1438          // Check permissions - warning there is similar code in review.php and
1439          // reviewquestion.php. If you change on, change them all.
1440          if ($reviewing && $this->is_own_attempt() && !$options->attempt) {
1441              return false;
1442          }
1443  
1444          if ($reviewing && !$this->is_own_attempt() && !$this->is_review_allowed()) {
1445              return false;
1446          }
1447  
1448          return $this->quba->check_file_access($slot, $options,
1449                  $component, $filearea, $args, $forcedownload);
1450      }
1451  
1452      /**
1453       * Get the navigation panel object for this attempt.
1454       *
1455       * @param renderer $output the quiz renderer to use to output things.
1456       * @param string $panelclass The type of panel, navigation_panel_attempt::class or navigation_panel_review::class
1457       * @param int $page the current page number.
1458       * @param bool $showall whether we are showing the whole quiz on one page. (Used by review.php.)
1459       * @return block_contents the requested object.
1460       */
1461      public function get_navigation_panel(renderer $output,
1462               $panelclass, $page, $showall = false) {
1463          $panel = new $panelclass($this, $this->get_display_options(true), $page, $showall);
1464  
1465          $bc = new block_contents();
1466          $bc->attributes['id'] = 'mod_quiz_navblock';
1467          $bc->attributes['role'] = 'navigation';
1468          $bc->title = get_string('quiznavigation', 'quiz');
1469          $bc->content = $output->navigation_panel($panel);
1470          return $bc;
1471      }
1472  
1473      /**
1474       * Return an array of variant URLs to other attempts at this quiz.
1475       *
1476       * The $url passed in must contain an attempt parameter.
1477       *
1478       * The {@see links_to_other_attempts} object returned contains an
1479       * array with keys that are the attempt number, 1, 2, 3.
1480       * The array values are either a {@see moodle_url} with the attempt parameter
1481       * updated to point to the attempt id of the other attempt, or null corresponding
1482       * to the current attempt number.
1483       *
1484       * @param moodle_url $url a URL.
1485       * @return links_to_other_attempts|bool containing array int => null|moodle_url.
1486       *      False if none.
1487       */
1488      public function links_to_other_attempts(moodle_url $url) {
1489          $attempts = quiz_get_user_attempts($this->get_quiz()->id, $this->attempt->userid, 'all');
1490          if (count($attempts) <= 1) {
1491              return false;
1492          }
1493  
1494          $links = new links_to_other_attempts();
1495          foreach ($attempts as $at) {
1496              if ($at->id == $this->attempt->id) {
1497                  $links->links[$at->attempt] = null;
1498              } else {
1499                  $links->links[$at->attempt] = new moodle_url($url, ['attempt' => $at->id]);
1500              }
1501          }
1502          return $links;
1503      }
1504  
1505      /**
1506       * Return an array of variant URLs to other redos of the question in a particular slot.
1507       *
1508       * The $url passed in must contain a slot parameter.
1509       *
1510       * The {@see links_to_other_attempts} object returned contains an
1511       * array with keys that are the redo number, 1, 2, 3.
1512       * The array values are either a {@see moodle_url} with the slot parameter
1513       * updated to point to the slot that has that redo of this question; or null
1514       * corresponding to the redo identified by $slot.
1515       *
1516       * @param int $slot identifies a question in this attempt.
1517       * @param moodle_url $baseurl the base URL to modify to generate each link.
1518       * @return links_to_other_attempts|null containing array int => null|moodle_url,
1519       *      or null if the question in this slot has not been redone.
1520       */
1521      public function links_to_other_redos($slot, moodle_url $baseurl) {
1522          $originalslot = $this->get_original_slot($slot);
1523  
1524          $qas = $this->all_question_attempts_originally_in_slot($originalslot);
1525          if (count($qas) <= 1) {
1526              return null;
1527          }
1528  
1529          $links = new links_to_other_attempts();
1530          $index = 1;
1531          foreach ($qas as $qa) {
1532              if ($qa->get_slot() == $slot) {
1533                  $links->links[$index] = null;
1534              } else {
1535                  $url = new moodle_url($baseurl, ['slot' => $qa->get_slot()]);
1536                  $links->links[$index] = new action_link($url, $index,
1537                          new popup_action('click', $url, 'reviewquestion',
1538                                  ['width' => 450, 'height' => 650]),
1539                          ['title' => get_string('reviewresponse', 'question')]);
1540              }
1541              $index++;
1542          }
1543          return $links;
1544      }
1545  
1546      // Methods for processing ==================================================.
1547  
1548      /**
1549       * Check this attempt, to see if there are any state transitions that should
1550       * happen automatically. This function will update the attempt checkstatetime.
1551       * @param int $timestamp the timestamp that should be stored as the modified
1552       * @param bool $studentisonline is the student currently interacting with Moodle?
1553       */
1554      public function handle_if_time_expired($timestamp, $studentisonline) {
1555  
1556          $timeclose = $this->get_access_manager($timestamp)->get_end_time($this->attempt);
1557  
1558          if ($timeclose === false || $this->is_preview()) {
1559              $this->update_timecheckstate(null);
1560              return; // No time limit.
1561          }
1562          if ($timestamp < $timeclose) {
1563              $this->update_timecheckstate($timeclose);
1564              return; // Time has not yet expired.
1565          }
1566  
1567          // If the attempt is already overdue, look to see if it should be abandoned ...
1568          if ($this->attempt->state == self::OVERDUE) {
1569              $timeoverdue = $timestamp - $timeclose;
1570              $graceperiod = $this->quizobj->get_quiz()->graceperiod;
1571              if ($timeoverdue >= $graceperiod) {
1572                  $this->process_abandon($timestamp, $studentisonline);
1573              } else {
1574                  // Overdue time has not yet expired.
1575                  $this->update_timecheckstate($timeclose + $graceperiod);
1576              }
1577              return; // ... and we are done.
1578          }
1579  
1580          if ($this->attempt->state != self::IN_PROGRESS) {
1581              $this->update_timecheckstate(null);
1582              return; // Attempt is already in a final state.
1583          }
1584  
1585          // Otherwise, we were in quiz_attempt::IN_PROGRESS, and time has now expired.
1586          // Transition to the appropriate state.
1587          switch ($this->quizobj->get_quiz()->overduehandling) {
1588              case 'autosubmit':
1589                  $this->process_finish($timestamp, false, $studentisonline ? $timestamp : $timeclose, $studentisonline);
1590                  return;
1591  
1592              case 'graceperiod':
1593                  $this->process_going_overdue($timestamp, $studentisonline);
1594                  return;
1595  
1596              case 'autoabandon':
1597                  $this->process_abandon($timestamp, $studentisonline);
1598                  return;
1599          }
1600  
1601          // This is an overdue attempt with no overdue handling defined, so just abandon.
1602          $this->process_abandon($timestamp, $studentisonline);
1603      }
1604  
1605      /**
1606       * Process all the actions that were submitted as part of the current request.
1607       *
1608       * @param int $timestamp the timestamp that should be stored as the modified.
1609       *      time in the database for these actions. If null, will use the current time.
1610       * @param bool $becomingoverdue
1611       * @param array|null $simulatedresponses If not null, then we are testing, and this is an array of simulated data.
1612       *      There are two formats supported here, for historical reasons. The newer approach is to pass an array created by
1613       *      {@see core_question_generator::get_simulated_post_data_for_questions_in_usage()}.
1614       *      the second is to pass an array slot no => contains arrays representing student
1615       *      responses which will be passed to {@see question_definition::prepare_simulated_post_data()}.
1616       *      This second method will probably get deprecated one day.
1617       */
1618      public function process_submitted_actions($timestamp, $becomingoverdue = false, $simulatedresponses = null) {
1619          global $DB;
1620  
1621          $transaction = $DB->start_delegated_transaction();
1622  
1623          if ($simulatedresponses !== null) {
1624              if (is_int(key($simulatedresponses))) {
1625                  // Legacy approach. Should be removed one day.
1626                  $simulatedpostdata = $this->quba->prepare_simulated_post_data($simulatedresponses);
1627              } else {
1628                  $simulatedpostdata = $simulatedresponses;
1629              }
1630          } else {
1631              $simulatedpostdata = null;
1632          }
1633  
1634          $this->quba->process_all_actions($timestamp, $simulatedpostdata);
1635          question_engine::save_questions_usage_by_activity($this->quba);
1636  
1637          $this->attempt->timemodified = $timestamp;
1638          if ($this->attempt->state == self::FINISHED) {
1639              $this->attempt->sumgrades = $this->quba->get_total_mark();
1640          }
1641          if ($becomingoverdue) {
1642              $this->process_going_overdue($timestamp, true);
1643          } else {
1644              $DB->update_record('quiz_attempts', $this->attempt);
1645          }
1646  
1647          if (!$this->is_preview() && $this->attempt->state == self::FINISHED) {
1648              $this->recompute_final_grade();
1649          }
1650  
1651          $transaction->allow_commit();
1652      }
1653  
1654      /**
1655       * Replace a question in an attempt with a new attempt at the same question.
1656       *
1657       * Well, for randomised questions, it won't be the same question, it will be
1658       * a different randomly selected pick from the available question.
1659       *
1660       * @param int $slot the question to restart.
1661       * @param int $timestamp the timestamp to record for this action.
1662       */
1663      public function process_redo_question($slot, $timestamp) {
1664          global $DB;
1665  
1666          if (!$this->can_question_be_redone_now($slot)) {
1667              throw new coding_exception('Attempt to restart the question in slot ' . $slot .
1668                      ' when it is not in a state to be restarted.');
1669          }
1670  
1671          $qubaids = new \mod_quiz\question\qubaids_for_users_attempts(
1672                  $this->get_quizid(), $this->get_userid(), 'all', true);
1673  
1674          $transaction = $DB->start_delegated_transaction();
1675  
1676          // Add the question to the usage. It is important we do this before we choose a variant.
1677          $newquestionid = qbank_helper::choose_question_for_redo($this->get_quizid(),
1678                      $this->get_quizobj()->get_context(), $this->slots[$slot]->id, $qubaids);
1679          $newquestion = question_bank::load_question($newquestionid, $this->get_quiz()->shuffleanswers);
1680          $newslot = $this->quba->add_question_in_place_of_other($slot, $newquestion);
1681  
1682          // Choose the variant.
1683          if ($newquestion->get_num_variants() == 1) {
1684              $variant = 1;
1685          } else {
1686              $variantstrategy = new \core_question\engine\variants\least_used_strategy(
1687                      $this->quba, $qubaids);
1688              $variant = $variantstrategy->choose_variant($newquestion->get_num_variants(),
1689                      $newquestion->get_variants_selection_seed());
1690          }
1691  
1692          // Start the question.
1693          $this->quba->start_question($slot, $variant);
1694          $this->quba->set_max_mark($newslot, 0);
1695          $this->quba->set_question_attempt_metadata($newslot, 'originalslot', $slot);
1696          question_engine::save_questions_usage_by_activity($this->quba);
1697          $this->fire_attempt_question_restarted_event($slot, $newquestion->id);
1698  
1699          $transaction->allow_commit();
1700      }
1701  
1702      /**
1703       * Process all the autosaved data that was part of the current request.
1704       *
1705       * @param int $timestamp the timestamp that should be stored as the modified.
1706       * time in the database for these actions. If null, will use the current time.
1707       */
1708      public function process_auto_save($timestamp) {
1709          global $DB;
1710  
1711          $transaction = $DB->start_delegated_transaction();
1712  
1713          $this->quba->process_all_autosaves($timestamp);
1714          question_engine::save_questions_usage_by_activity($this->quba);
1715          $this->fire_attempt_autosaved_event();
1716  
1717          $transaction->allow_commit();
1718      }
1719  
1720      /**
1721       * Update the flagged state for all question_attempts in this usage, if their
1722       * flagged state was changed in the request.
1723       */
1724      public function save_question_flags() {
1725          global $DB;
1726  
1727          $transaction = $DB->start_delegated_transaction();
1728          $this->quba->update_question_flags();
1729          question_engine::save_questions_usage_by_activity($this->quba);
1730          $transaction->allow_commit();
1731      }
1732  
1733      /**
1734       * Submit the attempt.
1735       *
1736       * The separate $timefinish argument should be used when the quiz attempt
1737       * is being processed asynchronously (for example when cron is submitting
1738       * attempts where the time has expired).
1739       *
1740       * @param int $timestamp the time to record as last modified time.
1741       * @param bool $processsubmitted if true, and question responses in the current
1742       *      POST request are stored to be graded, before the attempt is finished.
1743       * @param ?int $timefinish if set, use this as the finish time for the attempt.
1744       *      (otherwise use $timestamp as the finish time as well).
1745       * @param bool $studentisonline is the student currently interacting with Moodle?
1746       */
1747      public function process_finish($timestamp, $processsubmitted, $timefinish = null, $studentisonline = false) {
1748          global $DB;
1749  
1750          $transaction = $DB->start_delegated_transaction();
1751  
1752          if ($processsubmitted) {
1753              $this->quba->process_all_actions($timestamp);
1754          }
1755          $this->quba->finish_all_questions($timestamp);
1756  
1757          question_engine::save_questions_usage_by_activity($this->quba);
1758  
1759          $this->attempt->timemodified = $timestamp;
1760          $this->attempt->timefinish = $timefinish ?? $timestamp;
1761          $this->attempt->sumgrades = $this->quba->get_total_mark();
1762          $this->attempt->state = self::FINISHED;
1763          $this->attempt->timecheckstate = null;
1764          $this->attempt->gradednotificationsenttime = null;
1765  
1766          if (!$this->requires_manual_grading() ||
1767                  !has_capability('mod/quiz:emailnotifyattemptgraded', $this->get_quizobj()->get_context(),
1768                          $this->get_userid())) {
1769              $this->attempt->gradednotificationsenttime = $this->attempt->timefinish;
1770          }
1771  
1772          $DB->update_record('quiz_attempts', $this->attempt);
1773  
1774          if (!$this->is_preview()) {
1775              $this->recompute_final_grade();
1776  
1777              // Trigger event.
1778              $this->fire_state_transition_event('\mod_quiz\event\attempt_submitted', $timestamp, $studentisonline);
1779  
1780              // Tell any access rules that care that the attempt is over.
1781              $this->get_access_manager($timestamp)->current_attempt_finished();
1782          }
1783  
1784          $transaction->allow_commit();
1785      }
1786  
1787      /**
1788       * Update this attempt timecheckstate if necessary.
1789       *
1790       * @param int|null $time the timestamp to set.
1791       */
1792      public function update_timecheckstate($time) {
1793          global $DB;
1794          if ($this->attempt->timecheckstate !== $time) {
1795              $this->attempt->timecheckstate = $time;
1796              $DB->set_field('quiz_attempts', 'timecheckstate', $time, ['id' => $this->attempt->id]);
1797          }
1798      }
1799  
1800      /**
1801       * Needs to be called after this attempt's grade is changed, to update the overall quiz grade.
1802       */
1803      protected function recompute_final_grade(): void {
1804          $this->quizobj->get_grade_calculator()->recompute_final_grade($this->get_userid());
1805      }
1806  
1807      /**
1808       * Mark this attempt as now overdue.
1809       *
1810       * @param int $timestamp the time to deem as now.
1811       * @param bool $studentisonline is the student currently interacting with Moodle?
1812       */
1813      public function process_going_overdue($timestamp, $studentisonline) {
1814          global $DB;
1815  
1816          $transaction = $DB->start_delegated_transaction();
1817          $this->attempt->timemodified = $timestamp;
1818          $this->attempt->state = self::OVERDUE;
1819          // If we knew the attempt close time, we could compute when the graceperiod ends.
1820          // Instead, we'll just fix it up through cron.
1821          $this->attempt->timecheckstate = $timestamp;
1822          $DB->update_record('quiz_attempts', $this->attempt);
1823  
1824          $this->fire_state_transition_event('\mod_quiz\event\attempt_becameoverdue', $timestamp, $studentisonline);
1825  
1826          $transaction->allow_commit();
1827  
1828          quiz_send_overdue_message($this);
1829      }
1830  
1831      /**
1832       * Mark this attempt as abandoned.
1833       *
1834       * @param int $timestamp the time to deem as now.
1835       * @param bool $studentisonline is the student currently interacting with Moodle?
1836       */
1837      public function process_abandon($timestamp, $studentisonline) {
1838          global $DB;
1839  
1840          $transaction = $DB->start_delegated_transaction();
1841          $this->attempt->timemodified = $timestamp;
1842          $this->attempt->state = self::ABANDONED;
1843          $this->attempt->timecheckstate = null;
1844          $DB->update_record('quiz_attempts', $this->attempt);
1845  
1846          $this->fire_state_transition_event('\mod_quiz\event\attempt_abandoned', $timestamp, $studentisonline);
1847  
1848          $transaction->allow_commit();
1849      }
1850  
1851      /**
1852       * This method takes an attempt in the 'Never submitted' state, and reopens it.
1853       *
1854       * If, for this student, time has not expired (perhaps, because an override has
1855       * been added, then the attempt is left open. Otherwise, it is immediately submitted
1856       * for grading.
1857       *
1858       * @param int $timestamp the time to deem as now.
1859       */
1860      public function process_reopen_abandoned($timestamp) {
1861          global $DB;
1862  
1863          // Verify that things are as we expect.
1864          if ($this->get_state() != self::ABANDONED) {
1865              throw new coding_exception('Can only reopen an attempt that was never submitted.');
1866          }
1867  
1868          $transaction = $DB->start_delegated_transaction();
1869          $this->attempt->timemodified = $timestamp;
1870          $this->attempt->state = self::IN_PROGRESS;
1871          $this->attempt->timecheckstate = null;
1872          $DB->update_record('quiz_attempts', $this->attempt);
1873  
1874          $this->fire_state_transition_event('\mod_quiz\event\attempt_reopened', $timestamp, false);
1875  
1876          $timeclose = $this->get_access_manager($timestamp)->get_end_time($this->attempt);
1877          if ($timeclose && $timestamp > $timeclose) {
1878              $this->process_finish($timestamp, false, $timeclose);
1879          }
1880  
1881          $transaction->allow_commit();
1882      }
1883  
1884      /**
1885       * Fire a state transition event.
1886       *
1887       * @param string $eventclass the event class name.
1888       * @param int $timestamp the timestamp to include in the event.
1889       * @param bool $studentisonline is the student currently interacting with Moodle?
1890       */
1891      protected function fire_state_transition_event($eventclass, $timestamp, $studentisonline) {
1892          global $USER;
1893          $quizrecord = $this->get_quiz();
1894          $params = [
1895              'context' => $this->get_quizobj()->get_context(),
1896              'courseid' => $this->get_courseid(),
1897              'objectid' => $this->attempt->id,
1898              'relateduserid' => $this->attempt->userid,
1899              'other' => [
1900                  'submitterid' => CLI_SCRIPT ? null : $USER->id,
1901                  'quizid' => $quizrecord->id,
1902                  'studentisonline' => $studentisonline
1903              ]
1904          ];
1905          $event = $eventclass::create($params);
1906          $event->add_record_snapshot('quiz', $this->get_quiz());
1907          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
1908          $event->trigger();
1909      }
1910  
1911      // Private methods =========================================================.
1912  
1913      /**
1914       * Get a URL for a particular question on a particular page of the quiz.
1915       * Used by {@see attempt_url()} and {@see review_url()}.
1916       *
1917       * @param string $script e.g. 'attempt' or 'review'. Used in the URL like /mod/quiz/$script.php.
1918       * @param int $slot identifies the specific question on the page to jump to.
1919       *      0 to just use the $page parameter.
1920       * @param int $page -1 to look up the page number from the slot, otherwise
1921       *      the page number to go to.
1922       * @param bool|null $showall if true, return a URL with showall=1, and not page number.
1923       *      if null, then an intelligent default will be chosen.
1924       * @param int $thispage the page we are currently on. Links to questions on this
1925       *      page will just be a fragment #q123. -1 to disable this.
1926       * @return moodle_url The requested URL.
1927       */
1928      protected function page_and_question_url($script, $slot, $page, $showall, $thispage) {
1929  
1930          $defaultshowall = $this->get_default_show_all($script);
1931          if ($showall === null && ($page == 0 || $page == -1)) {
1932              $showall = $defaultshowall;
1933          }
1934  
1935          // Fix up $page.
1936          if ($page == -1) {
1937              if ($slot !== null && !$showall) {
1938                  $page = $this->get_question_page($slot);
1939              } else {
1940                  $page = 0;
1941              }
1942          }
1943  
1944          if ($showall) {
1945              $page = 0;
1946          }
1947  
1948          // Add a fragment to scroll down to the question.
1949          $fragment = '';
1950          if ($slot !== null) {
1951              if ($slot == reset($this->pagelayout[$page]) && $thispage != $page) {
1952                  // Changing the page, go to top.
1953                  $fragment = '#';
1954              } else {
1955                  // Link to the question container.
1956                  $qa = $this->get_question_attempt($slot);
1957                  $fragment = '#' . $qa->get_outer_question_div_unique_id();
1958              }
1959          }
1960  
1961          // Work out the correct start to the URL.
1962          if ($thispage == $page) {
1963              return new moodle_url($fragment);
1964  
1965          } else {
1966              $url = new moodle_url('/mod/quiz/' . $script . '.php' . $fragment,
1967                      ['attempt' => $this->attempt->id, 'cmid' => $this->get_cmid()]);
1968              if ($page == 0 && $showall != $defaultshowall) {
1969                  $url->param('showall', (int) $showall);
1970              } else if ($page > 0) {
1971                  $url->param('page', $page);
1972              }
1973              return $url;
1974          }
1975      }
1976  
1977      /**
1978       * Process responses during an attempt at a quiz.
1979       *
1980       * @param  int $timenow time when the processing started.
1981       * @param  bool $finishattempt whether to finish the attempt or not.
1982       * @param  bool $timeup true if form was submitted by timer.
1983       * @param  int $thispage current page number.
1984       * @return string the attempt state once the data has been processed.
1985       * @since  Moodle 3.1
1986       */
1987      public function process_attempt($timenow, $finishattempt, $timeup, $thispage) {
1988          global $DB;
1989  
1990          $transaction = $DB->start_delegated_transaction();
1991  
1992          // Get key times.
1993          $accessmanager = $this->get_access_manager($timenow);
1994          $timeclose = $accessmanager->get_end_time($this->get_attempt());
1995          $graceperiodmin = get_config('quiz', 'graceperiodmin');
1996  
1997          // Don't enforce timeclose for previews.
1998          if ($this->is_preview()) {
1999              $timeclose = false;
2000          }
2001  
2002          // Check where we are in relation to the end time, if there is one.
2003          $toolate = false;
2004          if ($timeclose !== false) {
2005              if ($timenow > $timeclose - QUIZ_MIN_TIME_TO_CONTINUE) {
2006                  // If there is only a very small amount of time left, there is no point trying
2007                  // to show the student another page of the quiz. Just finish now.
2008                  $timeup = true;
2009                  if ($timenow > $timeclose + $graceperiodmin) {
2010                      $toolate = true;
2011                  }
2012              } else {
2013                  // If time is not close to expiring, then ignore the client-side timer's opinion
2014                  // about whether time has expired. This can happen if the time limit has changed
2015                  // since the student's previous interaction.
2016                  $timeup = false;
2017              }
2018          }
2019  
2020          // If time is running out, trigger the appropriate action.
2021          $becomingoverdue = false;
2022          $becomingabandoned = false;
2023          if ($timeup) {
2024              if ($this->get_quiz()->overduehandling === 'graceperiod') {
2025                  if ($timenow > $timeclose + $this->get_quiz()->graceperiod + $graceperiodmin) {
2026                      // Grace period has run out.
2027                      $finishattempt = true;
2028                      $becomingabandoned = true;
2029                  } else {
2030                      $becomingoverdue = true;
2031                  }
2032              } else {
2033                  $finishattempt = true;
2034              }
2035          }
2036  
2037          if (!$finishattempt) {
2038              // Just process the responses for this page and go to the next page.
2039              if (!$toolate) {
2040                  try {
2041                      $this->process_submitted_actions($timenow, $becomingoverdue);
2042                      $this->fire_attempt_updated_event();
2043                  } catch (question_out_of_sequence_exception $e) {
2044                      throw new moodle_exception('submissionoutofsequencefriendlymessage', 'question',
2045                              $this->attempt_url(null, $thispage));
2046  
2047                  } catch (Exception $e) {
2048                      // This sucks, if we display our own custom error message, there is no way
2049                      // to display the original stack trace.
2050                      $debuginfo = '';
2051                      if (!empty($e->debuginfo)) {
2052                          $debuginfo = $e->debuginfo;
2053                      }
2054                      throw new moodle_exception('errorprocessingresponses', 'question',
2055                              $this->attempt_url(null, $thispage), $e->getMessage(), $debuginfo);
2056                  }
2057  
2058                  if (!$becomingoverdue) {
2059                      foreach ($this->get_slots() as $slot) {
2060                          if (optional_param('redoslot' . $slot, false, PARAM_BOOL)) {
2061                              $this->process_redo_question($slot, $timenow);
2062                          }
2063                      }
2064                  }
2065  
2066              } else {
2067                  // The student is too late.
2068                  $this->process_going_overdue($timenow, true);
2069              }
2070  
2071              $transaction->allow_commit();
2072  
2073              return $becomingoverdue ? self::OVERDUE : self::IN_PROGRESS;
2074          }
2075  
2076          // Update the quiz attempt record.
2077          try {
2078              if ($becomingabandoned) {
2079                  $this->process_abandon($timenow, true);
2080              } else {
2081                  if (!$toolate || $this->get_quiz()->overduehandling === 'graceperiod') {
2082                      // Normally, we record the accurate finish time when the student is online.
2083                      $finishtime = $timenow;
2084                  } else {
2085                      // But, if there is no grade period, and the final responses were too
2086                      // late to be processed, record the close time, to reduce confusion.
2087                      $finishtime = $timeclose;
2088                  }
2089                  $this->process_finish($timenow, !$toolate, $finishtime, true);
2090              }
2091  
2092          } catch (question_out_of_sequence_exception $e) {
2093              throw new moodle_exception('submissionoutofsequencefriendlymessage', 'question',
2094                      $this->attempt_url(null, $thispage));
2095  
2096          } catch (Exception $e) {
2097              // This sucks, if we display our own custom error message, there is no way
2098              // to display the original stack trace.
2099              $debuginfo = '';
2100              if (!empty($e->debuginfo)) {
2101                  $debuginfo = $e->debuginfo;
2102              }
2103              throw new moodle_exception('errorprocessingresponses', 'question',
2104                      $this->attempt_url(null, $thispage), $e->getMessage(), $debuginfo);
2105          }
2106  
2107          // Send the user to the review page.
2108          $transaction->allow_commit();
2109  
2110          return $becomingabandoned ? self::ABANDONED : self::FINISHED;
2111      }
2112  
2113      /**
2114       * Check a page read access to see if is an out of sequence access.
2115       *
2116       * If allownext is set then we also check whether access to the page
2117       * after the current one should be permitted.
2118       *
2119       * @param int $page page number.
2120       * @param bool $allownext in case of a sequential navigation, can we go to next page ?
2121       * @return boolean false is an out of sequence access, true otherwise.
2122       * @since Moodle 3.1
2123       */
2124      public function check_page_access(int $page, bool $allownext = true): bool {
2125          if ($this->get_navigation_method() != QUIZ_NAVMETHOD_SEQ) {
2126              return true;
2127          }
2128          // Sequential access: allow access to the summary, current page or next page.
2129          // Or if the user review his/her attempt, see MDLQA-1523.
2130          return $page == -1
2131              || $page == $this->get_currentpage()
2132              || $allownext && ($page == $this->get_currentpage() + 1);
2133      }
2134  
2135      /**
2136       * Update attempt page.
2137       *
2138       * @param  int $page page number.
2139       * @return boolean true if everything was ok, false otherwise (out of sequence access).
2140       * @since Moodle 3.1
2141       */
2142      public function set_currentpage($page) {
2143          global $DB;
2144  
2145          if ($this->check_page_access($page)) {
2146              $DB->set_field('quiz_attempts', 'currentpage', $page, ['id' => $this->get_attemptid()]);
2147              return true;
2148          }
2149          return false;
2150      }
2151  
2152      /**
2153       * Trigger the attempt_viewed event.
2154       *
2155       * @since Moodle 3.1
2156       */
2157      public function fire_attempt_viewed_event() {
2158          $params = [
2159              'objectid' => $this->get_attemptid(),
2160              'relateduserid' => $this->get_userid(),
2161              'courseid' => $this->get_courseid(),
2162              'context' => $this->get_context(),
2163              'other' => [
2164                  'quizid' => $this->get_quizid(),
2165                  'page' => $this->get_currentpage()
2166              ]
2167          ];
2168          $event = \mod_quiz\event\attempt_viewed::create($params);
2169          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2170          $event->trigger();
2171      }
2172  
2173      /**
2174       * Trigger the attempt_updated event.
2175       *
2176       * @return void
2177       */
2178      public function fire_attempt_updated_event(): void {
2179          $params = [
2180              'objectid' => $this->get_attemptid(),
2181              'relateduserid' => $this->get_userid(),
2182              'courseid' => $this->get_courseid(),
2183              'context' => $this->get_context(),
2184              'other' => [
2185                  'quizid' => $this->get_quizid(),
2186                  'page' => $this->get_currentpage()
2187              ]
2188          ];
2189          $event = \mod_quiz\event\attempt_updated::create($params);
2190          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2191          $event->trigger();
2192      }
2193  
2194      /**
2195       * Trigger the attempt_autosaved event.
2196       *
2197       * @return void
2198       */
2199      public function fire_attempt_autosaved_event(): void {
2200          $params = [
2201              'objectid' => $this->get_attemptid(),
2202              'relateduserid' => $this->get_userid(),
2203              'courseid' => $this->get_courseid(),
2204              'context' => $this->get_context(),
2205              'other' => [
2206                  'quizid' => $this->get_quizid(),
2207                  'page' => $this->get_currentpage()
2208              ]
2209          ];
2210          $event = \mod_quiz\event\attempt_autosaved::create($params);
2211          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2212          $event->trigger();
2213      }
2214  
2215      /**
2216       * Trigger the attempt_question_restarted event.
2217       *
2218       * @param int $slot Slot number
2219       * @param int $newquestionid New question id.
2220       * @return void
2221       */
2222      public function fire_attempt_question_restarted_event(int $slot, int $newquestionid): void {
2223          $params = [
2224              'objectid' => $this->get_attemptid(),
2225              'relateduserid' => $this->get_userid(),
2226              'courseid' => $this->get_courseid(),
2227              'context' => $this->get_context(),
2228              'other' => [
2229                  'quizid' => $this->get_quizid(),
2230                  'page' => $this->get_currentpage(),
2231                  'slot' => $slot,
2232                  'newquestionid' => $newquestionid
2233              ]
2234          ];
2235          $event = \mod_quiz\event\attempt_question_restarted::create($params);
2236          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2237          $event->trigger();
2238      }
2239  
2240      /**
2241       * Trigger the attempt_summary_viewed event.
2242       *
2243       * @since Moodle 3.1
2244       */
2245      public function fire_attempt_summary_viewed_event() {
2246  
2247          $params = [
2248              'objectid' => $this->get_attemptid(),
2249              'relateduserid' => $this->get_userid(),
2250              'courseid' => $this->get_courseid(),
2251              'context' => $this->get_context(),
2252              'other' => [
2253                  'quizid' => $this->get_quizid()
2254              ]
2255          ];
2256          $event = \mod_quiz\event\attempt_summary_viewed::create($params);
2257          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2258          $event->trigger();
2259      }
2260  
2261      /**
2262       * Trigger the attempt_reviewed event.
2263       *
2264       * @since Moodle 3.1
2265       */
2266      public function fire_attempt_reviewed_event() {
2267  
2268          $params = [
2269              'objectid' => $this->get_attemptid(),
2270              'relateduserid' => $this->get_userid(),
2271              'courseid' => $this->get_courseid(),
2272              'context' => $this->get_context(),
2273              'other' => [
2274                  'quizid' => $this->get_quizid()
2275              ]
2276          ];
2277          $event = \mod_quiz\event\attempt_reviewed::create($params);
2278          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2279          $event->trigger();
2280      }
2281  
2282      /**
2283       * Trigger the attempt manual grading completed event.
2284       */
2285      public function fire_attempt_manual_grading_completed_event() {
2286          $params = [
2287              'objectid' => $this->get_attemptid(),
2288              'relateduserid' => $this->get_userid(),
2289              'courseid' => $this->get_courseid(),
2290              'context' => $this->get_context(),
2291              'other' => [
2292                  'quizid' => $this->get_quizid()
2293              ]
2294          ];
2295  
2296          $event = \mod_quiz\event\attempt_manual_grading_completed::create($params);
2297          $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2298          $event->trigger();
2299      }
2300  
2301      /**
2302       * Update the timemodifiedoffline attempt field.
2303       *
2304       * This function should be used only when web services are being used.
2305       *
2306       * @param int $time time stamp.
2307       * @return boolean false if the field is not updated because web services aren't being used.
2308       * @since Moodle 3.2
2309       */
2310      public function set_offline_modified_time($time) {
2311          // Update the timemodifiedoffline field only if web services are being used.
2312          if (WS_SERVER) {
2313              $this->attempt->timemodifiedoffline = $time;
2314              return true;
2315          }
2316          return false;
2317      }
2318  
2319      /**
2320       * Get the total number of unanswered questions in the attempt.
2321       *
2322       * @return int
2323       */
2324      public function get_number_of_unanswered_questions(): int {
2325          $totalunanswered = 0;
2326          foreach ($this->get_slots() as $slot) {
2327              if (!$this->is_real_question($slot)) {
2328                  continue;
2329              }
2330              $questionstate = $this->get_question_state($slot);
2331              if ($questionstate == question_state::$todo || $questionstate == question_state::$invalid) {
2332                  $totalunanswered++;
2333              }
2334          }
2335          return $totalunanswered;
2336      }
2337  }