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

namespace mod_quiz;

use coding_exception;
use core\di;
use core\hook;
use core_component;
use mod_quiz\event\quiz_grade_updated;
use mod_quiz\hook\structure_modified;
use mod_quiz\output\grades\grade_out_of;
use qubaid_condition;
use qubaid_list;
use question_engine_data_mapper;
use question_usage_by_activity;
use stdClass;

/**
 * This class contains all the logic for computing the grade of a quiz.
 *
 * There are two sorts of calculation which need to be done. For a single
 * attempt, we need to compute the total attempt score from score for each question.
 * And for a quiz user, we need to compute the final grade from all the separate attempt grades.
 *
 * @package   mod_quiz
 * @copyright 2023 The Open University
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class grade_calculator {

    /** @var float a number that is effectively zero. Used to avoid division-by-zero or underflow problems. */
    const ALMOST_ZERO = 0.000005;

    /** @var quiz_settings the quiz for which this instance computes grades. */
    protected $quizobj;

    /**
     * @var stdClass[]|null quiz_grade_items for this quiz indexed by id, sorted by sortorder, with a maxmark field added.
     *
     * Lazy-loaded when needed. See {@see ensure_grade_items_loaded()}.
     */
    protected ?array $gradeitems = null;

    /**
     * @var ?stdClass[]|null quiz_slot for this quiz. Only ->slot and ->quizgradeitemid fields are used.
     *
     * This is either set by another class that already has the data, using {@see set_slots()}
     * or it is lazy-loaded when needed. See {@see ensure_slots_loaded()}.
     */
    protected ?array $slots = null;

    /**
     * Constructor. Recommended way to get an instance is $quizobj->get_grade_calculator();
     *
     * @param quiz_settings $quizobj
     */
    protected function __construct(quiz_settings $quizobj) {
        $this->quizobj = $quizobj;
    }

    /**
     * Factory. The recommended way to get an instance is $quizobj->get_grade_calculator();
     *
     * @param quiz_settings $quizobj settings of a quiz.
     * @return grade_calculator instance of this class for the given quiz.
     */
    public static function create(quiz_settings $quizobj): grade_calculator {
        return new self($quizobj);
    }

    /**
     * Update the sumgrades field of the quiz.
     *
     * This needs to be called whenever the grading structure of the quiz is changed.
     * For example if a question is added or removed, or a question weight is changed.
     *
     * You should call {@see quiz_delete_previews()} before you call this function.
     */
    public function recompute_quiz_sumgrades(): void {
        global $DB;
        $quiz = $this->quizobj->get_quiz();

        // Update sumgrades in the database.
        $DB->execute("
                UPDATE {quiz}
                   SET sumgrades = COALESCE((
                        SELECT SUM(maxmark)
                          FROM {quiz_slots}
                         WHERE quizid = {quiz}.id
                       ), 0)
                 WHERE id = ?
             ", [$quiz->id]);

        // Update the value in memory.
        $quiz->sumgrades = $DB->get_field('quiz', 'sumgrades', ['id' => $quiz->id]);

        if ($quiz->sumgrades < self::ALMOST_ZERO && quiz_has_attempts($quiz->id)) {
            // If the quiz has been attempted, and the sumgrades has been
            // set to 0, then we must also set the maximum possible grade to 0, or
            // we will get a divide by zero error.
            self::update_quiz_maximum_grade(0);
        }

        // This class callback is deprecated, and will be removed in Moodle 4.8 (MDL-80327).
        // Use the structure_modified hook instead.
        $callbackclasses = core_component::get_plugin_list_with_class('quiz', 'quiz_structure_modified');
        foreach ($callbackclasses as $callbackclass) {
            component_class_callback($callbackclass, 'callback', [$quiz->id], null, true);
        }

        di::get(hook\manager::class)->dispatch(new structure_modified($this->quizobj->get_structure()));
    }

    /**
     * Update the sumgrades field of attempts at this quiz.
     */
    public function recompute_all_attempt_sumgrades(): void {
        global $DB;
        $dm = new question_engine_data_mapper();
        $timenow = time();

        $DB->execute("
                UPDATE {quiz_attempts}
                   SET timemodified = :timenow,
                       sumgrades = (
                           {$dm->sum_usage_marks_subquery('uniqueid')}
                       )
                 WHERE quiz = :quizid AND state = :finishedstate
            ", [
                'timenow' => $timenow,
                'quizid' => $this->quizobj->get_quizid(),
                'finishedstate' => quiz_attempt::FINISHED
            ]);
    }

    /**
     * Update the final grade at this quiz for a particular student.
     *
     * That is, given the quiz settings, and all the attempts this user has made,
     * compute their final grade for the quiz, as shown in the gradebook.
     *
     * The $attempts parameter is for efficiency. If you already have the data for
     * all this user's attempts loaded (for example from {@see quiz_get_user_attempts()}
     * or because you are looping through a large recordset fetched in one efficient query,
     * then you can pass that data here to save DB queries.
     *
     * @param int|null $userid The userid to calculate the grade for. Defaults to the current user.
     * @param array $attempts if you already have this user's attempt records loaded, pass them here to save queries.
     */
    public function recompute_final_grade(?int $userid = null, array $attempts = []): void {
        global $DB, $USER;
        $quiz = $this->quizobj->get_quiz();

        if (empty($userid)) {
            $userid = $USER->id;
        }

        if (!$attempts) {
            // Get all the attempts made by the user.
            $attempts = quiz_get_user_attempts($quiz->id, $userid);
        }

        // Calculate the best grade.
        $bestgrade = $this->compute_final_grade_from_attempts($attempts);
        $bestgrade = quiz_rescale_grade($bestgrade, $quiz, false);

        // Save the best grade in the database.
        if (is_null($bestgrade)) {
            $DB->delete_records('quiz_grades', ['quiz' => $quiz->id, 'userid' => $userid]);

        } else if ($grade = $DB->get_record('quiz_grades',
                ['quiz' => $quiz->id, 'userid' => $userid])) {
            $grade->grade = $bestgrade;
            $grade->timemodified = time();
            $DB->update_record('quiz_grades', $grade);

        } else {
            $grade = new stdClass();
            $grade->quiz = $quiz->id;
            $grade->userid = $userid;
            $grade->grade = $bestgrade;
            $grade->timemodified = time();
            $DB->insert_record('quiz_grades', $grade);
        }

        quiz_update_grades($quiz, $userid);
    }

    /**
     * Calculate the overall grade for a quiz given a number of attempts by a particular user.
     *
     * @param array $attempts an array of all the user's attempts at this quiz in order.
     * @return float|null the overall grade, or null if the user does not have a grade.
     */
    protected function compute_final_grade_from_attempts(array $attempts): ?float {

        $grademethod = $this->quizobj->get_quiz()->grademethod;
        switch ($grademethod) {

            case QUIZ_ATTEMPTFIRST:
                $firstattempt = reset($attempts);
                return $firstattempt->sumgrades;

            case QUIZ_ATTEMPTLAST:
                $lastattempt = end($attempts);
                return $lastattempt->sumgrades;

            case QUIZ_GRADEAVERAGE:
                $sum = 0;
                $count = 0;
                foreach ($attempts as $attempt) {
                    if (!is_null($attempt->sumgrades)) {
                        $sum += $attempt->sumgrades;
                        $count++;
                    }
                }
                if ($count == 0) {
                    return null;
                }
                return $sum / $count;

            case QUIZ_GRADEHIGHEST:
                $max = null;
                foreach ($attempts as $attempt) {
                    if ($attempt->sumgrades > $max) {
                        $max = $attempt->sumgrades;
                    }
                }
                return $max;

            default:
                throw new coding_exception('Unrecognised grading method ' . $grademethod);
        }
    }

    /**
     * Update the final grade at this quiz for all students.
     *
     * This function is equivalent to calling {@see recompute_final_grade()} for all
     * users who have attempted the quiz, but is much more efficient.
     */
    public function recompute_all_final_grades(): void {
        global $DB;
        $quiz = $this->quizobj->get_quiz();

        // If the quiz does not contain any graded questions, then there is nothing to do.
        if (!$quiz->sumgrades) {
            return;
        }

        $param = ['iquizid' => $quiz->id, 'istatefinished' => quiz_attempt::FINISHED];
        $firstlastattemptjoin = "JOIN (
                SELECT
                    iquiza.userid,
                    MIN(attempt) AS firstattempt,
                    MAX(attempt) AS lastattempt

                FROM {quiz_attempts} iquiza

                WHERE
                    iquiza.state = :istatefinished AND
                    iquiza.preview = 0 AND
                    iquiza.quiz = :iquizid

                GROUP BY iquiza.userid
            ) first_last_attempts ON first_last_attempts.userid = quiza.userid";

        switch ($quiz->grademethod) {
            case QUIZ_ATTEMPTFIRST:
                // Because of the where clause, there will only be one row, but we
                // must still use an aggregate function.
                $select = 'MAX(quiza.sumgrades)';
                $join = $firstlastattemptjoin;
                $where = 'quiza.attempt = first_last_attempts.firstattempt AND';
                break;

            case QUIZ_ATTEMPTLAST:
                // Because of the where clause, there will only be one row, but we
                // must still use an aggregate function.
                $select = 'MAX(quiza.sumgrades)';
                $join = $firstlastattemptjoin;
                $where = 'quiza.attempt = first_last_attempts.lastattempt AND';
                break;

            case QUIZ_GRADEAVERAGE:
                $select = 'AVG(quiza.sumgrades)';
                $join = '';
                $where = '';
                break;

            default:
            case QUIZ_GRADEHIGHEST:
                $select = 'MAX(quiza.sumgrades)';
                $join = '';
                $where = '';
                break;
        }

        if ($quiz->sumgrades >= self::ALMOST_ZERO) {
            $finalgrade = $select . ' * ' . ($quiz->grade / $quiz->sumgrades);
        } else {
            $finalgrade = '0';
        }
        $param['quizid'] = $quiz->id;
        $param['quizid2'] = $quiz->id;
        $param['quizid3'] = $quiz->id;
        $param['quizid4'] = $quiz->id;
        $param['statefinished'] = quiz_attempt::FINISHED;
        $param['statefinished2'] = quiz_attempt::FINISHED;
        $param['almostzero'] = self::ALMOST_ZERO;
        $finalgradesubquery = "
                SELECT quiza.userid, $finalgrade AS newgrade
                FROM {quiz_attempts} quiza
                $join
                WHERE
                    $where
                    quiza.state = :statefinished AND
                    quiza.preview = 0 AND
                    quiza.quiz = :quizid3
                GROUP BY quiza.userid";

        $changedgrades = $DB->get_records_sql("
                SELECT users.userid, qg.id, qg.grade, newgrades.newgrade

                FROM (
                    SELECT userid
                    FROM {quiz_grades} qg
                    WHERE quiz = :quizid
                UNION
                    SELECT DISTINCT userid
                    FROM {quiz_attempts} quiza2
                    WHERE
                        quiza2.state = :statefinished2 AND
                        quiza2.preview = 0 AND
                        quiza2.quiz = :quizid2
                ) users

                LEFT JOIN {quiz_grades} qg ON qg.userid = users.userid AND qg.quiz = :quizid4

                LEFT JOIN (
                    $finalgradesubquery
                ) newgrades ON newgrades.userid = users.userid

                WHERE
                    ABS(newgrades.newgrade - qg.grade) > :almostzero OR
                    ((newgrades.newgrade IS NULL OR qg.grade IS NULL) AND NOT
                              (newgrades.newgrade IS NULL AND qg.grade IS NULL))",
                    // The mess on the previous line is detecting where the value is
                    // NULL in one column, and NOT NULL in the other, but SQL does
                    // not have an XOR operator, and MS SQL server can't cope with
                    // (newgrades.newgrade IS NULL) <> (qg.grade IS NULL).
                $param);

        $timenow = time();
        $todelete = [];
        foreach ($changedgrades as $changedgrade) {

            if (is_null($changedgrade->newgrade)) {
                $todelete[] = $changedgrade->userid;

            } else if (is_null($changedgrade->grade)) {
                $toinsert = new stdClass();
                $toinsert->quiz = $quiz->id;
                $toinsert->userid = $changedgrade->userid;
                $toinsert->timemodified = $timenow;
                $toinsert->grade = $changedgrade->newgrade;
                $DB->insert_record('quiz_grades', $toinsert);

            } else {
                $toupdate = new stdClass();
                $toupdate->id = $changedgrade->id;
                $toupdate->grade = $changedgrade->newgrade;
                $toupdate->timemodified = $timenow;
                $DB->update_record('quiz_grades', $toupdate);
            }
        }

        if (!empty($todelete)) {
            list($test, $params) = $DB->get_in_or_equal($todelete);
            $DB->delete_records_select('quiz_grades', 'quiz = ? AND userid ' . $test,
                    array_merge([$quiz->id], $params));
        }
    }

    /**
     * Update the quiz setting for the grade the quiz is out of.
     *
     * This function will update the data in quiz_grades and quiz_feedback, and
     * pass the new grades on to the gradebook.
     *
     * @param float $newgrade the new maximum grade for the quiz.
     */
    public function update_quiz_maximum_grade(float $newgrade): void {
        global $DB;
        $quiz = $this->quizobj->get_quiz();

        // This is potentially expensive, so only do it if necessary.
        if (abs($quiz->grade - $newgrade) < self::ALMOST_ZERO) {
            // Nothing to do.
            return;
        }

        // Use a transaction.
        $transaction = $DB->start_delegated_transaction();

        // Update the quiz table.
        $oldgrade = $quiz->grade;
        $quiz->grade = $newgrade;
        $timemodified = time();
        $DB->update_record('quiz', (object) [
            'id' => $quiz->id,
            'grade' => $newgrade,
            'timemodified' => $timemodified,
        ]);

        // Rescale the grade of all quiz attempts.
        if ($oldgrade < $newgrade) {
            // The new total is bigger, so we need to recompute fully to avoid underflow problems.
            $this->recompute_all_final_grades();

        } else {
            // New total smaller, so we can rescale the grades efficiently.
            $DB->execute("
                    UPDATE {quiz_grades}
                       SET grade = ? * grade, timemodified = ?
                     WHERE quiz = ?
            ", [$newgrade / $oldgrade, $timemodified, $quiz->id]);
        }

        // Rescale the overall feedback boundaries.
        if ($oldgrade > self::ALMOST_ZERO) {
            // Update the quiz_feedback table.
            $factor = $newgrade / $oldgrade;
            $DB->execute("
                    UPDATE {quiz_feedback}
                    SET mingrade = ? * mingrade, maxgrade = ? * maxgrade
                    WHERE quizid = ?
            ", [$factor, $factor, $quiz->id]);
        }

        // Update grade item and send all grades to gradebook.
        quiz_grade_item_update($quiz);
        quiz_update_grades($quiz);

        // Log quiz grade updated event.
        quiz_grade_updated::create([
            'context' => $this->quizobj->get_context(),
            'objectid' => $quiz->id,
            'other' => [
                'oldgrade' => $oldgrade + 0, // Remove trailing 0s.
                'newgrade' => $newgrade,
            ]
        ])->trigger();

        $transaction->allow_commit();
    }

    /**
     * Ensure the {@see grade_calculator::$gradeitems} field is ready to use.
     */
    protected function ensure_grade_items_loaded(): void {
        global $DB;

        if ($this->gradeitems !== null) {
            return; // Already done.
        }

        $this->gradeitems = $DB->get_records_sql("
            SELECT gi.id,
                   gi.quizid,
                   gi.sortorder,
                   gi.name,
                   COALESCE(SUM(slot.maxmark), 0) AS maxmark

              FROM {quiz_grade_items} gi
         LEFT JOIN {quiz_slots} slot ON slot.quizgradeitemid = gi.id

             WHERE gi.quizid = ? AND slot.quizid = ?

          GROUP BY gi.id, gi.quizid, gi.sortorder, gi.name

          ORDER BY gi.sortorder
            ", [$this->quizobj->get_quizid(), $this->quizobj->get_quizid()]);
    }

    /**
     * Get the extra grade items for this quiz.
     *
     * Returned objects have fields ->id, ->quizid, ->sortorder, ->name and maxmark.
     * @return stdClass[] the grade items for this quiz.
     */
    public function get_grade_items(): array {
        $this->ensure_grade_items_loaded();
        return $this->gradeitems;
    }

    /**
     * Lets other code pass in the slot information, so it does note have to be re-loaded from the DB.
     *
     * @param stdClass[] $slots the data from quiz_slots. The only required fields are ->slot and ->quizgradeitemid.
     */
    public function set_slots(array $slots): void {
        global $CFG;
        $this->slots = $slots;

        if ($CFG->debugdeveloper) {
            foreach ($slots as $slot) {
                if (!property_exists($slot, 'slot') || !property_exists($slot, 'quizgradeitemid')) {
                    debugging('Slot data passed to grade_calculator::set_slots ' .
                        'must have at least ->slot and ->quizgradeitemid set.', DEBUG_DEVELOPER);
                    break; // Only necessary to say this once.
                }
            }
        }
    }

    /**
     * Ensure the {@see $gradeitems} field is ready to use.
     */
    protected function ensure_slots_loaded(): void {
        global $DB;

        if ($this->slots !== null) {
            return; // Already done.
        }

        $this->slots = $DB->get_records('quiz_slots', ['quizid' => $this->quizobj->get_quizid()],
            'slot', 'slot, id, quizgradeitemid');
    }

    /**
     * Compute the grade and maximum for each item, for an attempt where the question_usage_by_activity is available.
     *
     * @param question_usage_by_activity $quba usage for the quiz attempt we want to calculate the grades of.
     * @return grade_out_of[] the grade for each item where the total grade is not zero.
     *      ->name will be set to the grade item name. Must be output through {@see format_string()}.
     */
    public function compute_grade_item_totals(question_usage_by_activity $quba): array {
        $this->ensure_grade_items_loaded();
        if (empty($this->gradeitems)) {
            // No extra grade items.
            return [];
        }

        $this->ensure_slots_loaded();

        // Prepare a place to store the results for each grade-item.
        $grades = [];
        foreach ($this->gradeitems as $gradeitem) {
            $grades[$gradeitem->id] = new grade_out_of(
                $this->quizobj->get_quiz(), 0, $gradeitem->maxmark, name: $gradeitem->name);
        }

        // Add up the scores.
        foreach ($this->slots as $slot) {
            if (!$slot->quizgradeitemid) {
                continue;
            }
            $grades[$slot->quizgradeitemid]->grade += $quba->get_question_mark($slot->slot);
        }

        // Remove any grade items where the total is 0.
        foreach ($grades as $gradeitemid => $grade) {
            if ($grade->maxgrade < self::ALMOST_ZERO) {
                unset($grades[$gradeitemid]);
            }
        }

        return $grades;
    }

    /**
     * Compute the grade and maximum for each item, for some attempts where we only have the usage ids.
     *
     * @param int[] $qubaids array of usage ids.
     * @return grade_out_of[][] question_usage.id => array of grade_out_of.
     *      ->name will be set to the grade item name. Must be output through {@see format_string()}..
     */
    public function compute_grade_item_totals_for_attempts(array $qubaids): array {
        $this->ensure_grade_items_loaded();
        $grades = [];
        foreach ($qubaids as $qubaid) {
            $grades[$qubaid] = [];
        }

        if (empty($this->gradeitems || empty($qubaids))) {
            // Nothing to do.
            return $grades;
        }

        $gradesdata = $this->load_grade_item_totals(new qubaid_list($qubaids));
        foreach ($qubaids as $qubaid) {
            foreach ($this->gradeitems as $gradeitem) {
                if ($gradeitem->maxmark < self::ALMOST_ZERO) {
                    continue;
                }
                $grades[$qubaid][$gradeitem->id] = new grade_out_of(
                    $this->quizobj->get_quiz(),
                    $gradesdata[$qubaid][$gradeitem->id] ?? 0,
                    $gradeitem->maxmark,
                    name: $gradeitem->name,
                );
            }
        }

        return $grades;
    }

    /**
     * Query the database return the total mark for each grade item for a set of attempts.
     *
     * @param qubaid_condition $qubaids which question_usages to computer the total marks for.
     * @return float[][] Array question_usage.id => quiz_grade_item.id => mark.
     */
    public function load_grade_item_totals(qubaid_condition $qubaids): array {
        global $DB;
        $dm = new question_engine_data_mapper();

        [$qalatestview, $viewparams] = $dm->question_attempt_latest_state_view('qalatest', $qubaids);

        $totals = $DB->get_records_sql("
            SELECT " . $DB->sql_concat('qalatest.questionusageid', "'#'", 'slot.quizgradeitemid') . " AS uniquefirstcolumn,
                   qalatest.questionusageid,
                   slot.quizgradeitemid,
                   SUM(qalatest.fraction * qalatest.maxmark) AS summarks

              FROM $qalatestview

              JOIN {quiz_slots} slot ON slot.slot = qalatest.slot
              JOIN {quiz_grade_items} qgi ON qgi.id = slot.quizgradeitemid

          GROUP BY qalatest.questionusageid, slot.quizgradeitemid

            ", $viewparams);

        $marks = [];
        foreach ($totals as $total) {
            $marks[$total->questionusageid][$total->quizgradeitemid] = $total->summarks + 0; // Convert to float with + 0.
        }

        return $marks;
    }
}