C:/xampp/htdocs/moodle/question/engine/questionattempt.php

Go to the documentation of this file.

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

defined('MOODLE_INTERNAL') || die();


class question_attempt {
    const USE_RAW_DATA = 'use raw data';

    const PARAM_MARK = 'parammark';

    const PARAM_FILES = 'paramfiles';

    const PARAM_CLEANHTML_FILES = 'paramcleanhtmlfiles';

    protected $id = null;

    protected $usageid;

    protected $slot = null;

    protected $behaviour = null;

    protected $question;

    protected $variant;

    protected $maxmark;

    protected $minfraction = null;

    protected $questionsummary = null;

    protected $responsesummary = null;

    protected $rightanswer = null;

    protected $steps = array();

    protected $flagged = false;

    protected $observer;

    const KEEP = true;
    const DISCARD = false;
    public function __construct(question_definition $question, $usageid,
            question_usage_observer $observer = null, $maxmark = null) {
        $this->question = $question;
        $this->usageid = $usageid;
        if (is_null($observer)) {
            $observer = new question_usage_null_observer();
        }
        $this->observer = $observer;
        if (!is_null($maxmark)) {
            $this->maxmark = $maxmark;
        } else {
            $this->maxmark = $question->defaultmark;
        }
    }

    public function get_full_qa() {
        return $this;
    }

    public function get_question() {
        return $this->question;
    }

    public function get_variant() {
        return $this->variant;
    }

    public function set_slot($slot) {
        $this->slot = $slot;
    }

    public function get_slot() {
        return $this->slot;
    }

    public function get_database_id() {
        return $this->id;
    }

    public function set_database_id($id) {
        $this->id = $id;
    }

    public function set_observer($observer) {
        $this->observer = $observer;
    }

    public function get_usage_id() {
        return $this->usageid;
    }

    public function set_usage_id($usageid) {
        $this->usageid = $usageid;
    }

    public function get_behaviour_name() {
        return $this->behaviour->get_name();
    }

    public function get_behaviour() {
        return $this->behaviour;
    }

    public function set_flagged($flagged) {
        $this->flagged = $flagged;
        $this->observer->notify_attempt_modified($this);
    }

    public function is_flagged() {
        return $this->flagged;
    }

    public function get_flag_field_name() {
        return $this->get_control_field_name('flagged');
    }

    public function get_qt_field_name($varname) {
        return $this->get_field_prefix() . $varname;
    }

    public function get_behaviour_field_name($varname) {
        return $this->get_field_prefix() . '-' . $varname;
    }

    public function get_control_field_name($varname) {
        return $this->get_field_prefix() . ':' . $varname;
    }

    public function get_field_prefix() {
        return 'q' . $this->usageid . ':' . $this->slot . '_';
    }

    public function get_step($i) {
        if ($i < 0 || $i >= count($this->steps)) {
            throw new coding_exception('Index out of bounds in question_attempt::get_step.');
        }
        return $this->steps[$i];
    }

    public function get_num_steps() {
        return count($this->steps);
    }

    public function get_last_step() {
        if (count($this->steps) == 0) {
            return new question_null_step();
        }
        return end($this->steps);
    }

    public function get_step_iterator() {
        return new question_attempt_step_iterator($this);
    }

    public function get_full_step_iterator() {
        return $this->get_step_iterator();
    }

    public function get_reverse_step_iterator() {
        return new question_attempt_reverse_step_iterator($this);
    }

    public function get_last_qt_data($default = array()) {
        foreach ($this->get_reverse_step_iterator() as $step) {
            $response = $step->get_qt_data();
            if (!empty($response)) {
                return $response;
            }
        }
        return $default;
    }

    public function get_last_step_with_qt_var($name) {
        foreach ($this->get_reverse_step_iterator() as $step) {
            if ($step->has_qt_var($name)) {
                return $step;
            }
        }
        return new question_attempt_step_read_only();
    }

    public function get_last_step_with_behaviour_var($name) {
        foreach ($this->get_reverse_step_iterator() as $step) {
            if ($step->has_behaviour_var($name)) {
                return $step;
            }
        }
        return new question_attempt_step_read_only();
    }

    public function get_last_qt_var($name, $default = null) {
        $step = $this->get_last_step_with_qt_var($name);
        if ($step->has_qt_var($name)) {
            return $step->get_qt_var($name);
        } else {
            return $default;
        }
    }

    public function get_last_qt_files($name, $contextid) {
        foreach ($this->get_reverse_step_iterator() as $step) {
            if ($step->has_qt_var($name)) {
                return $step->get_qt_files($name, $contextid);
            }
        }
        return array();
    }

    public function get_response_file_url(stored_file $file) {
        return file_encode_url(new moodle_url('/pluginfile.php'), '/' . implode('/', array(
                $file->get_contextid(),
                $file->get_component(),
                $file->get_filearea(),
                $this->usageid,
                $this->slot,
                $file->get_itemid())) .
                $file->get_filepath() . $file->get_filename(), true);
    }

    public function prepare_response_files_draft_itemid($name, $contextid) {
        foreach ($this->get_reverse_step_iterator() as $step) {
            if ($step->has_qt_var($name)) {
                return $step->prepare_response_files_draft_itemid($name, $contextid);
            }
        }

        // No files yet.
        $draftid = 0; // Will be filled in by file_prepare_draft_area.
        file_prepare_draft_area($draftid, $contextid, 'question', 'response_' . $name, null);
        return $draftid;
    }

    public function get_last_behaviour_var($name, $default = null) {
        foreach ($this->get_reverse_step_iterator() as $step) {
            if ($step->has_behaviour_var($name)) {
                return $step->get_behaviour_var($name);
            }
        }
        return $default;
    }

    public function get_state() {
        return $this->get_last_step()->get_state();
    }

    public function get_state_string($showcorrectness) {
        return $this->behaviour->get_state_string($showcorrectness);
    }

    public function get_state_class($showcorrectness) {
        return $this->get_state()->get_state_class($showcorrectness);
    }

    public function get_last_action_time() {
        return $this->get_last_step()->get_timecreated();
    }

    public function get_fraction() {
        return $this->get_last_step()->get_fraction();
    }

    public function has_marks() {
        // Since grades are stored in the database as NUMBER(12,7).
        return $this->maxmark >= 0.00000005;
    }

    public function get_mark() {
        return $this->fraction_to_mark($this->get_fraction());
    }

    public function get_current_manual_mark() {
        $mark = $this->get_submitted_var($this->get_behaviour_field_name('mark'), question_attempt::PARAM_MARK);
        if (is_null($mark)) {
            return $this->get_mark();
        } else {
            return $mark;
        }
    }

    public function fraction_to_mark($fraction) {
        if (is_null($fraction)) {
            return null;
        }
        return $fraction * $this->maxmark;
    }

    public function get_max_mark() {
        return $this->maxmark;
    }

    public function get_min_fraction() {
        if (is_null($this->minfraction)) {
            throw new coding_exception('This question_attempt has not been started yet, the min fraction is not yet konwn.');
        }
        return $this->minfraction;
    }

    public function format_mark($dp) {
        return $this->format_fraction_as_mark($this->get_fraction(), $dp);
    }

    public function format_fraction_as_mark($fraction, $dp) {
        return format_float($this->fraction_to_mark($fraction), $dp);
    }

    public function format_max_mark($dp) {
        return format_float($this->maxmark, $dp);
    }

    public function get_applicable_hint() {
        return $this->behaviour->get_applicable_hint();
    }

    public function summarise_action(question_attempt_step $step) {
        return $this->behaviour->summarise_action($step);
    }

    protected function extra_file_path_components() {
        return array($this->get_usage_id(), $this->get_slot());
    }

    public function rewrite_pluginfile_urls($text, $component, $filearea, $itemid) {
        return question_rewrite_question_urls($text, 'pluginfile.php',
                $this->question->contextid, $component, $filearea,
                $this->extra_file_path_components(), $itemid);
    }

    public function rewrite_response_pluginfile_urls($text, $contextid, $name,
            question_attempt_step $step) {
        return $step->rewrite_response_pluginfile_urls($text, $contextid, $name,
                $this->extra_file_path_components());
    }

    public function render($options, $number, $page = null) {
        if (is_null($page)) {
            global $PAGE;
            $page = $PAGE;
        }
        $qoutput = $page->get_renderer('core', 'question');
        $qtoutput = $this->question->get_renderer($page);
        return $this->behaviour->render($options, $number, $qoutput, $qtoutput);
    }

    public function render_head_html($page = null) {
        if (is_null($page)) {
            global $PAGE;
            $page = $PAGE;
        }
        // TODO go via behaviour.
        return $this->question->get_renderer($page)->head_code($this) .
                $this->behaviour->get_renderer($page)->head_code($this);
    }

    public function render_at_step($seq, $options, $number, $preferredbehaviour) {
        $restrictedqa = new question_attempt_with_restricted_history($this, $seq, $preferredbehaviour);
        return $restrictedqa->render($options, $number);
    }

    public function check_file_access($options, $component, $filearea, $args, $forcedownload) {
        return $this->behaviour->check_file_access($options, $component, $filearea, $args, $forcedownload);
    }

    protected function add_step(question_attempt_step $step) {
        $this->steps[] = $step;
        end($this->steps);
        $this->observer->notify_step_added($step, $this, key($this->steps));
    }

    public function select_variant(question_variant_selection_strategy $variantstrategy) {
        return $variantstrategy->choose_variant($this->get_question()->get_num_variants(),
                $this->get_question()->get_variants_selection_seed());
    }

    public function start($preferredbehaviour, $variant, $submitteddata = array(),
            $timestamp = null, $userid = null, $existingstepid = null) {

        // Initialise the behaviour.
        $this->variant = $variant;
        if (is_string($preferredbehaviour)) {
            $this->behaviour =
                    $this->question->make_behaviour($this, $preferredbehaviour);
        } else {
            $class = get_class($preferredbehaviour);
            $this->behaviour = new $class($this, $preferredbehaviour);
        }

        // Record the minimum fraction.
        $this->minfraction = $this->behaviour->get_min_fraction();

        // Initialise the first step.
        $firststep = new question_attempt_step($submitteddata, $timestamp, $userid, $existingstepid);
        $firststep->set_state(question_state::$todo);
        if ($submitteddata) {
            $this->question->apply_attempt_state($firststep);
        } else {
            $this->behaviour->init_first_step($firststep, $variant);
        }
        $this->add_step($firststep);

        // Record questionline and correct answer.
        $this->questionsummary = $this->behaviour->get_question_summary();
        $this->rightanswer = $this->behaviour->get_right_answer_summary();
    }

    public function start_based_on(question_attempt $oldqa) {
        $this->start($oldqa->behaviour, $oldqa->get_variant(), $oldqa->get_resume_data());
    }

    protected function get_resume_data() {
        return $this->behaviour->get_resume_data();
    }

    public function get_submitted_var($name, $type, $postdata = null) {
        switch ($type) {
            case self::PARAM_MARK:
                // Special case to work around PARAM_NUMBER converting '' to 0.
                $mark = $this->get_submitted_var($name, PARAM_RAW_TRIMMED, $postdata);
                if ($mark === '') {
                    return $mark;
                } else {
                    return $this->get_submitted_var($name, PARAM_NUMBER, $postdata);
                }

            case self::PARAM_FILES:
                return $this->process_response_files($name, $name, $postdata);

            case self::PARAM_CLEANHTML_FILES:
                $var = $this->get_submitted_var($name, PARAM_CLEANHTML, $postdata);
                return $this->process_response_files($name, $name . ':itemid', $postdata, $var);

            default:
                if (is_null($postdata)) {
                    $var = optional_param($name, null, $type);
                } else if (array_key_exists($name, $postdata)) {
                    $var = clean_param($postdata[$name], $type);
                } else {
                    $var = null;
                }

                return $var;
        }
    }

    protected function process_response_files($name, $draftidname, $postdata = null, $text = null) {
        if ($postdata) {
            // There can be no files with test data (at the moment).
            return null;
        }

        $draftitemid = file_get_submitted_draft_itemid($draftidname);
        if (!$draftitemid) {
            return null;
        }

        return new question_file_saver($draftitemid, 'question', 'response_' .
                str_replace($this->get_field_prefix(), '', $name), $text);
    }

    protected function get_expected_data($expected, $postdata, $extraprefix) {
        $submitteddata = array();
        foreach ($expected as $name => $type) {
            $value = $this->get_submitted_var(
                    $this->get_field_prefix() . $extraprefix . $name, $type, $postdata);
            if (!is_null($value)) {
                $submitteddata[$extraprefix . $name] = $value;
            }
        }
        return $submitteddata;
    }

    protected function get_all_submitted_qt_vars($postdata) {
        if (is_null($postdata)) {
            $postdata = $_POST;
        }

        $pattern = '/^' . preg_quote($this->get_field_prefix()) . '[^-:]/';
        $prefixlen = strlen($this->get_field_prefix());

        $submitteddata = array();
        foreach ($_POST as $name => $value) {
            if (preg_match($pattern, $name)) {
                $submitteddata[substr($name, $prefixlen)] = $value;
            }
        }

        return $submitteddata;
    }

    public function get_submitted_data($postdata = null) {
        $submitteddata = $this->get_expected_data(
                $this->behaviour->get_expected_data(), $postdata, '-');

        $expected = $this->behaviour->get_expected_qt_data();
        if ($expected === self::USE_RAW_DATA) {
            $submitteddata += $this->get_all_submitted_qt_vars($postdata);
        } else {
            $submitteddata += $this->get_expected_data($expected, $postdata, '');
        }
        return $submitteddata;
    }

    public function get_correct_response() {
        $response = $this->question->get_correct_response();
        if (is_null($response)) {
            return null;
        }
        $imvars = $this->behaviour->get_correct_response();
        foreach ($imvars as $name => $value) {
            $response['-' . $name] = $value;
        }
        return $response;
    }

    public function set_question_summary($questionsummary) {
        $this->questionsummary = $questionsummary;
        $this->observer->notify_attempt_modified($this);
    }

    public function get_question_summary() {
        return $this->questionsummary;
    }

    public function get_response_summary() {
        return $this->responsesummary;
    }

    public function get_right_answer_summary() {
        return $this->rightanswer;
    }

    public function process_action($submitteddata, $timestamp = null, $userid = null, $existingstepid = null) {
        $pendingstep = new question_attempt_pending_step($submitteddata, $timestamp, $userid, $existingstepid);
        if ($this->behaviour->process_action($pendingstep) == self::KEEP) {
            $this->add_step($pendingstep);
            if ($pendingstep->response_summary_changed()) {
                $this->responsesummary = $pendingstep->get_new_response_summary();
            }
        }
    }

    public function finish($timestamp = null, $userid = null) {
        $this->process_action(array('-finish' => 1), $timestamp, $userid);
    }

    public function regrade(question_attempt $oldqa, $finished) {
        $first = true;
        foreach ($oldqa->get_step_iterator() as $step) {
            $this->observer->notify_step_deleted($step, $this);
            if ($first) {
                $first = false;
                $this->start($oldqa->behaviour, $oldqa->get_variant(), $step->get_all_data(),
                        $step->get_timecreated(), $step->get_user_id(), $step->get_id());
            } else {
                $this->process_action($step->get_submitted_data(),
                        $step->get_timecreated(), $step->get_user_id(), $step->get_id());
            }
        }
        if ($finished) {
            $this->finish();
        }
    }

    public function manual_grade($comment, $mark, $timestamp = null, $userid = null) {
        $submitteddata = array('-comment' => $comment);
        if (!is_null($mark)) {
            $submitteddata['-mark'] = $mark;
            $submitteddata['-maxmark'] = $this->maxmark;
        }
        $this->process_action($submitteddata, $timestamp, $userid);
    }

    public function has_manual_comment() {
        foreach ($this->steps as $step) {
            if ($step->has_behaviour_var('comment')) {
                return true;
            }
        }
        return false;
    }

    public function get_manual_comment() {
        foreach ($this->get_reverse_step_iterator() as $step) {
            if ($step->has_behaviour_var('comment')) {
                return array($step->get_behaviour_var('comment'),
                        $step->get_behaviour_var('commentformat'));
            }
        }
        return array(null, null);
    }

    public function classify_response() {
        return $this->behaviour->classify_response();
    }

    public static function load_from_records($records, $questionattemptid,
            question_usage_observer $observer, $preferredbehaviour) {
        $record = $records->current();
        while ($record->questionattemptid != $questionattemptid) {
            $record = $records->next();
            if (!$records->valid()) {
                throw new coding_exception("Question attempt $questionattemptid not found in the database.");
            }
            $record = $records->current();
        }

        try {
            $question = question_bank::load_question($record->questionid);
        } catch (Exception $e) {
            // The question must have been deleted somehow. Create a missing
            // question to use in its place.
            $question = question_bank::get_qtype('missingtype')->make_deleted_instance(
                    $record->questionid, $record->maxmark + 0);
        }

        $qa = new question_attempt($question, $record->questionusageid,
                null, $record->maxmark + 0);
        $qa->set_database_id($record->questionattemptid);
        $qa->set_slot($record->slot);
        $qa->variant = $record->variant + 0;
        $qa->minfraction = $record->minfraction + 0;
        $qa->set_flagged($record->flagged);
        $qa->questionsummary = $record->questionsummary;
        $qa->rightanswer = $record->rightanswer;
        $qa->responsesummary = $record->responsesummary;
        $qa->timemodified = $record->timemodified;

        $qa->behaviour = question_engine::make_behaviour(
                $record->behaviour, $qa, $preferredbehaviour);

        $i = 0;
        while ($record && $record->questionattemptid == $questionattemptid && !is_null($record->attemptstepid)) {
            $qa->steps[$i] = question_attempt_step::load_from_records($records, $record->attemptstepid);
            if ($i == 0) {
                $question->apply_attempt_state($qa->steps[0]);
            }
            $i++;
            if ($records->valid()) {
                $record = $records->current();
            } else {
                $record = false;
            }
        }

        $qa->observer = $observer;

        return $qa;
    }
}


class question_attempt_with_restricted_history extends question_attempt {
    protected $baseqa;

    public function __construct(question_attempt $baseqa, $lastseq, $preferredbehaviour) {
        $this->baseqa = $baseqa->get_full_qa();

        if ($lastseq < 0 || $lastseq >= $this->baseqa->get_num_steps()) {
            throw new coding_exception('$lastseq out of range', $lastseq);
        }

        $this->steps = array_slice($this->baseqa->steps, 0, $lastseq + 1);
        $this->observer = new question_usage_null_observer();

        // This should be a straight copy of all the remaining fields.
        $this->id = $this->baseqa->id;
        $this->usageid = $this->baseqa->usageid;
        $this->slot = $this->baseqa->slot;
        $this->question = $this->baseqa->question;
        $this->maxmark = $this->baseqa->maxmark;
        $this->minfraction = $this->baseqa->minfraction;
        $this->questionsummary = $this->baseqa->questionsummary;
        $this->responsesummary = $this->baseqa->responsesummary;
        $this->rightanswer = $this->baseqa->rightanswer;
        $this->flagged = $this->baseqa->flagged;

        // Except behaviour, where we need to create a new one.
        $this->behaviour = question_engine::make_behaviour(
                $this->baseqa->get_behaviour_name(), $this, $preferredbehaviour);
    }

    public function get_full_qa() {
        return $this->baseqa;
    }

    public function get_full_step_iterator() {
        return $this->baseqa->get_step_iterator();
    }

    protected function add_step(question_attempt_step $step) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }
    public function process_action($submitteddata, $timestamp = null, $userid = null) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }
    public function start($preferredbehaviour, $variant, $submitteddata = array(), $timestamp = null, $userid = null) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }

    public function set_database_id($id) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }
    public function set_flagged($flagged) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }
    public function set_slot($slot) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }
    public function set_question_summary($questionsummary) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }
    public function set_usage_id($usageid) {
        coding_exception('Cannot modify a question_attempt_with_restricted_history.');
    }
}


class question_attempt_step_iterator implements Iterator, ArrayAccess {
    protected $qa;
    protected $i;

    public function __construct(question_attempt $qa) {
        $this->qa = $qa;
        $this->rewind();
    }

    public function current() {
        return $this->offsetGet($this->i);
    }
    public function key() {
        return $this->i;
    }
    public function next() {
        ++$this->i;
    }
    public function rewind() {
        $this->i = 0;
    }
    public function valid() {
        return $this->offsetExists($this->i);
    }

    public function offsetExists($i) {
        return $i >= 0 && $i < $this->qa->get_num_steps();
    }
    public function offsetGet($i) {
        return $this->qa->get_step($i);
    }
    public function offsetSet($offset, $value) {
        throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot set.');
    }
    public function offsetUnset($offset) {
        throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot unset.');
    }
}


class question_attempt_reverse_step_iterator extends question_attempt_step_iterator {
    public function next() {
        --$this->i;
    }

    public function rewind() {
        $this->i = $this->qa->get_num_steps() - 1;
    }
}