Proyectos de Subversion Moodle

<?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/>.

/**

 * Library of functions used by the quiz module.

 *

 * This contains functions that are called from within the quiz module only

 * Functions that are also called by core Moodle are in {@link lib.php}

 * This script also loads the code in {@link questionlib.php} which holds

 * the module-indpendent code for handling questions and which in turn

 * initialises all the questiontype classes.

 *

 * @package    mod_quiz

 * @copyright  1999 onwards Martin Dougiamas and others {@link http://moodle.com}

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

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

require_once($CFG->dirroot . '/mod/quiz/lib.php');

require_once($CFG->libdir . '/completionlib.php');

require_once($CFG->libdir . '/filelib.php');

require_once($CFG->libdir . '/questionlib.php');

use core\di;

use core\hook;

use core_question\local\bank\condition;

use mod_quiz\access_manager;

use mod_quiz\event\attempt_submitted;

use mod_quiz\grade_calculator;

use mod_quiz\hook\attempt_state_changed;

use mod_quiz\local\override_manager;

use mod_quiz\question\bank\qbank_helper;

use mod_quiz\question\display_options;

use mod_quiz\quiz_attempt;

use mod_quiz\quiz_settings;

use mod_quiz\structure;

use qbank_previewquestion\question_preview_options;

/**

 * @var int We show the countdown timer if there is less than this amount of time left before the

 * the quiz close date. (1 hour)

 */

define('QUIZ_SHOW_TIME_BEFORE_DEADLINE', '3600');

/**

 * @var int If there are fewer than this many seconds left when the student submits

 * a page of the quiz, then do not take them to the next page of the quiz. Instead

 * close the quiz immediately.

 */

define('QUIZ_MIN_TIME_TO_CONTINUE', '2');

/**

 * @var int We show no image when user selects No image from dropdown menu in quiz settings.

 */

define('QUIZ_SHOWIMAGE_NONE', 0);

/**

 * @var int We show small image when user selects small image from dropdown menu in quiz settings.

 */

define('QUIZ_SHOWIMAGE_SMALL', 1);

/**

 * @var int We show Large image when user selects Large image from dropdown menu in quiz settings.

 */

define('QUIZ_SHOWIMAGE_LARGE', 2);

// Functions related to attempts ///////////////////////////////////////////////

/**

 * Creates an object to represent a new attempt at a quiz

 *

 * Creates an attempt object to represent an attempt at the quiz by the current

 * user starting at the current time. The ->id field is not set. The object is

 * NOT written to the database.

 *

 * @param quiz_settings $quizobj the quiz object to create an attempt for.

 * @param int $attemptnumber the sequence number for the attempt.

 * @param stdClass|false $lastattempt the previous attempt by this user, if any. Only needed

 *         if $attemptnumber > 1 and $quiz->attemptonlast is true.

 * @param int $timenow the time the attempt was started at.

 * @param bool $ispreview whether this new attempt is a preview.

 * @param int|null $userid  the id of the user attempting this quiz.

 *

 * @return stdClass the newly created attempt object.

 */

function quiz_create_attempt(quiz_settings $quizobj, $attemptnumber, $lastattempt, $timenow, $ispreview = false, $userid = null) {

    global $USER;

    if ($userid === null) {

        $userid = $USER->id;

    }

    $quiz = $quizobj->get_quiz();

    if ($quiz->sumgrades < grade_calculator::ALMOST_ZERO && $quiz->grade > grade_calculator::ALMOST_ZERO) {

        throw new moodle_exception('cannotstartgradesmismatch', 'quiz',

                new moodle_url('/mod/quiz/view.php', ['q' => $quiz->id]),

                    ['grade' => quiz_format_grade($quiz, $quiz->grade)]);

    }

    if ($attemptnumber == 1 || !$quiz->attemptonlast) {

        // We are not building on last attempt so create a new attempt.

        $attempt = new stdClass();

        $attempt->quiz = $quiz->id;

        $attempt->userid = $userid;

        $attempt->preview = 0;

        $attempt->layout = '';

    } else {

        // Build on last attempt.

        if (empty($lastattempt)) {

            throw new \moodle_exception('cannotfindprevattempt', 'quiz');

        }

        $attempt = $lastattempt;

    }

    $attempt->attempt = $attemptnumber;

    $attempt->timefinish = 0;

    $attempt->timemodified = $timenow;

    $attempt->timemodifiedoffline = 0;

    $attempt->currentpage = 0;

    $attempt->sumgrades = null;

    $attempt->gradednotificationsenttime = null;

    $attempt->timecheckstate = null;

    // If this is a preview, mark it as such.

    if ($ispreview) {

        $attempt->preview = 1;

    }

    return $attempt;

}

/**

 * Start a normal, new, quiz attempt.

 *

 * @param quiz_settings $quizobj        the quiz object to start an attempt for.

 * @param question_usage_by_activity $quba

 * @param stdClass    $attempt

 * @param integer   $attemptnumber      starting from 1

 * @param integer   $timenow            the attempt start time

 * @param array     $questionids        slot number => question id. Used for random questions, to force the choice

 *                                      of a particular actual question. Intended for testing purposes only.

 * @param array     $forcedvariantsbyslot slot number => variant. Used for questions with variants,

 *                                        to force the choice of a particular variant. Intended for testing

 *                                        purposes only.

 * @return stdClass   modified attempt object

 */

function quiz_start_new_attempt($quizobj, $quba, $attempt, $attemptnumber, $timenow,

                                $questionids = [], $forcedvariantsbyslot = []) {

    // Usages for this user's previous quiz attempts.

    $qubaids = new \mod_quiz\question\qubaids_for_users_attempts(

            $quizobj->get_quizid(), $attempt->userid);

    // Partially load all the questions in this quiz.

    $quizobj->preload_questions();

    // First load all the non-random questions.

    $randomfound = false;

    $slot = 0;

    $questions = [];

    $maxmark = [];

    $page = [];

    foreach ($quizobj->get_questions(null, false) as $questiondata) {

        $slot += 1;

        $maxmark[$slot] = $questiondata->maxmark;

        $page[$slot] = $questiondata->page;

        if ($questiondata->status == \core_question\local\bank\question_version_status::QUESTION_STATUS_DRAFT) {

            throw new moodle_exception('questiondraftonly', 'mod_quiz', '', $questiondata->name);

        }

        if ($questiondata->qtype == 'random') {

            $randomfound = true;

            continue;

        }

        $questions[$slot] = question_bank::load_question($questiondata->questionid, $quizobj->get_quiz()->shuffleanswers);

    }

    // Then find a question to go in place of each random question.

    if ($randomfound) {

        $slot = 0;

        $usedquestionids = [];

        foreach ($questions as $question) {

            if ($question->id && isset($usedquestions[$question->id])) {

                $usedquestionids[$question->id] += 1;

            } else {

                $usedquestionids[$question->id] = 1;

            }

        }

        $randomloader = new \core_question\local\bank\random_question_loader($qubaids, $usedquestionids);

        foreach ($quizobj->get_questions(null, false) as $questiondata) {

            $slot += 1;

            if ($questiondata->qtype != 'random') {

                continue;

            }

            $tagids = qbank_helper::get_tag_ids_for_slot($questiondata);

            // Deal with fixed random choices for testing.

            if (isset($questionids[$quba->next_slot_number()])) {

                $filtercondition = $questiondata->filtercondition;

                $filters = $filtercondition['filter'] ?? [];

                if ($randomloader->is_filtered_question_available($filters, $questionids[$quba->next_slot_number()])) {

                    $questions[$slot] = question_bank::load_question(

                            $questionids[$quba->next_slot_number()], $quizobj->get_quiz()->shuffleanswers);

                    continue;

                } else {

                    throw new coding_exception('Forced question id not available.');

                }

            }

            // Normal case, pick one at random.

            $filtercondition = $questiondata->filtercondition;

            $filters = $filtercondition['filter'] ?? [];

            $questionid = $randomloader->get_next_filtered_question_id($filters);

            if ($questionid === null) {

                throw new moodle_exception('notenoughrandomquestions', 'quiz',

                                           $quizobj->view_url(), $questiondata);

            }

            $questions[$slot] = question_bank::load_question($questionid,

                    $quizobj->get_quiz()->shuffleanswers);

        }

    }

    // Finally add them all to the usage.

    ksort($questions);

    foreach ($questions as $slot => $question) {

        $newslot = $quba->add_question($question, $maxmark[$slot]);

        if ($newslot != $slot) {

            throw new coding_exception('Slot numbers have got confused.');

        }

    }

    // Start all the questions.

    $variantstrategy = new core_question\engine\variants\least_used_strategy($quba, $qubaids);

    if (!empty($forcedvariantsbyslot)) {

        $forcedvariantsbyseed = question_variant_forced_choices_selection_strategy::prepare_forced_choices_array(

            $forcedvariantsbyslot, $quba);

        $variantstrategy = new question_variant_forced_choices_selection_strategy(

            $forcedvariantsbyseed, $variantstrategy);

    }

    $quba->start_all_questions($variantstrategy, question_attempt_step::TIMECREATED_ON_FIRST_RENDER, $attempt->userid);

    // Work out the attempt layout.

    $sections = $quizobj->get_sections();

    foreach ($sections as $i => $section) {

        if (isset($sections[$i + 1])) {

            $sections[$i]->lastslot = $sections[$i + 1]->firstslot - 1;

        } else {

            $sections[$i]->lastslot = count($questions);

        }

    }

    $layout = [];

    foreach ($sections as $section) {

        if ($section->shufflequestions) {

            $questionsinthissection = [];

            for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {

                $questionsinthissection[] = $slot;

            }

            shuffle($questionsinthissection);

            $questionsonthispage = 0;

            foreach ($questionsinthissection as $slot) {

                if ($questionsonthispage && $questionsonthispage == $quizobj->get_quiz()->questionsperpage) {

                    $layout[] = 0;

                    $questionsonthispage = 0;

                }

                $layout[] = $slot;

                $questionsonthispage += 1;

            }

        } else {

            $currentpage = $page[$section->firstslot];

            for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {

                if ($currentpage !== null && $page[$slot] != $currentpage) {

                    $layout[] = 0;

                }

                $layout[] = $slot;

                $currentpage = $page[$slot];

            }

        }

        // Each section ends with a page break.

        $layout[] = 0;

    }

    $attempt->layout = implode(',', $layout);

    return $attempt;

}

/**

 * Start a subsequent new attempt, in each attempt builds on last mode.

 *

 * @param question_usage_by_activity    $quba         this question usage

 * @param stdClass                        $attempt      this attempt

 * @param stdClass                        $lastattempt  last attempt

 * @return stdClass                       modified attempt object

 *

 */

function quiz_start_attempt_built_on_last($quba, $attempt, $lastattempt) {

    $oldquba = question_engine::load_questions_usage_by_activity($lastattempt->uniqueid);

    $oldnumberstonew = [];

    foreach ($oldquba->get_attempt_iterator() as $oldslot => $oldqa) {

        $question = $oldqa->get_question(false);

        if ($question->status == \core_question\local\bank\question_version_status::QUESTION_STATUS_DRAFT) {

            throw new moodle_exception('questiondraftonly', 'mod_quiz', '', $question->name);

        }

        $newslot = $quba->add_question($question, $oldqa->get_max_mark());

        $quba->start_question_based_on($newslot, $oldqa);

        $oldnumberstonew[$oldslot] = $newslot;

    }

    // Update attempt layout.

    $newlayout = [];

    foreach (explode(',', $lastattempt->layout) as $oldslot) {

        if ($oldslot != 0) {

            $newlayout[] = $oldnumberstonew[$oldslot];

        } else {

            $newlayout[] = 0;

        }

    }

    $attempt->layout = implode(',', $newlayout);

    return $attempt;

}

/**

 * Create or update the quiz attempt record, and the question usage.

 *

 * If the attempt already exists in the database with the NOT_STARTED state, it will be transitioned

 * to IN_PROGRESS and the timestart updated. If it does not already exist, a new record will be created

 * already in the IN_PROGRESS state.

 *

 * @param quiz_settings $quizobj

 * @param question_usage_by_activity $quba

 * @param stdClass                     $attempt

 * @param ?int $timenow The time to use for the attempt's timestart property. Defaults to time().

 * @return stdClass                    attempt object with uniqueid and id set.

 */

function quiz_attempt_save_started(

    quiz_settings $quizobj,

    question_usage_by_activity $quba,

    \stdClass $attempt,

    ?int $timenow = null,

): stdClass {

    global $DB;

    $attempt->timestart = $timenow ?? time();

    $timeclose = $quizobj->get_access_manager($attempt->timestart)->get_end_time($attempt);

    if ($timeclose === false || $attempt->preview) {

        $attempt->timecheckstate = null;

    } else {

        $attempt->timecheckstate = $timeclose;

    }

    $originalattempt = null;

    if (isset($attempt->id) && $attempt->state === quiz_attempt::NOT_STARTED) {

        $originalattempt = clone $attempt;

        // In case questions have been edited since attempts were pre-created, update questions now.

        quiz_attempt::create($attempt->id)->update_questions_to_new_version_if_changed();

        // Update the attempt's state.

        $attempt->state = quiz_attempt::IN_PROGRESS;

        $DB->update_record('quiz_attempts', $attempt);

    } else {

        // Save the attempt in the database.

        question_engine::save_questions_usage_by_activity($quba);

        $attempt->uniqueid = $quba->get_id();

        $attempt->state = quiz_attempt::IN_PROGRESS;

        $attempt->id = $DB->insert_record('quiz_attempts', $attempt);

    }

    // Params used by the events below.

    $params = [

        'objectid' => $attempt->id,

        'relateduserid' => $attempt->userid,

        'courseid' => $quizobj->get_courseid(),

        'context' => $quizobj->get_context()

    ];

    // Decide which event we are using.

    if ($attempt->preview) {

        $params['other'] = [

            'quizid' => $quizobj->get_quizid()

        ];

        $event = \mod_quiz\event\attempt_preview_started::create($params);

    } else {

        $event = \mod_quiz\event\attempt_started::create($params);

    }

    // Trigger the event.

    $event->add_record_snapshot('quiz', $quizobj->get_quiz());

    $event->add_record_snapshot('quiz_attempts', $attempt);

    $event->trigger();

    di::get(hook\manager::class)->dispatch(new attempt_state_changed($originalattempt, $attempt));

    return $attempt;

}

/**

 * Create the quiz attempt record, and the question usage.

 *

 * This saves an attempt in the NOT_STARTED state, and is designed for use when pre-creating attempts

 * ahead of the quiz start time to spread out the processing load.

 *

 * @param question_usage_by_activity $quba

 * @param stdClass $attempt

 * @return stdClass attempt object with uniqueid and id set.

 */

function quiz_attempt_save_not_started(question_usage_by_activity $quba, stdClass $attempt): stdClass {

    global $DB;

    // Save the attempt in the database.

    question_engine::save_questions_usage_by_activity($quba);

    $attempt->uniqueid = $quba->get_id();

    $attempt->state = quiz_attempt::NOT_STARTED;

    $attempt->id = $DB->insert_record('quiz_attempts', $attempt);

    di::get(hook\manager::class)->dispatch(new attempt_state_changed(null, $attempt));

    return $attempt;

}

/**

 * Returns an unfinished attempt (if there is one) for the given

 * user on the given quiz. This function does not return preview attempts.

 *

 * @param int $quizid the id of the quiz.

 * @param int $userid the id of the user.

 *

 * @return mixed the unfinished attempt if there is one, false if not.

 */

function quiz_get_user_attempt_unfinished($quizid, $userid) {

    $attempts = quiz_get_user_attempts($quizid, $userid, 'unfinished', true);

    if ($attempts) {

        return array_shift($attempts);

    } else {

        return false;

    }

}

/**

 * Delete a quiz attempt.

 * @param mixed $attempt an integer attempt id or an attempt object

 *      (row of the quiz_attempts table).

 * @param stdClass $quiz the quiz object.

 */

function quiz_delete_attempt($attempt, $quiz) {

    global $DB;

    if (is_numeric($attempt)) {

        if (!$attempt = $DB->get_record('quiz_attempts', ['id' => $attempt])) {

            return;

        }

    }

    if ($attempt->quiz != $quiz->id) {

        debugging("Trying to delete attempt $attempt->id which belongs to quiz $attempt->quiz " .

                "but was passed quiz $quiz->id.");

        return;

    }

    if (!isset($quiz->cmid)) {

        $cm = get_coursemodule_from_instance('quiz', $quiz->id, $quiz->course);

        $quiz->cmid = $cm->id;

    }

    question_engine::delete_questions_usage_by_activity($attempt->uniqueid);

    $DB->delete_records('quiz_attempts', ['id' => $attempt->id]);

    // Log the deletion of the attempt if not a preview.

    if (!$attempt->preview) {

        $params = [

            'objectid' => $attempt->id,

            'relateduserid' => $attempt->userid,

            'context' => context_module::instance($quiz->cmid),

            'other' => [

                'quizid' => $quiz->id

            ]

        ];

        $event = \mod_quiz\event\attempt_deleted::create($params);

        $event->add_record_snapshot('quiz_attempts', $attempt);

        $event->trigger();

        // This class callback is deprecated, and will be removed in Moodle 4.8 (MDL-80327).

        // Use the attempt_state_changed hook instead.

        $callbackclasses = \core_component::get_plugin_list_with_class('quiz', 'quiz_attempt_deleted');

        foreach ($callbackclasses as $callbackclass) {

            component_class_callback($callbackclass, 'callback', [$quiz->id], null, true);

        }

        di::get(hook\manager::class)->dispatch(new attempt_state_changed($attempt, null));

    }

    // Search quiz_attempts for other instances by this user.

    // If none, then delete record for this quiz, this user from quiz_grades

    // else recalculate best grade.

    $userid = $attempt->userid;

    $gradecalculator = quiz_settings::create($quiz->id)->get_grade_calculator();

    if (!$DB->record_exists('quiz_attempts', ['userid' => $userid, 'quiz' => $quiz->id])) {

        $DB->delete_records('quiz_grades', ['userid' => $userid, 'quiz' => $quiz->id]);

    } else {

        $gradecalculator->recompute_final_grade($userid);

    }

    quiz_update_grades($quiz, $userid);

}

/**

 * Delete all the preview attempts at a quiz, or possibly all the attempts belonging

 * to one user.

 * @param stdClass $quiz the quiz object.

 * @param int $userid (optional) if given, only delete the previews belonging to this user.

 */

function quiz_delete_previews($quiz, $userid = null) {

    global $DB;

    $conditions = ['quiz' => $quiz->id, 'preview' => 1];

    if (!empty($userid)) {

        $conditions['userid'] = $userid;

    }

    $previewattempts = $DB->get_records('quiz_attempts', $conditions);

    foreach ($previewattempts as $attempt) {

        quiz_delete_attempt($attempt, $quiz);

    }

}

/**

 * @param int $quizid The quiz id.

 * @return bool whether this quiz has any (non-preview) attempts.

 */

function quiz_has_attempts($quizid) {

    global $DB;

    return $DB->record_exists('quiz_attempts', ['quiz' => $quizid, 'preview' => 0]);

}

// Functions to do with quiz layout and pages //////////////////////////////////

/**

 * Repaginate the questions in a quiz

 * @param int $quizid the id of the quiz to repaginate.

 * @param int $slotsperpage number of items to put on each page. 0 means unlimited.

 */

function quiz_repaginate_questions($quizid, $slotsperpage) {

    global $DB;

    $trans = $DB->start_delegated_transaction();

    $sections = $DB->get_records('quiz_sections', ['quizid' => $quizid], 'firstslot ASC');

    $firstslots = [];

    foreach ($sections as $section) {

        if ((int)$section->firstslot === 1) {

            continue;

        }

        $firstslots[] = $section->firstslot;

    }

    $slots = $DB->get_records('quiz_slots', ['quizid' => $quizid],

            'slot');

    $currentpage = 1;

    $slotsonthispage = 0;

    foreach ($slots as $slot) {

        if (($firstslots && in_array($slot->slot, $firstslots)) ||

            ($slotsonthispage && $slotsonthispage == $slotsperpage)) {

            $currentpage += 1;

            $slotsonthispage = 0;

        }

        if ($slot->page != $currentpage) {

            $DB->set_field('quiz_slots', 'page', $currentpage, ['id' => $slot->id]);

        }

        $slotsonthispage += 1;

    }

    $trans->allow_commit();

    // Log quiz re-paginated event.

    $cm = get_coursemodule_from_instance('quiz', $quizid);

    $event = \mod_quiz\event\quiz_repaginated::create([

        'context' => \context_module::instance($cm->id),

        'objectid' => $quizid,

        'other' => [

            'slotsperpage' => $slotsperpage

        ]

    ]);

    $event->trigger();

}

// Functions to do with quiz grades ////////////////////////////////////////////

// Note a lot of logic related to this is now in the grade_calculator class.

/**

 * Convert the raw grade stored in $attempt into a grade out of the maximum

 * grade for this quiz.

 *

 * @param float $rawgrade the unadjusted grade, fof example $attempt->sumgrades

 * @param stdClass $quiz the quiz object. Only the fields grade, sumgrades and decimalpoints are used.

 * @param bool|string $format whether to format the results for display

 *      or 'question' to format a question grade (different number of decimal places.

 * @return float|string the rescaled grade, or null/the lang string 'notyetgraded'

 *      if the $grade is null.

 */

function quiz_rescale_grade($rawgrade, $quiz, $format = true) {

    if (is_null($rawgrade)) {

        $grade = null;

    } else if ($quiz->sumgrades >= grade_calculator::ALMOST_ZERO) {

        $grade = $rawgrade * $quiz->grade / $quiz->sumgrades;

    } else {

        $grade = 0;

    }

    if ($format === 'question') {

        $grade = quiz_format_question_grade($quiz, $grade);

    } else if ($format) {

        $grade = quiz_format_grade($quiz, $grade);

    }

    return $grade;

}

/**

 * Get the feedback object for this grade on this quiz.

 *

 * @param float $grade a grade on this quiz.

 * @param stdClass $quiz the quiz settings.

 * @return false|stdClass the record object or false if there is not feedback for the given grade

 * @since  Moodle 3.1

 */

function quiz_feedback_record_for_grade($grade, $quiz) {

    global $DB;

    // With CBM etc, it is possible to get -ve grades, which would then not match

    // any feedback. Therefore, we replace -ve grades with 0.

    $grade = max($grade, 0);

    $feedback = $DB->get_record_select('quiz_feedback',

            'quizid = ? AND mingrade <= ? AND ? < maxgrade', [$quiz->id, $grade, $grade]);

    return $feedback;

}

/**

 * Get the feedback text that should be show to a student who

 * got this grade on this quiz. The feedback is processed ready for diplay.

 *

 * @param float $grade a grade on this quiz.

 * @param stdClass $quiz the quiz settings.

 * @param context_module $context the quiz context.

 * @return string the comment that corresponds to this grade (empty string if there is not one.

 */

function quiz_feedback_for_grade($grade, $quiz, $context) {

    if (is_null($grade)) {

        return '';

    }

    $feedback = quiz_feedback_record_for_grade($grade, $quiz);

    if (empty($feedback->feedbacktext)) {

        return '';

    }

    // Clean the text, ready for display.

    $formatoptions = new stdClass();

    $formatoptions->noclean = true;

    $feedbacktext = file_rewrite_pluginfile_urls($feedback->feedbacktext, 'pluginfile.php',

            $context->id, 'mod_quiz', 'feedback', $feedback->id);

    $feedbacktext = format_text($feedbacktext, $feedback->feedbacktextformat, $formatoptions);

    return $feedbacktext;

}

/**

 * @param stdClass $quiz the quiz database row.

 * @return bool Whether this quiz has any non-blank feedback text.

 */

function quiz_has_feedback($quiz) {

    global $DB;

    static $cache = [];

    if (!array_key_exists($quiz->id, $cache)) {

        $cache[$quiz->id] = quiz_has_grades($quiz) &&

                $DB->record_exists_select('quiz_feedback', "quizid = ? AND " .

                    $DB->sql_isnotempty('quiz_feedback', 'feedbacktext', false, true),

                [$quiz->id]);

    }

    return $cache[$quiz->id];

}

/**

 * Return summary of the number of settings override that exist.

 *

 * To get a nice display of this, see the quiz_override_summary_links()

 * quiz renderer method.

 *

 * @param stdClass $quiz the quiz settings. Only $quiz->id is used at the moment.

 * @param cm_info|stdClass $cm the cm object. Only $cm->course, $cm->groupmode and

 *      $cm->groupingid fields are used at the moment.

 * @param int $currentgroup if there is a concept of current group where this method is being called

 *      (e.g. a report) pass it in here. Default 0 which means no current group.

 * @return array like 'group' => 3, 'user' => 12] where 3 is the number of group overrides,

 *      and 12 is the number of user ones.

 */

function quiz_override_summary(stdClass $quiz, cm_info|stdClass $cm, int $currentgroup = 0): array {

    global $DB;

    if ($currentgroup) {

        // Currently only interested in one group.

        $groupcount = $DB->count_records('quiz_overrides', ['quiz' => $quiz->id, 'groupid' => $currentgroup]);

        $usercount = $DB->count_records_sql("

                SELECT COUNT(1)

                  FROM {quiz_overrides} o

                  JOIN {groups_members} gm ON o.userid = gm.userid

                 WHERE o.quiz = ?

                   AND gm.groupid = ?

                    ", [$quiz->id, $currentgroup]);

        return ['group' => $groupcount, 'user' => $usercount, 'mode' => 'onegroup'];

    }

    $quizgroupmode = groups_get_activity_groupmode($cm);

    $accessallgroups = ($quizgroupmode == NOGROUPS) ||

            has_capability('moodle/site:accessallgroups', context_module::instance($cm->id));

    if ($accessallgroups) {

        // User can see all groups.

        $groupcount = $DB->count_records_select('quiz_overrides',

                'quiz = ? AND groupid IS NOT NULL', [$quiz->id]);

        $usercount = $DB->count_records_select('quiz_overrides',

                'quiz = ? AND userid IS NOT NULL', [$quiz->id]);

        return ['group' => $groupcount, 'user' => $usercount, 'mode' => 'allgroups'];

    } else {

        // User can only see groups they are in.

        $groups = groups_get_activity_allowed_groups($cm);

        if (!$groups) {

            return ['group' => 0, 'user' => 0, 'mode' => 'somegroups'];

        }

        list($groupidtest, $params) = $DB->get_in_or_equal(array_keys($groups));

        $params[] = $quiz->id;

        $groupcount = $DB->count_records_select('quiz_overrides',

                "groupid $groupidtest AND quiz = ?", $params);

        $usercount = $DB->count_records_sql("

                SELECT COUNT(1)

                  FROM {quiz_overrides} o

                  JOIN {groups_members} gm ON o.userid = gm.userid

                 WHERE gm.groupid $groupidtest

                   AND o.quiz = ?

               ", $params);

        return ['group' => $groupcount, 'user' => $usercount, 'mode' => 'somegroups'];

    }

}

/**

 * Efficiently update check state time on all open attempts

 *

 * @param array $conditions optional restrictions on which attempts to update

 *                    Allowed conditions:

 *                      courseid => (array|int) attempts in given course(s)

 *                      userid   => (array|int) attempts for given user(s)

 *                      quizid   => (array|int) attempts in given quiz(s)

 *                      groupid  => (array|int) quizzes with some override for given group(s)

 *

 */

function quiz_update_open_attempts(array $conditions) {

    global $DB;

    foreach ($conditions as &$value) {

        if (!is_array($value)) {

            $value = [$value];

        }

    }

    $params = [];

    $wheres = ["quiza.state IN ('inprogress', 'overdue')"];

    $iwheres = ["iquiza.state IN ('inprogress', 'overdue')"];

    if (isset($conditions['courseid'])) {

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'cid');

        $params = array_merge($params, $inparams);

        $wheres[] = "quiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'icid');

        $params = array_merge($params, $inparams);

        $iwheres[] = "iquiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";

    }

    if (isset($conditions['userid'])) {

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'uid');

        $params = array_merge($params, $inparams);

        $wheres[] = "quiza.userid $incond";

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'iuid');

        $params = array_merge($params, $inparams);

        $iwheres[] = "iquiza.userid $incond";

    }

    if (isset($conditions['quizid'])) {

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'qid');

        $params = array_merge($params, $inparams);

        $wheres[] = "quiza.quiz $incond";

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'iqid');

        $params = array_merge($params, $inparams);

        $iwheres[] = "iquiza.quiz $incond";

    }

    if (isset($conditions['groupid'])) {

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'gid');

        $params = array_merge($params, $inparams);

        $wheres[] = "quiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";

        list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'igid');

        $params = array_merge($params, $inparams);

        $iwheres[] = "iquiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";

    }

    // SQL to compute timeclose and timelimit for each attempt:

    $quizausersql = quiz_get_attempt_usertime_sql(

            implode("\n                AND ", $iwheres));

    // SQL to compute the new timecheckstate

    $timecheckstatesql = "

          CASE WHEN quizauser.usertimelimit = 0 AND quizauser.usertimeclose = 0 THEN NULL

               WHEN quizauser.usertimelimit = 0 THEN quizauser.usertimeclose

               WHEN quizauser.usertimeclose = 0 THEN quiza.timestart + quizauser.usertimelimit

               WHEN quiza.timestart + quizauser.usertimelimit < quizauser.usertimeclose THEN quiza.timestart + quizauser.usertimelimit

               ELSE quizauser.usertimeclose END +

          CASE WHEN quiza.state = 'overdue' THEN quiz.graceperiod ELSE 0 END";

    // SQL to select which attempts to process

    $attemptselect = implode("\n                         AND ", $wheres);

   /*

    * Each database handles updates with inner joins differently:

    *  - mysql does not allow a FROM clause

    *  - postgres and mssql allow FROM but handle table aliases differently

    *

    * Different code for each database.

    */

    $dbfamily = $DB->get_dbfamily();

    if ($dbfamily == 'mysql') {

        $updatesql = "UPDATE {quiz_attempts} quiza

                        JOIN {quiz} quiz ON quiz.id = quiza.quiz

                        JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id

                         SET quiza.timecheckstate = $timecheckstatesql

                       WHERE $attemptselect";

    } else if ($dbfamily == 'postgres') {

        $updatesql = "UPDATE {quiz_attempts} quiza

                         SET timecheckstate = $timecheckstatesql

                        FROM {quiz} quiz, ( $quizausersql ) quizauser

                       WHERE quiz.id = quiza.quiz

                         AND quizauser.id = quiza.id

                         AND $attemptselect";

    } else if ($dbfamily == 'mssql') {

        $updatesql = "UPDATE quiza

                         SET timecheckstate = $timecheckstatesql

                        FROM {quiz_attempts} quiza

                        JOIN {quiz} quiz ON quiz.id = quiza.quiz

                        JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id

                       WHERE $attemptselect";

    } else {

        throw new \core\exception\coding_exception("Unsupported database family: {$dbfamily}");

    }

    $DB->execute($updatesql, $params);

}

/**

 * Returns SQL to compute timeclose and timelimit for every attempt, taking into account user and group overrides.

 * The query used herein is very similar to the one in function quiz_get_user_timeclose, so, in case you

 * would change either one of them, make sure to apply your changes to both.

 *

 * @param string $redundantwhereclauses extra where clauses to add to the subquery

 *      for performance. These can use the table alias iquiza for the quiz attempts table.

 * @return string SQL select with columns attempt.id, usertimeclose, usertimelimit.

 */

function quiz_get_attempt_usertime_sql($redundantwhereclauses = '') {

    if ($redundantwhereclauses) {

        $redundantwhereclauses = 'WHERE ' . $redundantwhereclauses;

    }

    // The multiple qgo JOINS are necessary because we want timeclose/timelimit = 0 (unlimited) to supercede

    // any other group override

    $quizausersql = "

          SELECT iquiza.id,

           COALESCE(MAX(quo.timeclose), MAX(qgo1.timeclose), MAX(qgo2.timeclose), iquiz.timeclose) AS usertimeclose,

           COALESCE(MAX(quo.timelimit), MAX(qgo3.timelimit), MAX(qgo4.timelimit), iquiz.timelimit) AS usertimelimit

           FROM {quiz_attempts} iquiza

           JOIN {quiz} iquiz ON iquiz.id = iquiza.quiz

      LEFT JOIN {quiz_overrides} quo ON quo.quiz = iquiza.quiz AND quo.userid = iquiza.userid

      LEFT JOIN {groups_members} gm ON gm.userid = iquiza.userid

      LEFT JOIN {quiz_overrides} qgo1 ON qgo1.quiz = iquiza.quiz AND qgo1.groupid = gm.groupid AND qgo1.timeclose = 0

      LEFT JOIN {quiz_overrides} qgo2 ON qgo2.quiz = iquiza.quiz AND qgo2.groupid = gm.groupid AND qgo2.timeclose > 0

      LEFT JOIN {quiz_overrides} qgo3 ON qgo3.quiz = iquiza.quiz AND qgo3.groupid = gm.groupid AND qgo3.timelimit = 0

      LEFT JOIN {quiz_overrides} qgo4 ON qgo4.quiz = iquiza.quiz AND qgo4.groupid = gm.groupid AND qgo4.timelimit > 0

          $redundantwhereclauses

       GROUP BY iquiza.id, iquiz.id, iquiz.timeclose, iquiz.timelimit";

    return $quizausersql;

}

/**

 * @return array int => lang string the options for calculating the quiz grade

 *      from the individual attempt grades.

 */

function quiz_get_grading_options() {

    return [

        QUIZ_GRADEHIGHEST => get_string('gradehighest', 'quiz'),

        QUIZ_GRADEAVERAGE => get_string('gradeaverage', 'quiz'),

        QUIZ_ATTEMPTFIRST => get_string('attemptfirst', 'quiz'),

        QUIZ_ATTEMPTLAST  => get_string('attemptlast', 'quiz')

    ];

}

/**

 * @param int $option one of the values QUIZ_GRADEHIGHEST, QUIZ_GRADEAVERAGE,

 *      QUIZ_ATTEMPTFIRST or QUIZ_ATTEMPTLAST.

 * @return the lang string for that option.

 */

function quiz_get_grading_option_name($option) {

    $strings = quiz_get_grading_options();

    return $strings[$option];

}

/**

 * @return array string => lang string the options for handling overdue quiz

 *      attempts.

 */

function quiz_get_overdue_handling_options() {

    return [

        'autosubmit'  => get_string('overduehandlingautosubmit', 'quiz'),

        'graceperiod' => get_string('overduehandlinggraceperiod', 'quiz'),

        'autoabandon' => get_string('overduehandlingautoabandon', 'quiz'),

    ];

}

/**

 * Get the choices for what size user picture to show.

 * @return array string => lang string the options for whether to display the user's picture.

 */

function quiz_get_user_image_options() {

    return [

        QUIZ_SHOWIMAGE_NONE  => get_string('shownoimage', 'quiz'),

        QUIZ_SHOWIMAGE_SMALL => get_string('showsmallimage', 'quiz'),

        QUIZ_SHOWIMAGE_LARGE => get_string('showlargeimage', 'quiz'),

    ];

}

/**

 * Return an user's timeclose for all quizzes in a course, hereby taking into account group and user overrides.

 *

 * @param int $courseid the course id.

 * @return stdClass An object with of all quizids and close unixdates in this course, taking into account the most lenient

 * overrides, if existing and 0 if no close date is set.

 */

function quiz_get_user_timeclose($courseid) {

    global $DB, $USER;

    // For teacher and manager/admins return timeclose.

    if (has_capability('moodle/course:update', context_course::instance($courseid))) {

        $sql = "SELECT quiz.id, quiz.timeclose AS usertimeclose

                  FROM {quiz} quiz

                 WHERE quiz.course = :courseid";

        $results = $DB->get_records_sql($sql, ['courseid' => $courseid]);

        return $results;

    }

    $sql = "SELECT q.id,

  COALESCE(v.userclose, v.groupclose, q.timeclose, 0) AS usertimeclose

  FROM (

      SELECT quiz.id as quizid,

             MAX(quo.timeclose) AS userclose, MAX(qgo.timeclose) AS groupclose

       FROM {quiz} quiz

  LEFT JOIN {quiz_overrides} quo on quiz.id = quo.quiz AND quo.userid = :userid

  LEFT JOIN {groups_members} gm ON gm.userid = :useringroupid

  LEFT JOIN {quiz_overrides} qgo on quiz.id = qgo.quiz AND qgo.groupid = gm.groupid

      WHERE quiz.course = :courseid

   GROUP BY quiz.id) v

       JOIN {quiz} q ON q.id = v.quizid";

    $results = $DB->get_records_sql($sql, ['userid' => $USER->id, 'useringroupid' => $USER->id, 'courseid' => $courseid]);

    return $results;

}

/**

 * Get the choices to offer for the 'Questions per page' option.

 * @return array int => string.