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 stdClass;

/**
 * Helper for sending quiz related notifications.
 *
 * @package    mod_quiz
 * @copyright  2024 David Woloszyn <david.woloszyn@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class notification_helper {
    /**
     * @var int Default date range of 48 hours.
     */
    private const DEFAULT_DATE_RANGE = (DAYSECS * 2);

    /**
     * Get all quizzes that have an approaching open date (includes users and groups with open date overrides).
     *
     * @return \moodle_recordset Returns the matching quiz records.
     */
    public static function get_quizzes_within_date_range(): \moodle_recordset {
        global $DB;

        $timenow = self::get_time_now();
        $futuretime = self::get_future_time();

        $sql = "SELECT DISTINCT q.id
                  FROM {quiz} q
                  JOIN {course} c ON q.course = c.id
                  JOIN {course_modules} cm ON q.id = cm.instance
                  JOIN {modules} m ON cm.module = m.id AND m.name = :modulename
             LEFT JOIN {quiz_overrides} qo ON q.id = qo.quiz
                 WHERE (q.timeopen < :futuretime OR qo.timeopen < :qo_futuretime)
                   AND (q.timeopen > :timenow OR qo.timeopen > :qo_timenow)
                   AND cm.visible = 1
                   AND c.visible = 1";

        $params = [
            'timenow' => $timenow,
            'futuretime' => $futuretime,
            'qo_timenow' => $timenow,
            'qo_futuretime' => $futuretime,
            'modulename' => 'quiz',
        ];

        return $DB->get_recordset_sql($sql, $params);
    }

    /**
     * Get all users that have an approaching open date within a quiz.
     *
     * @param int $quizid The quiz id.
     * @return array The users after all filtering has been applied.
     */
    public static function get_users_within_quiz(int $quizid): array {
        // Get quiz data.
        $quizobj = quiz_settings::create($quizid);
        $quiz = $quizobj->get_quiz();

        // Get our users.
        $users = get_enrolled_users(
            context: \context_module::instance($quizobj->get_cm()->id),
            withcapability: 'mod/quiz:attempt',
            userfields: 'u.id, u.firstname, u.suspended, u.auth',
        );

        // Filter a list of users who meet the availability conditions.
        $info = new \core_availability\info_module($quizobj->get_cm());
        $users = $info->filter_user_list($users);

        // Check for any override dates.
        $overrides = $quizobj->get_override_manager()->get_all_overrides();

        foreach ($users as $key => $user) {
            if ($user->suspended || ($user->auth == 'nologin')) {
                unset($users[$key]);
                continue;
            }
            // Time open and time close dates can be user specific with an override.
            // We begin by assuming it is the same as recorded in the quiz.
            $user->timeopen = $quiz->timeopen;
            $user->timeclose = $quiz->timeclose;

            // Set the override type to 'none' to begin with.
            $user->overridetype = 'none';

            // Update this user with any applicable override dates.
            if (!empty($overrides)) {
                self::update_user_with_date_overrides($overrides, $user);
            }

            // If the 'timeopen' date has no value, even after overriding, unset this user.
            if (empty($quiz->timeopen) && empty($user->timeopen)) {
                unset($users[$key]);
                continue;
            }

            // Check the date is within our range.
            // We have to check here because we don't know if this quiz was selected because it only had users with overrides.
            if (!self::is_time_within_range($user->timeopen)) {
                unset($users[$key]);
                continue;
            }

            // Check if the user has already received this notification.
            $match = [
                'quizid' => strval($quizid),
                'timeopen' => $user->timeopen,
                'overridetype' => $user->overridetype,
            ];

            if (self::has_user_been_sent_a_notification_already($user->id, json_encode($match))) {
                unset($users[$key]);
            }
        }

        return $users;
    }

    /**
     * Send the notification to the user.
     *
     * @param stdClass $user The user's custom data.
     */
    public static function send_notification_to_user(stdClass $user): void {
        // Check if the user has submitted already.
        if (self::has_user_attempted($user)) {
            return;
        }

        // Get quiz data.
        $quizobj = quiz_settings::create($user->quizid);
        $quiz = $quizobj->get_quiz();
        $url = $quizobj->view_url();

        $stringparams = [
            'firstname' => $user->firstname,
            'quizname' => format_string($quiz->name,
                options: ['context' => $quizobj->get_context(), 'escape' => false]),
            'coursename' => format_string($quizobj->get_course()->fullname,
                options: ['context' => \context_course::instance($quizobj->get_course()->id), 'escape' => false]),
            'timeopen' => userdate($user->timeopen),
            'timeclose' => !empty($user->timeclose) ? userdate($user->timeclose) : get_string('statusna'),
            'url' => $url,
        ];

        $messagedata = [
            'user' => \core_user::get_user($user->id),
            'url' => $url->out(false),
            'subject' => get_string('quizopendatesoonsubject', 'mod_quiz', $stringparams),
            'quizname' => $stringparams['quizname'],
            'html' => get_string('quizopendatesoonhtml', 'mod_quiz', $stringparams),
        ];

        // Prepare message object.
        $message = new \core\message\message();
        $message->component = 'mod_quiz';
        $message->name = 'quiz_open_soon';
        $message->userfrom = \core_user::get_noreply_user();
        $message->userto = $messagedata['user'];
        $message->subject = $messagedata['subject'];
        $message->fullmessageformat = FORMAT_HTML;
        $message->fullmessage = html_to_text($messagedata['html']);
        $message->fullmessagehtml = $messagedata['html'];
        $message->smallmessage = $messagedata['subject'];
        $message->notification = 1;
        $message->contexturl = $messagedata['url'];
        $message->contexturlname = $messagedata['quizname'];
        // Use custom data to avoid future notifications being sent again.
        $message->customdata = [
            'quizid' => $user->quizid,
            'timeopen' => $user->timeopen,
            'overridetype' => $user->overridetype,
        ];

        message_send($message);
    }

    /**
     * Get the time now.
     *
     * @return int The time now as a timestamp.
     */
    protected static function get_time_now(): int {
        return \core\di::get(\core\clock::class)->time();
    }

    /**
     * Get a future time that serves as the cut-off for this notification.
     *
     * @param int|null $range Amount of seconds added to the now time (optional).
     * @return int The time now value plus the range.
     */
    protected static function get_future_time(?int $range = null): int {
        $range = $range ?? self::DEFAULT_DATE_RANGE;
        return self::get_time_now() + $range;
    }

    /**
     * Check if a time is within the current time now and the future time values.
     *
     * @param int $time The timestamp to check.
     * @return boolean
     */
    protected static function is_time_within_range(int $time): bool {
        return ($time > self::get_time_now() && $time < self::get_future_time());
    }

    /**
     * Update user's recorded date based on the overrides.
     *
     * @param array $overrides The overrides to check.
     * @param stdClass $user The user records we will be updating.
     */
    protected static function update_user_with_date_overrides(array $overrides, stdClass $user): void {

        foreach ($overrides as $override) {
            // User override.
            if ($override->userid === $user->id) {
                $user->timeopen = !empty($override->timeopen) ? $override->timeopen : $user->timeopen;
                $user->timeclose = !empty($override->timeclose) ? $override->timeclose : $user->timeclose;
                $user->overridetype = 'user';
                // User override has precedence over group. Return here.
                return;
            }
            // Group override.
            if (!empty($override->groupid) && groups_is_member($override->groupid, $user->id)) {
                // If user is a member of multiple groups, and we have set this already, use the earliest date.
                if ($user->overridetype === 'group' && $user->timeopen < $override->timeopen) {
                    continue;
                }
                $user->timeopen = !empty($override->timeopen) ? $override->timeopen : $user->timeopen;
                $user->timeclose = !empty($override->timeclose) ? $override->timeclose : $user->timeclose;
                $user->overridetype = 'group';
            }
        }
    }

    /**
     * Check if a user has attempted this quiz already.
     *
     * @param stdClass $user The user record we will be checking.
     * @return bool Return true if attempt found.
     */
    protected static function has_user_attempted(stdClass $user): bool {
        global $DB;

        return $DB->record_exists('quiz_attempts', [
            'quiz' => $user->quizid,
            'userid' => $user->id,
        ]);
    }

    /**
     * Check if a user has been sent a notification already.
     *
     * @param int $userid The user id.
     * @param string $match The custom data string to match on.
     * @return bool Returns true if already sent.
     */
    protected static function has_user_been_sent_a_notification_already(int $userid, string $match): bool {
        global $DB;

        $sql = "SELECT COUNT(n.id)
                  FROM {notifications} n
                 WHERE " . $DB->sql_compare_text('n.customdata', 255) . " = " . $DB->sql_compare_text(':match', 255) . "
                   AND n.useridto = :userid";

        $result = $DB->count_records_sql($sql, [
            'userid' => $userid,
            'match' => $match,
        ]);

        return ($result > 0);
    }
}