question/engine/questionattempt.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * This file defines the question attempt class, and a few related classes.
  19  *
  20  * @package    moodlecore
  21  * @subpackage questionengine
  22  * @copyright  2009 The Open University
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26
  27 defined('MOODLE_INTERNAL') || die();
  28
  29
  30 /**
  31  * Tracks an attempt at one particular question in a {@link question_usage_by_activity}.
  32  *
  33  * Most calling code should need to access objects of this class. They should be
  34  * able to do everything through the usage interface. This class is an internal
  35  * implementation detail of the question engine.
  36  *
  37  * Instances of this class correspond to rows in the question_attempts table, and
  38  * a collection of {@link question_attempt_steps}. Question inteaction models and
  39  * question types do work with question_attempt objects.
  40  *
  41  * @copyright  2009 The Open University
  42  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  43  */
  44 class question_attempt {
  45     /**
  46      * @var string this is a magic value that question types can return from
  47      * {@link question_definition::get_expected_data()}.
  48      */
  49     const USE_RAW_DATA = 'use raw data';
  50
  51     /**
  52      * @var string Should not longer be used.
  53      * @deprecated since Moodle 3.0
  54      */
  55     const PARAM_MARK = PARAM_RAW_TRIMMED;
  56
  57     /**
  58      * @var string special value to indicate a response variable that is uploaded
  59      * files.
  60      */
  61     const PARAM_FILES = 'paramfiles';
  62
  63     /**
  64      * @var string special value to indicate a response variable that is uploaded
  65      * files.
  66      */
  67     const PARAM_RAW_FILES = 'paramrawfiles';
  68
  69     /**
  70      * @var string means first try at a question during an attempt by a user.
  71      */
  72     const FIRST_TRY = 'firsttry';
  73
  74     /**
  75      * @var string means last try at a question during an attempt by a user.
  76      */
  77     const LAST_TRY = 'lasttry';
  78
  79     /**
  80      * @var string means all tries at a question during an attempt by a user.
  81      */
  82     const ALL_TRIES = 'alltries';
  83
  84     /** @var integer if this attempts is stored in the question_attempts table, the id of that row. */
  85     protected $id = null;
  86
  87     /** @var integer|string the id of the question_usage_by_activity we belong to. */
  88     protected $usageid;
  89
  90     /** @var integer the number used to identify this question_attempt within the usage. */
  91     protected $slot = null;
  92
  93     /**
  94      * @var question_behaviour the behaviour controlling this attempt.
  95      * null until {@link start()} is called.
  96      */
  97     protected $behaviour = null;
  98
  99     /** @var question_definition the question this is an attempt at. */
 100     protected $question;
 101
 102     /** @var int which variant of the question to use. */
 103     protected $variant;
 104
 105     /**
 106      * @var float the maximum mark that can be scored at this question.
 107      * Actually, this is only really a nominal maximum. It might be better thought
 108      * of as the question weight.
 109      */
 110     protected $maxmark;
 111
 112     /**
 113      * @var float the minimum fraction that can be scored at this question, so
 114      * the minimum mark is $this->minfraction * $this->maxmark.
 115      */
 116     protected $minfraction = null;
 117
 118     /**
 119      * @var float the maximum fraction that can be scored at this question, so
 120      * the maximum mark is $this->maxfraction * $this->maxmark.
 121      */
 122     protected $maxfraction = null;
 123
 124     /**
 125      * @var string plain text summary of the variant of the question the
 126      * student saw. Intended for reporting purposes.
 127      */
 128     protected $questionsummary = null;
 129
 130     /**
 131      * @var string plain text summary of the response the student gave.
 132      * Intended for reporting purposes.
 133      */
 134     protected $responsesummary = null;
 135
 136     /**
 137      * @var int last modified time.
 138      */
 139     public $timemodified = null;
 140
 141     /**
 142      * @var string plain text summary of the correct response to this question
 143      * variant the student saw. The format should be similar to responsesummary.
 144      * Intended for reporting purposes.
 145      */
 146     protected $rightanswer = null;
 147
 148     /** @var array of {@link question_attempt_step}s. The steps in this attempt. */
 149     protected $steps = array();
 150
 151     /**
 152      * @var question_attempt_step if, when we loaded the step from the DB, there was
 153      * an autosaved step, we save a pointer to it here. (It is also added to the $steps array.)
 154      */
 155     protected $autosavedstep = null;
 156
 157     /** @var boolean whether the user has flagged this attempt within the usage. */
 158     protected $flagged = false;
 159
 160     /** @var question_usage_observer tracks changes to the useage this attempt is part of.*/
 161     protected $observer;
 162
 163     /**#@+
 164      * Constants used by the intereaction models to indicate whether the current
 165      * pending step should be kept or discarded.
 166      */
 167     const KEEP = true;
 168     const DISCARD = false;
 169     /**#@-*/
 170
 171     /**
 172      * Create a new {@link question_attempt}. Normally you should create question_attempts
 173      * indirectly, by calling {@link question_usage_by_activity::add_question()}.
 174      *
 175      * @param question_definition $question the question this is an attempt at.
 176      * @param int|string $usageid The id of the
 177      *      {@link question_usage_by_activity} we belong to. Used by {@link get_field_prefix()}.
 178      * @param question_usage_observer $observer tracks changes to the useage this
 179      *      attempt is part of. (Optional, a {@link question_usage_null_observer} is
 180      *      used if one is not passed.
 181      * @param number $maxmark the maximum grade for this question_attempt. If not
 182      * passed, $question->defaultmark is used.
 183      */
 184     public function __construct(question_definition $question, $usageid,
 185             question_usage_observer $observer = null, $maxmark = null) {
 186         $this->question = $question;
 187         $this->usageid = $usageid;
 188         if (is_null($observer)) {
 189             $observer = new question_usage_null_observer();
 190         }
 191         $this->observer = $observer;
 192         if (!is_null($maxmark)) {
 193             $this->maxmark = $maxmark;
 194         } else {
 195             $this->maxmark = $question->defaultmark;
 196         }
 197     }
 198
 199     /**
 200      * This method exists so that {@link question_attempt_with_restricted_history}
 201      * can override it. You should not normally need to call it.
 202      * @return question_attempt return ourself.
 203      */
 204     public function get_full_qa() {
 205         return $this;
 206     }
 207
 208     /** @return question_definition the question this is an attempt at. */
 209     public function get_question() {
 210         return $this->question;
 211     }
 212
 213     /**
 214      * Get the variant of the question being used in a given slot.
 215      * @return int the variant number.
 216      */
 217     public function get_variant() {
 218         return $this->variant;
 219     }
 220
 221     /**
 222      * Set the number used to identify this question_attempt within the usage.
 223      * For internal use only.
 224      * @param int $slot
 225      */
 226     public function set_slot($slot) {
 227         $this->slot = $slot;
 228     }
 229
 230     /** @return int the number used to identify this question_attempt within the usage. */
 231     public function get_slot() {
 232         return $this->slot;
 233     }
 234
 235     /**
 236      * @return int the id of row for this question_attempt, if it is stored in the
 237      * database. null if not.
 238      */
 239     public function get_database_id() {
 240         return $this->id;
 241     }
 242
 243     /**
 244      * For internal use only. Set the id of the corresponding database row.
 245      * @param int $id the id of row for this question_attempt, if it is
 246      * stored in the database.
 247      */
 248     public function set_database_id($id) {
 249         $this->id = $id;
 250     }
 251
 252     /**
 253      * You should almost certainly not call this method from your code. It is for
 254      * internal use only.
 255      * @param question_usage_observer that should be used to tracking changes made to this qa.
 256      */
 257     public function set_observer($observer) {
 258         $this->observer = $observer;
 259     }
 260
 261     /** @return int|string the id of the {@link question_usage_by_activity} we belong to. */
 262     public function get_usage_id() {
 263         return $this->usageid;
 264     }
 265
 266     /**
 267      * Set the id of the {@link question_usage_by_activity} we belong to.
 268      * For internal use only.
 269      * @param int|string the new id.
 270      */
 271     public function set_usage_id($usageid) {
 272         $this->usageid = $usageid;
 273     }
 274
 275     /** @return string the name of the behaviour that is controlling this attempt. */
 276     public function get_behaviour_name() {
 277         return $this->behaviour->get_name();
 278     }
 279
 280     /**
 281      * For internal use only.
 282      * @return question_behaviour the behaviour that is controlling this attempt.
 283      */
 284     public function get_behaviour() {
 285         return $this->behaviour;
 286     }
 287
 288     /**
 289      * Set the flagged state of this question.
 290      * @param bool $flagged the new state.
 291      */
 292     public function set_flagged($flagged) {
 293         $this->flagged = $flagged;
 294         $this->observer->notify_attempt_modified($this);
 295     }
 296
 297     /** @return bool whether this question is currently flagged. */
 298     public function is_flagged() {
 299         return $this->flagged;
 300     }
 301
 302     /**
 303      * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
 304      * name) to use for the field that indicates whether this question is flagged.
 305      *
 306      * @return string The field name to use.
 307      */
 308     public function get_flag_field_name() {
 309         return $this->get_control_field_name('flagged');
 310     }
 311
 312     /**
 313      * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
 314      * name) to use for a question_type variable belonging to this question_attempt.
 315      *
 316      * See the comment on {@link question_attempt_step} for an explanation of
 317      * question type and behaviour variables.
 318      *
 319      * @param string $varname The short form of the variable name.
 320      * @return string The field name to use.
 321      */
 322     public function get_qt_field_name($varname) {
 323         return $this->get_field_prefix() . $varname;
 324     }
 325
 326     /**
 327      * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
 328      * name) to use for a question_type variable belonging to this question_attempt.
 329      *
 330      * See the comment on {@link question_attempt_step} for an explanation of
 331      * question type and behaviour variables.
 332      *
 333      * @param string $varname The short form of the variable name.
 334      * @return string The field name to use.
 335      */
 336     public function get_behaviour_field_name($varname) {
 337         return $this->get_field_prefix() . '-' . $varname;
 338     }
 339
 340     /**
 341      * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
 342      * name) to use for a control variables belonging to this question_attempt.
 343      *
 344      * Examples are :sequencecheck and :flagged
 345      *
 346      * @param string $varname The short form of the variable name.
 347      * @return string The field name to use.
 348      */
 349     public function get_control_field_name($varname) {
 350         return $this->get_field_prefix() . ':' . $varname;
 351     }
 352
 353     /**
 354      * Get the prefix added to variable names to give field names for this
 355      * question attempt.
 356      *
 357      * You should not use this method directly. This is an implementation detail
 358      * anyway, but if you must access it, use {@link question_usage_by_activity::get_field_prefix()}.
 359      *
 360      * @return string The field name to use.
 361      */
 362     public function get_field_prefix() {
 363         return 'q' . $this->usageid . ':' . $this->slot . '_';
 364     }
 365
 366     /**
 367      * When the question is rendered, this unique id is added to the
 368      * outer div of the question. It can be used to uniquely reference
 369      * the question from JavaScript.
 370      *
 371      * @return string id added to the outer <div class="que ..."> when the question is rendered.
 372      */
 373     public function get_outer_question_div_unique_id() {
 374         return 'question-' . $this->usageid . '-' . $this->slot;
 375     }
 376
 377     /**
 378      * Get one of the steps in this attempt.
 379      *
 380      * @param int $i the step number, which counts from 0.
 381      * @return question_attempt_step
 382      */
 383     public function get_step($i) {
 384         if ($i < 0 || $i >= count($this->steps)) {
 385             throw new coding_exception('Index out of bounds in question_attempt::get_step.');
 386         }
 387         return $this->steps[$i];
 388     }
 389
 390     /**
 391      * Get the number of real steps in this attempt.
 392      * This is put as a hidden field in the HTML, so that when we receive some
 393      * data to process, then we can check that it came from the question
 394      * in the state we are now it.
 395      * @return int a number that summarises the current state of this question attempt.
 396      */
 397     public function get_sequence_check_count() {
 398         $numrealsteps = $this->get_num_steps();
 399         if ($this->has_autosaved_step()) {
 400             $numrealsteps -= 1;
 401         }
 402         return $numrealsteps;
 403     }
 404
 405     /**
 406      * Get the number of steps in this attempt.
 407      * For internal/test code use only.
 408      * @return int the number of steps we currently have.
 409      */
 410     public function get_num_steps() {
 411         return count($this->steps);
 412     }
 413
 414     /**
 415      * Return the latest step in this question_attempt.
 416      * For internal/test code use only.
 417      * @return question_attempt_step
 418      */
 419     public function get_last_step() {
 420         if (count($this->steps) == 0) {
 421             return new question_null_step();
 422         }
 423         return end($this->steps);
 424     }
 425
 426     /**
 427      * @return boolean whether this question_attempt has autosaved data from
 428      * some time in the past.
 429      */
 430     public function has_autosaved_step() {
 431         return !is_null($this->autosavedstep);
 432     }
 433
 434     /**
 435      * @return question_attempt_step_iterator for iterating over the steps in
 436      * this attempt, in order.
 437      */
 438     public function get_step_iterator() {
 439         return new question_attempt_step_iterator($this);
 440     }
 441
 442     /**
 443      * The same as {@link get_step_iterator()}. However, for a
 444      * {@link question_attempt_with_restricted_history} this returns the full
 445      * list of steps, while {@link get_step_iterator()} returns only the
 446      * limited history.
 447      * @return question_attempt_step_iterator for iterating over the steps in
 448      * this attempt, in order.
 449      */
 450     public function get_full_step_iterator() {
 451         return $this->get_step_iterator();
 452     }
 453
 454     /**
 455      * @return question_attempt_reverse_step_iterator for iterating over the steps in
 456      * this attempt, in reverse order.
 457      */
 458     public function get_reverse_step_iterator() {
 459         return new question_attempt_reverse_step_iterator($this);
 460     }
 461
 462     /**
 463      * Get the qt data from the latest step that has any qt data. Return $default
 464      * array if it is no step has qt data.
 465      *
 466      * @param mixed default the value to return no step has qt data.
 467      *      (Optional, defaults to an empty array.)
 468      * @return array|mixed the data, or $default if there is not any.
 469      */
 470     public function get_last_qt_data($default = array()) {
 471         foreach ($this->get_reverse_step_iterator() as $step) {
 472             $response = $step->get_qt_data();
 473             if (!empty($response)) {
 474                 return $response;
 475             }
 476         }
 477         return $default;
 478     }
 479
 480     /**
 481      * Get the last step with a particular question type varialbe set.
 482      * @param string $name the name of the variable to get.
 483      * @return question_attempt_step the last step, or a step with no variables
 484      * if there was not a real step.
 485      */
 486     public function get_last_step_with_qt_var($name) {
 487         foreach ($this->get_reverse_step_iterator() as $step) {
 488             if ($step->has_qt_var($name)) {
 489                 return $step;
 490             }
 491         }
 492         return new question_attempt_step_read_only();
 493     }
 494
 495     /**
 496      * Get the last step with a particular behaviour variable set.
 497      * @param string $name the name of the variable to get.
 498      * @return question_attempt_step the last step, or a step with no variables
 499      * if there was not a real step.
 500      */
 501     public function get_last_step_with_behaviour_var($name) {
 502         foreach ($this->get_reverse_step_iterator() as $step) {
 503             if ($step->has_behaviour_var($name)) {
 504                 return $step;
 505             }
 506         }
 507         return new question_attempt_step_read_only();
 508     }
 509
 510     /**
 511      * Get the latest value of a particular question type variable. That is, get
 512      * the value from the latest step that has it set. Return null if it is not
 513      * set in any step.
 514      *
 515      * @param string $name the name of the variable to get.
 516      * @param mixed default the value to return in the variable has never been set.
 517      *      (Optional, defaults to null.)
 518      * @return mixed string value, or $default if it has never been set.
 519      */
 520     public function get_last_qt_var($name, $default = null) {
 521         $step = $this->get_last_step_with_qt_var($name);
 522         if ($step->has_qt_var($name)) {
 523             return $step->get_qt_var($name);
 524         } else {
 525             return $default;
 526         }
 527     }
 528
 529     /**
 530      * Get the latest set of files for a particular question type variable of
 531      * type question_attempt::PARAM_FILES.
 532      *
 533      * @param string $name the name of the associated variable.
 534      * @param int $contextid the context to which the files are linked.
 535      * @return array of {@link stored_files}.
 536      */
 537     public function get_last_qt_files($name, $contextid) {
 538         foreach ($this->get_reverse_step_iterator() as $step) {
 539             if ($step->has_qt_var($name)) {
 540                 return $step->get_qt_files($name, $contextid);
 541             }
 542         }
 543         return array();
 544     }
 545
 546     /**
 547      * Get the URL of a file that belongs to a response variable of this
 548      * question_attempt.
 549      * @param stored_file $file the file to link to.
 550      * @return string the URL of that file.
 551      */
 552     public function get_response_file_url(stored_file $file) {
 553         return file_encode_url(new moodle_url('/pluginfile.php'), '/' . implode('/', array(
 554                 $file->get_contextid(),
 555                 $file->get_component(),
 556                 $file->get_filearea(),
 557                 $this->usageid,
 558                 $this->slot,
 559                 $file->get_itemid())) .
 560                 $file->get_filepath() . $file->get_filename(), true);
 561     }
 562
 563     /**
 564      * Prepare a draft file are for the files belonging the a response variable
 565      * of this question attempt. The draft area is populated with the files from
 566      * the most recent step having files.
 567      *
 568      * @param string $name the variable name the files belong to.
 569      * @param int $contextid the id of the context the quba belongs to.
 570      * @return int the draft itemid.
 571      */
 572     public function prepare_response_files_draft_itemid($name, $contextid) {
 573         foreach ($this->get_reverse_step_iterator() as $step) {
 574             if ($step->has_qt_var($name)) {
 575                 return $step->prepare_response_files_draft_itemid($name, $contextid);
 576             }
 577         }
 578
 579         // No files yet.
 580         $draftid = 0; // Will be filled in by file_prepare_draft_area.
 581         file_prepare_draft_area($draftid, $contextid, 'question', 'response_' . $name, null);
 582         return $draftid;
 583     }
 584
 585     /**
 586      * Get the latest value of a particular behaviour variable. That is,
 587      * get the value from the latest step that has it set. Return null if it is
 588      * not set in any step.
 589      *
 590      * @param string $name the name of the variable to get.
 591      * @param mixed default the value to return in the variable has never been set.
 592      *      (Optional, defaults to null.)
 593      * @return mixed string value, or $default if it has never been set.
 594      */
 595     public function get_last_behaviour_var($name, $default = null) {
 596         foreach ($this->get_reverse_step_iterator() as $step) {
 597             if ($step->has_behaviour_var($name)) {
 598                 return $step->get_behaviour_var($name);
 599             }
 600         }
 601         return $default;
 602     }
 603
 604     /**
 605      * Get the current state of this question attempt. That is, the state of the
 606      * latest step.
 607      * @return question_state
 608      */
 609     public function get_state() {
 610         return $this->get_last_step()->get_state();
 611     }
 612
 613     /**
 614      * @param bool $showcorrectness Whether right/partial/wrong states should
 615      * be distinguised.
 616      * @return string A brief textual description of the current state.
 617      */
 618     public function get_state_string($showcorrectness) {
 619         // Special case when attempt is based on previous one, see MDL-31226.
 620         if ($this->get_num_steps() == 1 && $this->get_state() == question_state::$complete) {
 621             return get_string('notchanged', 'question');
 622         }
 623         return $this->behaviour->get_state_string($showcorrectness);
 624     }
 625
 626     /**
 627      * @param bool $showcorrectness Whether right/partial/wrong states should
 628      * be distinguised.
 629      * @return string a CSS class name for the current state.
 630      */
 631     public function get_state_class($showcorrectness) {
 632         return $this->get_state()->get_state_class($showcorrectness);
 633     }
 634
 635     /**
 636      * @return int the timestamp of the most recent step in this question attempt.
 637      */
 638     public function get_last_action_time() {
 639         return $this->get_last_step()->get_timecreated();
 640     }
 641
 642     /**
 643      * Get the current fraction of this question attempt. That is, the fraction
 644      * of the latest step, or null if this question has not yet been graded.
 645      * @return number the current fraction.
 646      */
 647     public function get_fraction() {
 648         return $this->get_last_step()->get_fraction();
 649     }
 650
 651     /** @return bool whether this question attempt has a non-zero maximum mark. */
 652     public function has_marks() {
 653         // Since grades are stored in the database as NUMBER(12,7).
 654         return $this->maxmark >= 0.00000005;
 655     }
 656
 657     /**
 658      * @return number the current mark for this question.
 659      * {@link get_fraction()} * {@link get_max_mark()}.
 660      */
 661     public function get_mark() {
 662         return $this->fraction_to_mark($this->get_fraction());
 663     }
 664
 665     /**
 666      * This is used by the manual grading code, particularly in association with
 667      * validation. It gets the current manual mark for a question, in exactly the string
 668      * form that the teacher entered it, if possible. This may come from the current
 669      * POST request, if there is one, otherwise from the database.
 670      *
 671      * @return string the current manual mark for this question, in the format the teacher typed,
 672      *     if possible.
 673      */
 674     public function get_current_manual_mark() {
 675         // Is there a current value in the current POST data? If so, use that.
 676         $mark = $this->get_submitted_var($this->get_behaviour_field_name('mark'), PARAM_RAW_TRIMMED);
 677         if ($mark !== null) {
 678             return $mark;
 679         }
 680
 681         // Otherwise, use the stored value.
 682         // If the question max mark has not changed, use the stored value that was input.
 683         $storedmaxmark = $this->get_last_behaviour_var('maxmark');
 684         if ($storedmaxmark !== null && ($storedmaxmark - $this->get_max_mark()) < 0.0000005) {
 685             return $this->get_last_behaviour_var('mark');
 686         }
 687
 688         // The max mark for this question has changed so we must re-scale the current mark.
 689         return format_float($this->get_mark(), 7, true, true);
 690     }
 691
 692     /**
 693      * @param number|null $fraction a fraction.
 694      * @return number|null the corresponding mark.
 695      */
 696     public function fraction_to_mark($fraction) {
 697         if (is_null($fraction)) {
 698             return null;
 699         }
 700         return $fraction * $this->maxmark;
 701     }
 702
 703     /**
 704      * @return float the maximum mark possible for this question attempt.
 705      * In fact, this is not strictly the maximum, becuase get_max_fraction may
 706      * return a number greater than 1. It might be better to think of this as a
 707      * question weight.
 708      */
 709     public function get_max_mark() {
 710         return $this->maxmark;
 711     }
 712
 713     /** @return float the maximum mark possible for this question attempt. */
 714     public function get_min_fraction() {
 715         if (is_null($this->minfraction)) {
 716             throw new coding_exception('This question_attempt has not been started yet, the min fraction is not yet known.');
 717         }
 718         return $this->minfraction;
 719     }
 720
 721     /** @return float the maximum mark possible for this question attempt. */
 722     public function get_max_fraction() {
 723         if (is_null($this->maxfraction)) {
 724             throw new coding_exception('This question_attempt has not been started yet, the max fraction is not yet known.');
 725         }
 726         return $this->maxfraction;
 727     }
 728
 729     /**
 730      * The current mark, formatted to the stated number of decimal places. Uses
 731      * {@link format_float()} to format floats according to the current locale.
 732      * @param int $dp number of decimal places.
 733      * @return string formatted mark.
 734      */
 735     public function format_mark($dp) {
 736         return $this->format_fraction_as_mark($this->get_fraction(), $dp);
 737     }
 738
 739     /**
 740      * The a mark, formatted to the stated number of decimal places. Uses
 741      * {@link format_float()} to format floats according to the current locale.
 742      *
 743      * @param number $fraction a fraction.
 744      * @param int $dp number of decimal places.
 745      * @return string formatted mark.
 746      */
 747     public function format_fraction_as_mark($fraction, $dp) {
 748         return format_float($this->fraction_to_mark($fraction), $dp);
 749     }
 750
 751     /**
 752      * The maximum mark for this question attempt, formatted to the stated number
 753      * of decimal places. Uses {@link format_float()} to format floats according
 754      * to the current locale.
 755      * @param int $dp number of decimal places.
 756      * @return string formatted maximum mark.
 757      */
 758     public function format_max_mark($dp) {
 759         return format_float($this->maxmark, $dp);
 760     }
 761
 762     /**
 763      * Return the hint that applies to the question in its current state, or null.
 764      * @return question_hint|null
 765      */
 766     public function get_applicable_hint() {
 767         return $this->behaviour->get_applicable_hint();
 768     }
 769
 770     /**
 771      * Produce a plain-text summary of what the user did during a step.
 772      * @param question_attempt_step $step the step in quetsion.
 773      * @return string a summary of what was done during that step.
 774      */
 775     public function summarise_action(question_attempt_step $step) {
 776         return $this->behaviour->summarise_action($step);
 777     }
 778
 779     /**
 780      * Return one of the bits of metadata for a this question attempt.
 781      * @param string $name the name of the metadata variable to return.
 782      * @return string the value of that metadata variable.
 783      */
 784     public function get_metadata($name) {
 785         return $this->get_step(0)->get_metadata_var($name);
 786     }
 787
 788     /**
 789      * Set some metadata for this question attempt.
 790      * @param string $name the name of the metadata variable to return.
 791      * @param string $value the value to set that metadata variable to.
 792      */
 793     public function set_metadata($name, $value) {
 794         $firststep = $this->get_step(0);
 795         if (!$firststep->has_metadata_var($name)) {
 796             $this->observer->notify_metadata_added($this, $name);
 797         } else if ($value !== $firststep->get_metadata_var($name)) {
 798             $this->observer->notify_metadata_modified($this, $name);
 799         }
 800         $firststep->set_metadata_var($name, $value);
 801     }
 802
 803     /**
 804      * Helper function used by {@link rewrite_pluginfile_urls()} and
 805      * {@link rewrite_response_pluginfile_urls()}.
 806      * @return array ids that need to go into the file paths.
 807      */
 808     protected function extra_file_path_components() {
 809         return array($this->get_usage_id(), $this->get_slot());
 810     }
 811
 812     /**
 813      * Calls {@link question_rewrite_question_urls()} with appropriate parameters
 814      * for content belonging to this question.
 815      * @param string $text the content to output.
 816      * @param string $component the component name (normally 'question' or 'qtype_...')
 817      * @param string $filearea the name of the file area.
 818      * @param int $itemid the item id.
 819      * @return string the content with the URLs rewritten.
 820      */
 821     public function rewrite_pluginfile_urls($text, $component, $filearea, $itemid) {
 822         return question_rewrite_question_urls($text, 'pluginfile.php',
 823                 $this->question->contextid, $component, $filearea,
 824                 $this->extra_file_path_components(), $itemid);
 825     }
 826
 827     /**
 828      * Calls {@link question_rewrite_question_urls()} with appropriate parameters
 829      * for content belonging to responses to this question.
 830      *
 831      * @param string $text the text to update the URLs in.
 832      * @param int $contextid the id of the context the quba belongs to.
 833      * @param string $name the variable name the files belong to.
 834      * @param question_attempt_step $step the step the response is coming from.
 835      * @return string the content with the URLs rewritten.
 836      */
 837     public function rewrite_response_pluginfile_urls($text, $contextid, $name,
 838             question_attempt_step $step) {
 839         return $step->rewrite_response_pluginfile_urls($text, $contextid, $name,
 840                 $this->extra_file_path_components());
 841     }
 842
 843     /**
 844      * Get the {@link core_question_renderer}, in collaboration with appropriate
 845      * {@link qbehaviour_renderer} and {@link qtype_renderer} subclasses, to generate the
 846      * HTML to display this question attempt in its current state.
 847      *
 848      * @param question_display_options $options controls how the question is rendered.
 849      * @param string|null $number The question number to display.
 850      * @param moodle_page|null $page the page the question is being redered to.
 851      *      (Optional. Defaults to $PAGE.)
 852      * @return string HTML fragment representing the question.
 853      */
 854     public function render($options, $number, $page = null) {
 855         if (is_null($page)) {
 856             global $PAGE;
 857             $page = $PAGE;
 858         }
 859         $qoutput = $page->get_renderer('core', 'question');
 860         $qtoutput = $this->question->get_renderer($page);
 861         return $this->behaviour->render($options, $number, $qoutput, $qtoutput);
 862     }
 863
 864     /**
 865      * Generate any bits of HTML that needs to go in the <head> tag when this question
 866      * attempt is displayed in the body.
 867      * @return string HTML fragment.
 868      */
 869     public function render_head_html($page = null) {
 870         if (is_null($page)) {
 871             global $PAGE;
 872             $page = $PAGE;
 873         }
 874         // TODO go via behaviour.
 875         return $this->question->get_renderer($page)->head_code($this) .
 876                 $this->behaviour->get_renderer($page)->head_code($this);
 877     }
 878
 879     /**
 880      * Like {@link render_question()} but displays the question at the past step
 881      * indicated by $seq, rather than showing the latest step.
 882      *
 883      * @param int $seq the seq number of the past state to display.
 884      * @param question_display_options $options controls how the question is rendered.
 885      * @param string|null $number The question number to display. 'i' is a special
 886      *      value that gets displayed as Information. Null means no number is displayed.
 887      * @param string $preferredbehaviour the preferred behaviour. It is slightly
 888      *      annoying that this needs to be passed, but unavoidable for now.
 889      * @return string HTML fragment representing the question.
 890      */
 891     public function render_at_step($seq, $options, $number, $preferredbehaviour) {
 892         $restrictedqa = new question_attempt_with_restricted_history($this, $seq, $preferredbehaviour);
 893         return $restrictedqa->render($options, $number);
 894     }
 895
 896     /**
 897      * Checks whether the users is allow to be served a particular file.
 898      * @param question_display_options $options the options that control display of the question.
 899      * @param string $component the name of the component we are serving files for.
 900      * @param string $filearea the name of the file area.
 901      * @param array $args the remaining bits of the file path.
 902      * @param bool $forcedownload whether the user must be forced to download the file.
 903      * @return bool true if the user can access this file.
 904      */
 905     public function check_file_access($options, $component, $filearea, $args, $forcedownload) {
 906         return $this->behaviour->check_file_access($options, $component, $filearea, $args, $forcedownload);
 907     }
 908
 909     /**
 910      * Add a step to this question attempt.
 911      * @param question_attempt_step $step the new step.
 912      */
 913     protected function add_step(question_attempt_step $step) {
 914         $this->steps[] = $step;
 915         end($this->steps);
 916         $this->observer->notify_step_added($step, $this, key($this->steps));
 917     }
 918
 919     /**
 920      * Add an auto-saved step to this question attempt. We mark auto-saved steps by
 921      * changing saving the step number with a - sign.
 922      * @param question_attempt_step $step the new step.
 923      */
 924     protected function add_autosaved_step(question_attempt_step $step) {
 925         $this->steps[] = $step;
 926         $this->autosavedstep = $step;
 927         end($this->steps);
 928         $this->observer->notify_step_added($step, $this, -key($this->steps));
 929     }
 930
 931     /**
 932      * Discard any auto-saved data belonging to this question attempt.
 933      */
 934     public function discard_autosaved_step() {
 935         if (!$this->has_autosaved_step()) {
 936             return;
 937         }
 938
 939         $autosaved = array_pop($this->steps);
 940         $this->autosavedstep = null;
 941         $this->observer->notify_step_deleted($autosaved, $this);
 942     }
 943
 944     /**
 945      * If there is an autosaved step, convert it into a real save, so that it
 946      * is preserved.
 947      */
 948     protected function convert_autosaved_step_to_real_step() {
 949         if ($this->autosavedstep === null) {
 950             return;
 951         }
 952
 953         $laststep = end($this->steps);
 954         if ($laststep !== $this->autosavedstep) {
 955             throw new coding_exception('Cannot convert autosaved step to real step, since other steps have been added.');
 956         }
 957
 958         $this->observer->notify_step_modified($this->autosavedstep, $this, key($this->steps));
 959         $this->autosavedstep = null;
 960     }
 961
 962     /**
 963      * Use a strategy to pick a variant.
 964      * @param question_variant_selection_strategy $variantstrategy a strategy.
 965      * @return int the selected variant.
 966      */
 967     public function select_variant(question_variant_selection_strategy $variantstrategy) {
 968         return $variantstrategy->choose_variant($this->get_question()->get_num_variants(),
 969                 $this->get_question()->get_variants_selection_seed());
 970     }
 971
 972     /**
 973      * Start this question attempt.
 974      *
 975      * You should not call this method directly. Call
 976      * {@link question_usage_by_activity::start_question()} instead.
 977      *
 978      * @param string|question_behaviour $preferredbehaviour the name of the
 979      *      desired archetypal behaviour, or an actual model instance.
 980      * @param int $variant the variant of the question to start. Between 1 and
 981      *      $this->get_question()->get_num_variants() inclusive.
 982      * @param array $submitteddata optional, used when re-starting to keep the same initial state.
 983      * @param int $timestamp optional, the timstamp to record for this action. Defaults to now.
 984      * @param int $userid optional, the user to attribute this action to. Defaults to the current user.
 985      * @param int $existingstepid optional, if this step is going to replace an existing step
 986      *      (for example, during a regrade) this is the id of the previous step we are replacing.
 987      */
 988     public function start($preferredbehaviour, $variant, $submitteddata = array(),
 989             $timestamp = null, $userid = null, $existingstepid = null) {
 990
 991         if ($this->get_num_steps() > 0) {
 992             throw new coding_exception('Cannot start a question that is already started.');
 993         }
 994
 995         // Initialise the behaviour.
 996         $this->variant = $variant;
 997         if (is_string($preferredbehaviour)) {
 998             $this->behaviour =
 999                     $this->question->make_behaviour($this, $preferredbehaviour);
1000         } else {
1001             $class = get_class($preferredbehaviour);
1002             $this->behaviour = new $class($this, $preferredbehaviour);
1003         }
1004
1005         // Record the minimum and maximum fractions.
1006         $this->minfraction = $this->behaviour->get_min_fraction();
1007         $this->maxfraction = $this->behaviour->get_max_fraction();
1008
1009         // Initialise the first step.
1010         $firststep = new question_attempt_step($submitteddata, $timestamp, $userid, $existingstepid);
1011         if ($submitteddata) {
1012             $firststep->set_state(question_state::$complete);
1013             $this->behaviour->apply_attempt_state($firststep);
1014         } else {
1015             $this->behaviour->init_first_step($firststep, $variant);
1016         }
1017         $this->add_step($firststep);
1018
1019         // Record questionline and correct answer.
1020         $this->questionsummary = $this->behaviour->get_question_summary();
1021         $this->rightanswer = $this->behaviour->get_right_answer_summary();
1022     }
1023
1024     /**
1025      * Start this question attempt, starting from the point that the previous
1026      * attempt $oldqa had reached.
1027      *
1028      * You should not call this method directly. Call
1029      * {@link question_usage_by_activity::start_question_based_on()} instead.
1030      *
1031      * @param question_attempt $oldqa a previous attempt at this quetsion that
1032      *      defines the starting point.
1033      */
1034     public function start_based_on(question_attempt $oldqa) {
1035         $this->start($oldqa->behaviour, $oldqa->get_variant(), $oldqa->get_resume_data());
1036     }
1037
1038     /**
1039      * Used by {@link start_based_on()} to get the data needed to start a new
1040      * attempt from the point this attempt has go to.
1041      * @return array name => value pairs.
1042      */
1043     protected function get_resume_data() {
1044         $resumedata = $this->behaviour->get_resume_data();
1045         foreach ($resumedata as $name => $value) {
1046             if ($value instanceof question_file_loader) {
1047                 $resumedata[$name] = $value->get_question_file_saver();
1048             }
1049         }
1050         return $resumedata;
1051     }
1052
1053     /**
1054      * Get a particular parameter from the current request. A wrapper round
1055      * {@link optional_param()}, except that the results is returned without
1056      * slashes.
1057      * @param string $name the paramter name.
1058      * @param int $type one of the standard PARAM_... constants, or one of the
1059      *      special extra constands defined by this class.
1060      * @param array $postdata (optional, only inteded for testing use) take the
1061      *      data from this array, instead of from $_POST.
1062      * @return mixed the requested value.
1063      */
1064     public function get_submitted_var($name, $type, $postdata = null) {
1065         switch ($type) {
1066
1067             case self::PARAM_FILES:
1068                 return $this->process_response_files($name, $name, $postdata);
1069
1070             case self::PARAM_RAW_FILES:
1071                 $var = $this->get_submitted_var($name, PARAM_RAW, $postdata);
1072                 return $this->process_response_files($name, $name . ':itemid', $postdata, $var);
1073
1074             default:
1075                 if (is_null($postdata)) {
1076                     $var = optional_param($name, null, $type);
1077                 } else if (array_key_exists($name, $postdata)) {
1078                     $var = clean_param($postdata[$name], $type);
1079                 } else {
1080                     $var = null;
1081                 }
1082
1083                 if ($var !== null) {
1084                     // Ensure that, if set, $var is a string. This is because later, after
1085                     // it has been saved to the database and loaded back it will be a string,
1086                     // so better if the type is predictably always a string.
1087                     $var = (string) $var;
1088                 }
1089
1090                 return $var;
1091         }
1092     }
1093
1094     /**
1095      * Validate the manual mark for a question.
1096      * @param string $currentmark the user input (e.g. '1,0', '1,0' or 'invalid'.
1097      * @return string any errors with the value, or '' if it is OK.
1098      */
1099     public function validate_manual_mark($currentmark) {
1100         if ($currentmark === null || $currentmark === '') {
1101             return '';
1102         }
1103
1104         $mark = question_utils::clean_param_mark($currentmark);
1105         if ($mark === null) {
1106             return get_string('manualgradeinvalidformat', 'question');
1107         }
1108
1109         $maxmark = $this->get_max_mark();
1110         if ($mark > $maxmark * $this->get_max_fraction() || $mark < $maxmark * $this->get_min_fraction()) {
1111             return get_string('manualgradeoutofrange', 'question');
1112         }
1113
1114         return '';
1115     }
1116
1117     /**
1118      * Handle a submitted variable representing uploaded files.
1119      * @param string $name the field name.
1120      * @param string $draftidname the field name holding the draft file area id.
1121      * @param array $postdata (optional, only inteded for testing use) take the
1122      *      data from this array, instead of from $_POST. At the moment, this
1123      *      behaves as if there were no files.
1124      * @param string $text optional reponse text.
1125      * @return question_file_saver that can be used to save the files later.
1126      */
1127     protected function process_response_files($name, $draftidname, $postdata = null, $text = null) {
1128         if ($postdata) {
1129             // For simulated posts, get the draft itemid from there.
1130             $draftitemid = $this->get_submitted_var($draftidname, PARAM_INT, $postdata);
1131         } else {
1132             $draftitemid = file_get_submitted_draft_itemid($draftidname);
1133         }
1134
1135         if (!$draftitemid) {
1136             return null;
1137         }
1138
1139         $filearea = str_replace($this->get_field_prefix(), '', $name);
1140         $filearea = str_replace('-', 'bf_', $filearea);
1141         $filearea = 'response_' . $filearea;
1142         return new question_file_saver($draftitemid, 'question', $filearea, $text);
1143     }
1144
1145     /**
1146      * Get any data from the request that matches the list of expected params.
1147      *
1148      * @param array $expected variable name => PARAM_... constant.
1149      * @param null|array $postdata null to use real post data, otherwise an array of data to use.
1150      * @param string $extraprefix '-' or ''.
1151      * @return array name => value.
1152      */
1153     protected function get_expected_data($expected, $postdata, $extraprefix) {
1154         $submitteddata = array();
1155         foreach ($expected as $name => $type) {
1156             $value = $this->get_submitted_var(
1157                     $this->get_field_prefix() . $extraprefix . $name, $type, $postdata);
1158             if (!is_null($value)) {
1159                 $submitteddata[$extraprefix . $name] = $value;
1160             }
1161         }
1162         return $submitteddata;
1163     }
1164
1165     /**
1166      * Get all the submitted question type data for this question, whithout checking
1167      * that it is valid or cleaning it in any way.
1168      *
1169      * @param null|array $postdata null to use real post data, otherwise an array of data to use.
1170      * @return array name => value.
1171      */
1172     public function get_all_submitted_qt_vars($postdata) {
1173         if (is_null($postdata)) {
1174             $postdata = $_POST;
1175         }
1176
1177         $pattern = '/^' . preg_quote($this->get_field_prefix(), '/') . '[^-:]/';
1178         $prefixlen = strlen($this->get_field_prefix());
1179
1180         $submitteddata = array();
1181         foreach ($postdata as $name => $value) {
1182             if (preg_match($pattern, $name)) {
1183                 $submitteddata[substr($name, $prefixlen)] = $value;
1184             }
1185         }
1186
1187         return $submitteddata;
1188     }
1189
1190     /**
1191      * Get all the sumbitted data belonging to this question attempt from the
1192      * current request.
1193      * @param array $postdata (optional, only inteded for testing use) take the
1194      *      data from this array, instead of from $_POST.
1195      * @return array name => value pairs that could be passed to {@link process_action()}.
1196      */
1197     public function get_submitted_data($postdata = null) {
1198         $submitteddata = $this->get_expected_data(
1199                 $this->behaviour->get_expected_data(), $postdata, '-');
1200
1201         $expected = $this->behaviour->get_expected_qt_data();
1202         $this->check_qt_var_name_restrictions($expected);
1203
1204         if ($expected === self::USE_RAW_DATA) {
1205             $submitteddata += $this->get_all_submitted_qt_vars($postdata);
1206         } else {
1207             $submitteddata += $this->get_expected_data($expected, $postdata, '');
1208         }
1209         return $submitteddata;
1210     }
1211
1212     /**
1213      * Ensure that no reserved prefixes are being used by installed
1214      * question types.
1215      * @param array $expected An array of question type variables
1216      */
1217     protected function check_qt_var_name_restrictions($expected) {
1218         global $CFG;
1219
1220         if ($CFG->debugdeveloper && $expected !== self::USE_RAW_DATA) {
1221             foreach ($expected as $key => $value) {
1222                 if (strpos($key, 'bf_') !== false) {
1223                     debugging('The bf_ prefix is reserved and cannot be used by question types', DEBUG_DEVELOPER);
1224                 }
1225             }
1226         }
1227     }
1228
1229     /**
1230      * Get a set of response data for this question attempt that would get the
1231      * best possible mark. If it is not possible to compute a correct
1232      * response, this method should return null.
1233      * @return array|null name => value pairs that could be passed to {@link process_action()}.
1234      */
1235     public function get_correct_response() {
1236         $response = $this->question->get_correct_response();
1237         if (is_null($response)) {
1238             return null;
1239         }
1240         $imvars = $this->behaviour->get_correct_response();
1241         foreach ($imvars as $name => $value) {
1242             $response['-' . $name] = $value;
1243         }
1244         return $response;
1245     }
1246
1247     /**
1248      * Change the quetsion summary. Note, that this is almost never necessary.
1249      * This method was only added to work around a limitation of the Opaque
1250      * protocol, which only sends questionLine at the end of an attempt.
1251      * @param string $questionsummary the new summary to set.
1252      */
1253     public function set_question_summary($questionsummary) {
1254         $this->questionsummary = $questionsummary;
1255         $this->observer->notify_attempt_modified($this);
1256     }
1257
1258     /**
1259      * @return string a simple textual summary of the question that was asked.
1260      */
1261     public function get_question_summary() {
1262         return $this->questionsummary;
1263     }
1264
1265     /**
1266      * @return string a simple textual summary of response given.
1267      */
1268     public function get_response_summary() {
1269         return $this->responsesummary;
1270     }
1271
1272     /**
1273      * @return string a simple textual summary of the correct resonse.
1274      */
1275     public function get_right_answer_summary() {
1276         return $this->rightanswer;
1277     }
1278
1279     /**
1280      * Whether this attempt at this question could be completed just by the
1281      * student interacting with the question, before {@link finish()} is called.
1282      *
1283      * @return boolean whether this attempt can finish naturally.
1284      */
1285     public function can_finish_during_attempt() {
1286         return $this->behaviour->can_finish_during_attempt();
1287     }
1288
1289     /**
1290      * Perform the action described by $submitteddata.
1291      * @param array $submitteddata the submitted data the determines the action.
1292      * @param int $timestamp the time to record for the action. (If not given, use now.)
1293      * @param int $userid the user to attribute the action to. (If not given, use the current user.)
1294      * @param int $existingstepid used by the regrade code.
1295      */
1296     public function process_action($submitteddata, $timestamp = null, $userid = null, $existingstepid = null) {
1297         $pendingstep = new question_attempt_pending_step($submitteddata, $timestamp, $userid, $existingstepid);
1298         $this->discard_autosaved_step();
1299         if ($this->behaviour->process_action($pendingstep) == self::KEEP) {
1300             $this->add_step($pendingstep);
1301             if ($pendingstep->response_summary_changed()) {
1302                 $this->responsesummary = $pendingstep->get_new_response_summary();
1303             }
1304             if ($pendingstep->variant_number_changed()) {
1305                 $this->variant = $pendingstep->get_new_variant_number();
1306             }
1307         }
1308     }
1309
1310     /**
1311      * Process an autosave.
1312      * @param array $submitteddata the submitted data the determines the action.
1313      * @param int $timestamp the time to record for the action. (If not given, use now.)
1314      * @param int $userid the user to attribute the action to. (If not given, use the current user.)
1315      * @return bool whether anything was saved.
1316      */
1317     public function process_autosave($submitteddata, $timestamp = null, $userid = null) {
1318         $pendingstep = new question_attempt_pending_step($submitteddata, $timestamp, $userid);
1319         if ($this->behaviour->process_autosave($pendingstep) == self::KEEP) {
1320             $this->add_autosaved_step($pendingstep);
1321             return true;
1322         }
1323         return false;
1324     }
1325
1326     /**
1327      * Perform a finish action on this question attempt. This corresponds to an
1328      * external finish action, for example the user pressing Submit all and finish
1329      * in the quiz, rather than using one of the controls that is part of the
1330      * question.
1331      *
1332      * @param int $timestamp the time to record for the action. (If not given, use now.)
1333      * @param int $userid the user to attribute the aciton to. (If not given, use the current user.)
1334      */
1335     public function finish($timestamp = null, $userid = null) {
1336         $this->convert_autosaved_step_to_real_step();
1337         $this->process_action(array('-finish' => 1), $timestamp, $userid);
1338     }
1339
1340     /**
1341      * Perform a regrade. This replays all the actions from $oldqa into this
1342      * attempt.
1343      * @param question_attempt $oldqa the attempt to regrade.
1344      * @param bool $finished whether the question attempt should be forced to be finished
1345      *      after the regrade, or whether it may still be in progress (default false).
1346      */
1347     public function regrade(question_attempt $oldqa, $finished) {
1348         $first = true;
1349         foreach ($oldqa->get_step_iterator() as $step) {
1350             $this->observer->notify_step_deleted($step, $this);
1351
1352             if ($first) {
1353                 // First step of the attempt.
1354                 $first = false;
1355                 $this->start($oldqa->behaviour, $oldqa->get_variant(), $step->get_all_data(),
1356                         $step->get_timecreated(), $step->get_user_id(), $step->get_id());
1357
1358             } else if ($step->has_behaviour_var('finish') && count($step->get_submitted_data()) > 1) {
1359                 // This case relates to MDL-32062. The upgrade code from 2.0
1360                 // generates attempts where the final submit of the question
1361                 // data, and the finish action, are in the same step. The system
1362                 // cannot cope with that, so convert the single old step into
1363                 // two new steps.
1364                 $submitteddata = $step->get_submitted_data();
1365                 unset($submitteddata['-finish']);
1366                 $this->process_action($submitteddata,
1367                         $step->get_timecreated(), $step->get_user_id(), $step->get_id());
1368                 $this->finish($step->get_timecreated(), $step->get_user_id());
1369
1370             } else {
1371                 // This is the normal case. Replay the next step of the attempt.
1372                 $this->process_action($step->get_submitted_data(),
1373                         $step->get_timecreated(), $step->get_user_id(), $step->get_id());
1374             }
1375         }
1376
1377         if ($finished) {
1378             $this->finish();
1379         }
1380
1381         $this->set_flagged($oldqa->is_flagged());
1382     }
1383
1384     /**
1385      * Change the max mark for this question_attempt.
1386      * @param float $maxmark the new max mark.
1387      */
1388     public function set_max_mark($maxmark) {
1389         $this->maxmark = $maxmark;
1390         $this->observer->notify_attempt_modified($this);
1391     }
1392
1393     /**
1394      * Perform a manual grading action on this attempt.
1395      * @param string $comment the comment being added.
1396      * @param float $mark the new mark. If null, then only a comment is added.
1397      * @param int $commentformat the FORMAT_... for $comment. Must be given.
1398      * @param int $timestamp the time to record for the action. (If not given, use now.)
1399      * @param int $userid the user to attribute the aciton to. (If not given, use the current user.)
1400      */
1401     public function manual_grade($comment, $mark, $commentformat = null, $timestamp = null, $userid = null) {
1402         $submitteddata = array('-comment' => $comment);
1403         if (is_null($commentformat)) {
1404             debugging('You should pass $commentformat to manual_grade.', DEBUG_DEVELOPER);
1405             $commentformat = FORMAT_HTML;
1406         }
1407         $submitteddata['-commentformat'] = $commentformat;
1408         if (!is_null($mark)) {
1409             $submitteddata['-mark'] = $mark;
1410             $submitteddata['-maxmark'] = $this->maxmark;
1411         }
1412         $this->process_action($submitteddata, $timestamp, $userid);
1413     }
1414
1415     /** @return bool Whether this question attempt has had a manual comment added. */
1416     public function has_manual_comment() {
1417         foreach ($this->steps as $step) {
1418             if ($step->has_behaviour_var('comment')) {
1419                 return true;
1420             }
1421         }
1422         return false;
1423     }
1424
1425     /**
1426      * @return array(string, int) the most recent manual comment that was added
1427      * to this question, the FORMAT_... it is and the step itself.
1428      */
1429     public function get_manual_comment() {
1430         foreach ($this->get_reverse_step_iterator() as $step) {
1431             if ($step->has_behaviour_var('comment')) {
1432                 return array($step->get_behaviour_var('comment'),
1433                         $step->get_behaviour_var('commentformat'),
1434                         $step);
1435             }
1436         }
1437         return array(null, null, null);
1438     }
1439
1440     /**
1441      * This is used by the manual grading code, particularly in association with
1442      * validation. If there is a comment submitted in the request, then use that,
1443      * otherwise use the latest comment for this question.
1444      *
1445      * @return array with three elements, comment, commentformat and mark.
1446      */
1447     public function get_current_manual_comment() {
1448         $comment = $this->get_submitted_var($this->get_behaviour_field_name('comment'), PARAM_RAW);
1449         if (is_null($comment)) {
1450             return $this->get_manual_comment();
1451         } else {
1452             $commentformat = $this->get_submitted_var(
1453                     $this->get_behaviour_field_name('commentformat'), PARAM_INT);
1454             if ($commentformat === null) {
1455                 $commentformat = FORMAT_HTML;
1456             }
1457             return array($comment, $commentformat, null);
1458         }
1459     }
1460
1461     /**
1462      * Break down a student response by sub part and classification. See also {@link question::classify_response}.
1463      * Used for response analysis.
1464      *
1465      * @param string $whichtries which tries to analyse for response analysis. Will be one of
1466      *      question_attempt::FIRST_TRY, LAST_TRY or ALL_TRIES. Defaults to question_attempt::LAST_TRY.
1467      * @return question_classified_response[]|question_classified_response[][] If $whichtries is
1468      *      question_attempt::FIRST_TRY or LAST_TRY index is subpartid and values are
1469      *      question_classified_response instances.
1470      *      If $whichtries is question_attempt::ALL_TRIES then first key is submitted response no
1471      *      and the second key is subpartid.
1472      */
1473     public function classify_response($whichtries = self::LAST_TRY) {
1474         return $this->behaviour->classify_response($whichtries);
1475     }
1476
1477     /**
1478      * Create a question_attempt_step from records loaded from the database.
1479      *
1480      * For internal use only.
1481      *
1482      * @param Iterator $records Raw records loaded from the database.
1483      * @param int $questionattemptid The id of the question_attempt to extract.
1484      * @param question_usage_observer $observer the observer that will be monitoring changes in us.
1485      * @param string $preferredbehaviour the preferred behaviour under which we are operating.
1486      * @return question_attempt The newly constructed question_attempt.
1487      */
1488     public static function load_from_records($records, $questionattemptid,
1489             question_usage_observer $observer, $preferredbehaviour) {
1490         $record = $records->current();
1491         while ($record->questionattemptid != $questionattemptid) {
1492             $records->next();
1493             if (!$records->valid()) {
1494                 throw new coding_exception("Question attempt {$questionattemptid} not found in the database.");
1495             }
1496             $record = $records->current();
1497         }
1498
1499         try {
1500             $question = question_bank::load_question($record->questionid);
1501         } catch (Exception $e) {
1502             // The question must have been deleted somehow. Create a missing
1503             // question to use in its place.
1504             $question = question_bank::get_qtype('missingtype')->make_deleted_instance(
1505                     $record->questionid, $record->maxmark + 0);
1506         }
1507
1508         $qa = new question_attempt($question, $record->questionusageid,
1509                 null, $record->maxmark + 0);
1510         $qa->set_database_id($record->questionattemptid);
1511         $qa->set_slot($record->slot);
1512         $qa->variant = $record->variant + 0;
1513         $qa->minfraction = $record->minfraction + 0;
1514         $qa->maxfraction = $record->maxfraction + 0;
1515         $qa->set_flagged($record->flagged);
1516         $qa->questionsummary = $record->questionsummary;
1517         $qa->rightanswer = $record->rightanswer;
1518         $qa->responsesummary = $record->responsesummary;
1519         $qa->timemodified = $record->timemodified;
1520
1521         $qa->behaviour = question_engine::make_behaviour(
1522                 $record->behaviour, $qa, $preferredbehaviour);
1523         $qa->observer = $observer;
1524
1525         // If attemptstepid is null (which should not happen, but has happened
1526         // due to corrupt data, see MDL-34251) then the current pointer in $records
1527         // will not be advanced in the while loop below, and we get stuck in an
1528         // infinite loop, since this method is supposed to always consume at
1529         // least one record. Therefore, in this case, advance the record here.
1530         if (is_null($record->attemptstepid)) {
1531             $records->next();
1532         }
1533
1534         $i = 0;
1535         $autosavedstep = null;
1536         $autosavedsequencenumber = null;
1537         while ($record && $record->questionattemptid == $questionattemptid && !is_null($record->attemptstepid)) {
1538             $sequencenumber = $record->sequencenumber;
1539             $nextstep = question_attempt_step::load_from_records($records, $record->attemptstepid, $qa->get_question()->get_type_name());
1540
1541             if ($sequencenumber < 0) {
1542                 if (!$autosavedstep) {
1543                     $autosavedstep = $nextstep;
1544                     $autosavedsequencenumber = -$sequencenumber;
1545                 } else {
1546                     // Old redundant data. Mark it for deletion.
1547                     $qa->observer->notify_step_deleted($nextstep, $qa);
1548                 }
1549             } else {
1550                 $qa->steps[$i] = $nextstep;
1551                 if ($i == 0) {
1552                     $question->apply_attempt_state($qa->steps[0]);
1553                 }
1554                 $i++;
1555             }
1556
1557             if ($records->valid()) {
1558                 $record = $records->current();
1559             } else {
1560                 $record = false;
1561             }
1562         }
1563
1564         if ($autosavedstep) {
1565             if ($autosavedsequencenumber >= $i) {
1566                 $qa->autosavedstep = $autosavedstep;
1567                 $qa->steps[$i] = $qa->autosavedstep;
1568             } else {
1569                 $qa->observer->notify_step_deleted($autosavedstep, $qa);
1570             }
1571         }
1572
1573         return $qa;
1574     }
1575
1576     /**
1577      * Allow access to steps with responses submitted by students for grading in a question attempt.
1578      *
1579      * @return question_attempt_steps_with_submitted_response_iterator to access all steps with submitted data for questions that
1580      *                                                      allow multiple submissions that count towards grade, per attempt.
1581      */
1582     public function get_steps_with_submitted_response_iterator() {
1583         return new question_attempt_steps_with_submitted_response_iterator($this);
1584     }
1585 }
1586
1587
1588 /**
1589  * This subclass of question_attempt pretends that only part of the step history
1590  * exists. It is used for rendering the question in past states.
1591  *
1592  * All methods that try to modify the question_attempt throw exceptions.
1593  *
1594  * @copyright  2010 The Open University
1595  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1596  */
1597 class question_attempt_with_restricted_history extends question_attempt {
1598     /**
1599      * @var question_attempt the underlying question_attempt.
1600      */
1601     protected $baseqa;
1602
1603     /**
1604      * Create a question_attempt_with_restricted_history
1605      * @param question_attempt $baseqa The question_attempt to make a restricted version of.
1606      * @param int $lastseq the index of the last step to include.
1607      * @param string $preferredbehaviour the preferred behaviour. It is slightly
1608      *      annoying that this needs to be passed, but unavoidable for now.
1609      */
1610     public function __construct(question_attempt $baseqa, $lastseq, $preferredbehaviour) {
1611         $this->baseqa = $baseqa->get_full_qa();
1612
1613         if ($lastseq < 0 || $lastseq >= $this->baseqa->get_num_steps()) {
1614             throw new coding_exception('$lastseq out of range', $lastseq);
1615         }
1616
1617         $this->steps = array_slice($this->baseqa->steps, 0, $lastseq + 1);
1618         $this->observer = new question_usage_null_observer();
1619
1620         // This should be a straight copy of all the remaining fields.
1621         $this->id = $this->baseqa->id;
1622         $this->usageid = $this->baseqa->usageid;
1623         $this->slot = $this->baseqa->slot;
1624         $this->question = $this->baseqa->question;
1625         $this->maxmark = $this->baseqa->maxmark;
1626         $this->minfraction = $this->baseqa->minfraction;
1627         $this->maxfraction = $this->baseqa->maxfraction;
1628         $this->questionsummary = $this->baseqa->questionsummary;
1629         $this->responsesummary = $this->baseqa->responsesummary;
1630         $this->rightanswer = $this->baseqa->rightanswer;
1631         $this->flagged = $this->baseqa->flagged;
1632
1633         // Except behaviour, where we need to create a new one.
1634         $this->behaviour = question_engine::make_behaviour(
1635                 $this->baseqa->get_behaviour_name(), $this, $preferredbehaviour);
1636     }
1637
1638     public function get_full_qa() {
1639         return $this->baseqa;
1640     }
1641
1642     public function get_full_step_iterator() {
1643         return $this->baseqa->get_step_iterator();
1644     }
1645
1646     protected function add_step(question_attempt_step $step) {
1647         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1648     }
1649     public function process_action($submitteddata, $timestamp = null, $userid = null, $existingstepid = null) {
1650         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1651     }
1652     public function start($preferredbehaviour, $variant, $submitteddata = array(), $timestamp = null, $userid = null, $existingstepid = null) {
1653         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1654     }
1655
1656     public function set_database_id($id) {
1657         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1658     }
1659     public function set_flagged($flagged) {
1660         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1661     }
1662     public function set_slot($slot) {
1663         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1664     }
1665     public function set_question_summary($questionsummary) {
1666         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1667     }
1668     public function set_usage_id($usageid) {
1669         throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
1670     }
1671 }
1672
1673
1674 /**
1675  * A class abstracting access to the {@link question_attempt::$states} array.
1676  *
1677  * This is actively linked to question_attempt. If you add an new step
1678  * mid-iteration, then it will be included.
1679  *
1680  * @copyright  2009 The Open University
1681  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1682  */
1683 class question_attempt_step_iterator implements Iterator, ArrayAccess {
1684     /** @var question_attempt the question_attempt being iterated over. */
1685     protected $qa;
1686     /** @var integer records the current position in the iteration. */
1687     protected $i;
1688
1689     /**
1690      * Do not call this constructor directly.
1691      * Use {@link question_attempt::get_step_iterator()}.
1692      * @param question_attempt $qa the attempt to iterate over.
1693      */
1694     public function __construct(question_attempt $qa) {
1695         $this->qa = $qa;
1696         $this->rewind();
1697     }
1698
1699     /** @return question_attempt_step */
1700     public function current() {
1701         return $this->offsetGet($this->i);
1702     }
1703     /** @return int */
1704     public function key() {
1705         return $this->i;
1706     }
1707     public function next() {
1708         ++$this->i;
1709     }
1710     public function rewind() {
1711         $this->i = 0;
1712     }
1713     /** @return bool */
1714     public function valid() {
1715         return $this->offsetExists($this->i);
1716     }
1717
1718     /** @return bool */
1719     public function offsetExists($i) {
1720         return $i >= 0 && $i < $this->qa->get_num_steps();
1721     }
1722     /** @return question_attempt_step */
1723     public function offsetGet($i) {
1724         return $this->qa->get_step($i);
1725     }
1726     public function offsetSet($offset, $value) {
1727         throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot set.');
1728     }
1729     public function offsetUnset($offset) {
1730         throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot unset.');
1731     }
1732 }
1733
1734
1735 /**
1736  * A variant of {@link question_attempt_step_iterator} that iterates through the
1737  * steps in reverse order.
1738  *
1739  * @copyright  2009 The Open University
1740  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1741  */
1742 class question_attempt_reverse_step_iterator extends question_attempt_step_iterator {
1743     public function next() {
1744         --$this->i;
1745     }
1746
1747     public function rewind() {
1748         $this->i = $this->qa->get_num_steps() - 1;
1749     }
1750 }
1751
1752 /**
1753  * A variant of {@link question_attempt_step_iterator} that iterates through the
1754  * steps with submitted tries.
1755  *
1756  * @copyright  2014 The Open University
1757  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1758  */
1759 class question_attempt_steps_with_submitted_response_iterator extends question_attempt_step_iterator implements Countable {
1760
1761     /** @var question_attempt the question_attempt being iterated over. */
1762     protected $qa;
1763
1764     /** @var integer records the current position in the iteration. */
1765     protected $submittedresponseno;
1766
1767     /**
1768      * Index is the submitted response number and value is the step no.
1769      *
1770      * @var int[]
1771      */
1772     protected $stepswithsubmittedresponses;
1773
1774     /**
1775      * Do not call this constructor directly.
1776      * Use {@link question_attempt::get_submission_step_iterator()}.
1777      * @param question_attempt $qa the attempt to iterate over.
1778      */
1779     public function __construct(question_attempt $qa) {
1780         $this->qa = $qa;
1781         $this->find_steps_with_submitted_response();
1782         $this->rewind();
1783     }
1784
1785     /**
1786      * Find the step nos  in which a student has submitted a response. Including any step with a response that is saved before
1787      * the question attempt finishes.
1788      *
1789      * Called from constructor, should not be called from elsewhere.
1790      *
1791      */
1792     protected function find_steps_with_submitted_response() {
1793         $stepnos = array();
1794         $lastsavedstep = null;
1795         foreach ($this->qa->get_step_iterator() as $stepno => $step) {
1796             if ($this->qa->get_behaviour()->step_has_a_submitted_response($step)) {
1797                 $stepnos[] = $stepno;
1798                 $lastsavedstep = null;
1799             } else {
1800                 $qtdata = $step->get_qt_data();
1801                 if (count($qtdata)) {
1802                     $lastsavedstep = $stepno;
1803                 }
1804             }
1805         }
1806
1807         if (!is_null($lastsavedstep)) {
1808             $stepnos[] = $lastsavedstep;
1809         }
1810         if (empty($stepnos)) {
1811             $this->stepswithsubmittedresponses = array();
1812         } else {
1813             // Re-index array so index starts with 1.
1814             $this->stepswithsubmittedresponses = array_combine(range(1, count($stepnos)), $stepnos);
1815         }
1816     }
1817
1818     /** @return question_attempt_step */
1819     public function current() {
1820         return $this->offsetGet($this->submittedresponseno);
1821     }
1822     /** @return int */
1823     public function key() {
1824         return $this->submittedresponseno;
1825     }
1826     public function next() {
1827         ++$this->submittedresponseno;
1828     }
1829     public function rewind() {
1830         $this->submittedresponseno = 1;
1831     }
1832     /** @return bool */
1833     public function valid() {
1834         return $this->submittedresponseno >= 1 && $this->submittedresponseno <= count($this->stepswithsubmittedresponses);
1835     }
1836
1837     /**
1838      * @param int $submittedresponseno
1839      * @return bool
1840      */
1841     public function offsetExists($submittedresponseno) {
1842         return $submittedresponseno >= 1;
1843     }
1844
1845     /**
1846      * @param int $submittedresponseno
1847      * @return question_attempt_step
1848      */
1849     public function offsetGet($submittedresponseno) {
1850         if ($submittedresponseno > count($this->stepswithsubmittedresponses)) {
1851             return null;
1852         } else {
1853             return $this->qa->get_step($this->step_no_for_try($submittedresponseno));
1854         }
1855     }
1856
1857     /**
1858      * @return int the count of steps with tries.
1859      */
1860     public function count() {
1861         return count($this->stepswithsubmittedresponses);
1862     }
1863
1864     /**
1865      * @param int $submittedresponseno
1866      * @throws coding_exception
1867      * @return int|null the step number or null if there is no such submitted response.
1868      */
1869     public function step_no_for_try($submittedresponseno) {
1870         if (isset($this->stepswithsubmittedresponses[$submittedresponseno])) {
1871             return $this->stepswithsubmittedresponses[$submittedresponseno];
1872         } else if ($submittedresponseno > count($this->stepswithsubmittedresponses)) {
1873             return null;
1874         } else {
1875             throw new coding_exception('Try number not found. It should be 1 or more.');
1876         }
1877     }
1878
1879     public function offsetSet($offset, $value) {
1880         throw new coding_exception('You are only allowed read-only access to question_attempt::states '.
1881                                    'through a question_attempt_step_iterator. Cannot set.');
1882     }
1883     public function offsetUnset($offset) {
1884         throw new coding_exception('You are only allowed read-only access to question_attempt::states '.
1885                                    'through a question_attempt_step_iterator. Cannot unset.');
1886     }
1887
1888 }