[Summary view]

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