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\local;

use mod_quiz\event\group_override_created;
use mod_quiz\event\group_override_deleted;
use mod_quiz\event\group_override_updated;
use mod_quiz\event\user_override_created;
use mod_quiz\event\user_override_deleted;
use mod_quiz\event\user_override_updated;
use mod_quiz\quiz_settings;

/**
 * Manager class for quiz overrides
 *
 * @package   mod_quiz
 * @copyright 2024 Matthew Hilton <matthewhilton@catalyst-au.net>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class override_manager {
    /** @var array quiz setting keys that can be overwritten **/
    private const OVERRIDEABLE_QUIZ_SETTINGS = ['timeopen', 'timeclose', 'timelimit', 'attempts', 'password'];

    /**
     * Create override manager
     *
     * @param \stdClass $quiz The quiz to link the manager to.
     * @param \context_module $context Context being operated in
     */
    public function __construct(
        /** @var \stdClass The quiz linked to this manager instance **/
        protected readonly \stdClass $quiz,
        /** @var \context_module The context being operated in **/
        public readonly \context_module $context
    ) {
        global $CFG;
        // Required for quiz_* methods.
        require_once($CFG->dirroot . '/mod/quiz/locallib.php');

        // Sanity check that the context matches the quiz.
        if (empty($quiz->cmid) || $quiz->cmid != $context->instanceid) {
            throw new \coding_exception("Given context does not match the quiz object");
        }
    }

    /**
     * Returns all overrides for the linked quiz.
     *
     * @return array of quiz_override records
     */
    public function get_all_overrides(): array {
        global $DB;
        return $DB->get_records('quiz_overrides', ['quiz' => $this->quiz->id]);
    }

    /**
     * Validates the data, usually from a moodleform or a webservice call.
     * If it contains an 'id' property, additional validation is performed against the existing record.
     *
     * @param array $formdata data from moodleform or webservice call.
     * @return array array where the keys are error elements, and the values are lists of errors for each element.
     */
    public function validate_data(array $formdata): array {
        global $DB;

        // Because this can be called directly (e.g. via edit_override_form)
        // and not just through save_override, we must ensure the data
        // is parsed in the same way.
        $formdata = $this->parse_formdata($formdata);

        $formdata = (object) $formdata;

        $errors = [];

        // Ensure at least one of the overrideable settings is set.
        $keysthatareset = array_map(function ($key) use ($formdata) {
            return isset($formdata->$key) && !is_null($formdata->$key);
        }, self::OVERRIDEABLE_QUIZ_SETTINGS);

        if (!in_array(true, $keysthatareset)) {
            $errors['general'][] = new \lang_string('nooverridedata', 'quiz');
        }

        // Ensure quiz is a valid quiz.
        if (empty($formdata->quiz) || empty(get_coursemodule_from_instance('quiz', $formdata->quiz))) {
            $errors['quiz'][] = new \lang_string('overrideinvalidquiz', 'quiz');
        }

        // Ensure either userid or groupid is set.
        if (empty($formdata->userid) && empty($formdata->groupid)) {
            $errors['general'][] = new \lang_string('overridemustsetuserorgroup', 'quiz');
        }

        // Ensure not both userid and groupid are set.
        if (!empty($formdata->userid) && !empty($formdata->groupid)) {
            $errors['general'][] = new \lang_string('overridecannotsetbothgroupanduser', 'quiz');
        }

        // If group is set, ensure it is a real group.
        if (!empty($formdata->groupid) && empty(groups_get_group($formdata->groupid))) {
            $errors['groupid'][] = new \lang_string('overrideinvalidgroup', 'quiz');
        }

        // If user is set, ensure it is a valid user.
        if (!empty($formdata->userid) && !\core_user::is_real_user($formdata->userid, true)) {
            $errors['userid'][] = new \lang_string('overrideinvaliduser', 'quiz');
        }

        // Ensure timeclose is later than timeopen, if both are set.
        if (!empty($formdata->timeclose) && !empty($formdata->timeopen) && $formdata->timeclose <= $formdata->timeopen) {
            $errors['timeclose'][] = new \lang_string('closebeforeopen', 'quiz');
        }

        // Ensure attempts is a integer greater than or equal to 0 (0 is unlimited attempts).
        if (isset($formdata->attempts) && ((int) $formdata->attempts < 0)) {
            $errors['attempts'][] = new \lang_string('overrideinvalidattempts', 'quiz');
        }

        // Ensure timelimit is greather than zero.
        if (!empty($formdata->timelimit) && $formdata->timelimit <= 0) {
            $errors['timelimit'][] = new \lang_string('overrideinvalidtimelimit', 'quiz');
        }

        // Ensure other records do not exist with the same group or user.
        if (!empty($formdata->quiz) && (!empty($formdata->userid) || !empty($formdata->groupid))) {
            $existingrecordparams = ['quiz' => $formdata->quiz, 'groupid' => $formdata->groupid ?? null,
                'userid' => $formdata->userid ?? null, ];
            $records = $DB->get_records('quiz_overrides', $existingrecordparams, '', 'id');

            // Ignore self if updating.
            if (!empty($formdata->id)) {
                unset($records[$formdata->id]);
            }

            // If count is not zero, it means existing records exist already for this user/group.
            if (!empty($records)) {
                $errors['general'][] = new \lang_string('overridemultiplerecordsexist', 'quiz');
            }
        }

        // If is existing record, validate it against the existing record.
        if (!empty($formdata->id)) {
            $existingrecorderrors = self::validate_against_existing_record($formdata->id, $formdata);
            $errors = array_merge($errors, $existingrecorderrors);
        }

        // Implode each value (array of error strings) into a single error string.
        foreach ($errors as $key => $value) {
            $errors[$key] = implode(",", $value);
        }

        return $errors;
    }

    /**
     * Returns the existing quiz override record with the given ID or null if does not exist.
     *
     * @param int $id existing quiz override id
     * @return ?\stdClass record, if exists
     */
    private static function get_existing(int $id): ?\stdClass {
        global $DB;
        return $DB->get_record('quiz_overrides', ['id' => $id]) ?: null;
    }

    /**
     * Validates the formdata against an existing record.
     *
     * @param int $existingid id of existing quiz override record
     * @param \stdClass $formdata formdata, usually from moodleform or webservice call.
     * @return array array where the keys are error elements, and the values are lists of errors for each element.
     */
    private static function validate_against_existing_record(int $existingid, \stdClass $formdata): array {
        $existingrecord = self::get_existing($existingid);
        $errors = [];

        // Existing record must exist.
        if (empty($existingrecord)) {
            $errors['general'][] = new \lang_string('overrideinvalidexistingid', 'quiz');
        }

        // Group value must match existing record if it is set in the formdata.
        if (!empty($existingrecord) && !empty($formdata->groupid) && $existingrecord->groupid != $formdata->groupid) {
            $errors['groupid'][] = new \lang_string('overridecannotchange', 'quiz');
        }

        // User value must match existing record if it is set in the formdata.
        if (!empty($existingrecord) && !empty($formdata->userid) && $existingrecord->userid != $formdata->userid) {
            $errors['userid'][] = new \lang_string('overridecannotchange', 'quiz');
        }

        return $errors;
    }

    /**
     * Parses the formdata by finding only the OVERRIDEABLE_QUIZ_SETTINGS,
     * clearing any values that match the existing quiz, and re-adds the user or group id.
     *
     * @param array $formdata data usually from moodleform or webservice call.
     * @return array array containing parsed formdata, with keys as the properties and values as the values.
     * Any values set the same as the existing quiz are set to null.
     */
    public function parse_formdata(array $formdata): array {
        // Get the data from the form that we want to update.
        $settings = array_intersect_key($formdata, array_flip(self::OVERRIDEABLE_QUIZ_SETTINGS));

        // Remove values that are the same as currently in the quiz.
        $settings = $this->clear_unused_values($settings);

        // Add the user / group back as applicable.
        $userorgroupdata = array_intersect_key($formdata, array_flip(['userid', 'groupid', 'quiz', 'id']));

        return array_merge($settings, $userorgroupdata);
    }

    /**
     * Saves the given override. If an id is given, it updates, otherwise it creates a new one.
     * Note, capabilities are not checked, {@see require_manage_capability()}
     *
     * @param array $formdata data usually from moodleform or webservice call.
     * @return int updated/inserted record id
     */
    public function save_override(array $formdata): int {
        global $DB;

        // Extract only the necessary data.
        $datatoset = $this->parse_formdata($formdata);
        $datatoset['quiz'] = $this->quiz->id;

        // Validate the data is OK.
        $errors = $this->validate_data($datatoset);
        if (!empty($errors)) {
            $errorstr = implode(',', $errors);
            throw new \invalid_parameter_exception($errorstr);
        }

        // Insert or update.
        $id = $datatoset['id'] ?? 0;
        if (!empty($id)) {
            $DB->update_record('quiz_overrides', $datatoset);
        } else {
            $id = $DB->insert_record('quiz_overrides', $datatoset);
        }

        $userid = $datatoset['userid'] ?? null;
        $groupid = $datatoset['groupid'] ?? null;

        // Clear the cache.
        $cache = new override_cache($this->quiz->id);
        $cache->clear_for($userid, $groupid);

        // Trigger moodle events.
        if (empty($formdata['id'])) {
            $this->fire_created_event($id, $userid, $groupid);
        } else {
            $this->fire_updated_event($id, $userid, $groupid);
        }

        // Update open events.
        quiz_update_open_attempts(['quizid' => $this->quiz->id]);

        // Update calendar events.
        $isgroup = !empty($datatoset['groupid']);
        if ($isgroup) {
            // If is group, must update the entire quiz calendar events.
            quiz_update_events($this->quiz);
        } else {
            // If is just a user, can update only their calendar event.
            quiz_update_events($this->quiz, (object) $datatoset);
        }

        return $id;
    }

    /**
     * Deletes all the overrides for the linked quiz
     *
     * @param bool $shouldlog If true, will log a override_deleted event
     */
    public function delete_all_overrides(bool $shouldlog = true): void {
        global $DB;
        $overrides = $DB->get_records('quiz_overrides', ['quiz' => $this->quiz->id], '', 'id,userid,groupid');
        $this->delete_overrides($overrides, $shouldlog);
    }

    /**
     * Deletes overrides given just their ID.
     * Note, the given IDs must exist and user must have access to them otherwise an exception will be thrown.
     * Also note, capabilities are not checked, {@see require_manage_capability()}
     *
     * @param array $ids IDs of overrides to delete
     * @param bool $shouldlog If true, will log a override_deleted event
     */
    public function delete_overrides_by_id(array $ids, bool $shouldlog = true): void {
        global $DB;

        $quizsettings = quiz_settings::create($this->quiz->id);

        // Filter for those overrides user can access.
        [$sql, $params] = self::get_override_in_sql($this->quiz->id, $ids);
        $records = array_filter(
            $DB->get_records_select('quiz_overrides', $sql, $params, '', 'id,userid,groupid'),
            fn(\stdClass $override) => $this->can_view_override(
                $override,
                $quizsettings->get_course(),
                $quizsettings->get_cm(),
            ),
        );

        // Ensure all the given ids exist, so the user is aware if they give a dodgy id.
        $missingids = array_diff($ids, array_keys($records));
        if (!empty($missingids)) {
            throw new \invalid_parameter_exception(get_string('overridemissingdelete', 'quiz', implode(',', $missingids)));
        }

        $this->delete_overrides($records, $shouldlog);
    }


    /**
     * Builds sql and parameters to find overrides in quiz with the given ids
     *
     * @param int $quizid id of quiz
     * @param array $ids array of quiz override ids
     * @return array sql and params
     */
    private static function get_override_in_sql(int $quizid, array $ids): array {
        global $DB;

        [$insql, $inparams] = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED);
        $params = array_merge($inparams, ['quizid' => $quizid]);
        $sql = 'id ' . $insql . ' AND quiz = :quizid';
        return [$sql, $params];
    }

    /**
     * Deletes the given overrides in the quiz linked to the override manager.
     * Note - capabilities are not checked, {@see require_manage_capability()}
     *
     * @param array $overrides override to delete. Must specify an id, quizid, and either a userid or groupid.
     * @param bool $shouldlog If true, will log a override_deleted event
     */
    public function delete_overrides(array $overrides, bool $shouldlog = true): void {
        global $DB;

        foreach ($overrides as $override) {
            if (empty($override->id)) {
                throw new \coding_exception("All overrides must specify an ID");
            }

            // Sanity check that user xor group is specified.
            // User or group is required to clear the cache.
            self::ensure_userid_xor_groupid_set($override->userid ?? null, $override->groupid ?? null);
        }

        if (empty($overrides)) {
            // Exit early, since delete select requires at least 1 record.
            return;
        }

        // Match id and quiz.
        [$sql, $params] = self::get_override_in_sql($this->quiz->id, array_column($overrides, 'id'));
        $DB->delete_records_select('quiz_overrides', $sql, $params);

        $cache = new override_cache($this->quiz->id);

        // Perform other cleanup.
        foreach ($overrides as $override) {
            $userid = $override->userid ?? null;
            $groupid = $override->groupid ?? null;

            $cache->clear_for($userid, $groupid);
            $this->delete_override_events($userid, $groupid);

            if ($shouldlog) {
                $this->fire_deleted_event($override->id, $userid, $groupid);
            }
        }
    }

    /**
     * Ensures either userid or groupid is set, but not both.
     * If neither or both are set, a coding exception is thrown.
     *
     * @param ?int $userid user for the record, or null
     * @param ?int $groupid group for the record, or null
     */
    private static function ensure_userid_xor_groupid_set(?int $userid = null, ?int $groupid = null): void {
        $groupset = !empty($groupid);
        $userset = !empty($userid);

        // If either set, but not both (xor).
        $xorset = $groupset ^ $userset;

        if (!$xorset) {
            throw new \coding_exception("Either userid or groupid must be specified, but not both.");
        }
    }

    /**
     * Deletes the events associated with the override.
     *
     * @param ?int $userid or null if groupid is specified
     * @param ?int $groupid or null if the userid is specified
     */
    private function delete_override_events(?int $userid = null, ?int $groupid = null): void {
        global $DB;

        // Sanity check.
        self::ensure_userid_xor_groupid_set($userid, $groupid);

        $eventssearchparams = ['modulename' => 'quiz', 'instance' => $this->quiz->id];

        if (!empty($userid)) {
            $eventssearchparams['userid'] = $userid;
        }

        if (!empty($groupid)) {
            $eventssearchparams['groupid'] = $groupid;
        }

        $events = $DB->get_records('event', $eventssearchparams);
        foreach ($events as $event) {
            $eventold = \calendar_event::load($event);
            $eventold->delete();
        }
    }

    /**
     * Requires the user has the override management capability
     */
    public function require_manage_capability(): void {
        require_capability('mod/quiz:manageoverrides', $this->context);
    }

    /**
     * Requires the user has the override viewing capability
     */
    public function require_read_capability(): void {
        // If user can manage, they can also view.
        // It would not make sense to be able to create and edit overrides without being able to view them.
        if (!has_any_capability(['mod/quiz:viewoverrides', 'mod/quiz:manageoverrides'], $this->context)) {
            throw new \required_capability_exception($this->context, 'mod/quiz:viewoverrides', 'nopermissions', '');
        }
    }

    /**
     * Determine whether user can view a given override record
     *
     * @param \stdClass $override
     * @param \stdClass $course
     * @param \cm_info $cm
     * @return bool
     */
    public function can_view_override(\stdClass $override, \stdClass $course, \cm_info $cm): bool {
        if ($override->groupid) {
            return groups_group_visible($override->groupid, $course, $cm);
        } else {
            return groups_user_groups_visible($course, $override->userid, $cm);
        }
    }

    /**
     * Builds common event data
     *
     * @param int $id override id
     * @return array of data to add as parameters to an event.
     */
    private function get_base_event_params(int $id): array {
        return [
            'context' => $this->context,
            'other' => [
                'quizid' => $this->quiz->id,
            ],
            'objectid' => $id,
        ];
    }

    /**
     * Log that a given override was deleted
     *
     * @param int $id of quiz override that was just deleted
     * @param ?int $userid user attached to override record, or null
     * @param ?int $groupid group attached to override record, or null
     */
    private function fire_deleted_event(int $id, ?int $userid = null, ?int $groupid = null): void {
        // Sanity check.
        self::ensure_userid_xor_groupid_set($userid, $groupid);

        $params = $this->get_base_event_params($id);
        $params['objectid'] = $id;

        if (!empty($userid)) {
            $params['relateduserid'] = $userid;
            user_override_deleted::create($params)->trigger();
        }

        if (!empty($groupid)) {
            $params['other']['groupid'] = $groupid;
            group_override_deleted::create($params)->trigger();
        }
    }


    /**
     * Log that a given override was created
     *
     * @param int $id of quiz override that was just created
     * @param ?int $userid user attached to override record, or null
     * @param ?int $groupid group attached to override record, or null
     */
    private function fire_created_event(int $id, ?int $userid = null, ?int $groupid = null): void {
        // Sanity check.
        self::ensure_userid_xor_groupid_set($userid, $groupid);

        $params = $this->get_base_event_params($id);

        if (!empty($userid)) {
            $params['relateduserid'] = $userid;
            user_override_created::create($params)->trigger();
        }

        if (!empty($groupid)) {
            $params['other']['groupid'] = $groupid;
            group_override_created::create($params)->trigger();
        }
    }

    /**
     * Log that a given override was updated
     *
     * @param int $id of quiz override that was just updated
     * @param ?int $userid user attached to override record, or null
     * @param ?int $groupid group attached to override record, or null
     */
    private function fire_updated_event(int $id, ?int $userid = null, ?int $groupid = null): void {
        // Sanity check.
        self::ensure_userid_xor_groupid_set($userid, $groupid);

        $params = $this->get_base_event_params($id);

        if (!empty($userid)) {
            $params['relateduserid'] = $userid;
            user_override_updated::create($params)->trigger();
        }

        if (!empty($groupid)) {
            $params['other']['groupid'] = $groupid;
            group_override_updated::create($params)->trigger();
        }
    }

    /**
     * Clears any overrideable settings in the formdata, where the value matches what is already in the quiz
     * If they match, the data is set to null.
     *
     * @param array $formdata data usually from moodleform or webservice call.
     * @return array formdata with same values cleared
     */
    private function clear_unused_values(array $formdata): array {
        foreach (self::OVERRIDEABLE_QUIZ_SETTINGS as $key) {
            // If the formdata is the same as the current quiz object data, clear it.
            if (isset($formdata[$key]) && $formdata[$key] == $this->quiz->$key) {
                $formdata[$key] = null;
            }

            // Ensure these keys always are set (even if null).
            $formdata[$key] = $formdata[$key] ?? null;

            // If the formdata is empty, set it to null.
            // This avoids putting 0, false, or '' into the DB since the override logic expects null.
            // Attempts is the exception, it can have a integer value of '0', so we use is_numeric instead.
            if ($key != 'attempts' && empty($formdata[$key])) {
                $formdata[$key] = null;
            }

            if ($key == 'attempts' && !is_numeric($formdata[$key])) {
                $formdata[$key] = null;
            }
        }

        return $formdata;
    }

    /**
     * Deletes orphaned group overrides in a given course.
     * Note - permissions are not checked and events are not logged for performance reasons.
     *
     * @param int $courseid ID of course to delete orphaned group overrides in
     * @return array array of quizzes that had orphaned group overrides.
     */
    public static function delete_orphaned_group_overrides_in_course(int $courseid): array {
        global $DB;

        // It would be nice if we got the groupid that was deleted.
        // Instead, we just update all quizzes with orphaned group overrides.
        $sql = "SELECT o.id, o.quiz, o.groupid
                  FROM {quiz_overrides} o
                  JOIN {quiz} quiz ON quiz.id = o.quiz
             LEFT JOIN {groups} grp ON grp.id = o.groupid
                 WHERE quiz.course = :courseid
                   AND o.groupid IS NOT NULL
                   AND grp.id IS NULL";
        $params = ['courseid' => $courseid];
        $records = $DB->get_records_sql($sql, $params);

        $DB->delete_records_list('quiz_overrides', 'id', array_keys($records));

        // Purge cache for each record.
        foreach ($records as $record) {
            $cache = new override_cache($record->quiz);
            $cache->clear_for_group($record->groupid);
        }
        return array_unique(array_column($records, 'quiz'));
    }
}