AutorÃa | Ultima modificación | Ver Log |
<?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 core_component;use mod_quiz\form\preflight_check_form;use mod_quiz\local\access_rule_base;use mod_quiz\output\renderer;use mod_quiz\question\display_options;use mod_quiz_mod_form;use moodle_page;use moodle_url;use MoodleQuickForm;use stdClass;/*** This class aggregates the access rules that apply to a particular quiz.** This provides a convenient API which other parts of the quiz code can use* to interact with the access rules.** @package mod_quiz* @copyright 2009 Tim Hunt* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later* @since Moodle 2.2*/class access_manager {/** @var quiz_settings the quiz settings object. */protected $quizobj;/** @var int the time to be considered as 'now'. */protected $timenow;/** @var access_rule_base instances of the active rules for this quiz. */protected $rules = [];/*** Create an instance for a particular quiz.** @param quiz_settings $quizobj the quiz settings.* The quiz we will be controlling access to.* @param int $timenow The time to use as 'now'.* @param bool $canignoretimelimits Whether this user is exempt from time* limits (has_capability('mod/quiz:ignoretimelimits', ...)).*/public function __construct(quiz_settings $quizobj, int $timenow, bool $canignoretimelimits) {$this->quizobj = $quizobj;$this->timenow = $timenow;$this->rules = $this->make_rules($quizobj, $timenow, $canignoretimelimits);}/*** Make all the rules relevant to a particular quiz.** @param quiz_settings $quizobj information about the quiz in question.* @param int $timenow the time that should be considered as 'now'.* @param bool $canignoretimelimits whether the current user is exempt from* time limits by the mod/quiz:ignoretimelimits capability.* @return access_rule_base[] rules that apply to this quiz.*/protected function make_rules(quiz_settings $quizobj, int $timenow, bool $canignoretimelimits): array {$rules = [];foreach (self::get_rule_classes() as $ruleclass) {$rule = $ruleclass::make($quizobj, $timenow, $canignoretimelimits);if ($rule) {$rules[$ruleclass] = $rule;}}$superceededrules = [];foreach ($rules as $rule) {$superceededrules += $rule->get_superceded_rules();}foreach ($superceededrules as $superceededrule) {unset($rules['quizaccess_' . $superceededrule]);}return $rules;}/*** Get that names of all the installed rule classes.** @return array of class names.*/protected static function get_rule_classes(): array {return core_component::get_plugin_list_with_class('quizaccess', '', 'rule.php');}/*** Add any form fields that the access rules require to the settings form.** Note that the standard plugins do not use this mechanism, becuase all their* settings are stored in the quiz table.** @param mod_quiz_mod_form $quizform the quiz settings form that is being built.* @param MoodleQuickForm $mform the wrapped MoodleQuickForm.*/public static function add_settings_form_fields(mod_quiz_mod_form $quizform, MoodleQuickForm $mform): void {foreach (self::get_rule_classes() as $rule) {$rule::add_settings_form_fields($quizform, $mform);}}/*** The the options for the Browser security settings menu.** @return array key => lang string.*/public static function get_browser_security_choices(): array {$options = ['-' => get_string('none', 'quiz')];foreach (self::get_rule_classes() as $rule) {$options += $rule::get_browser_security_choices();}return $options;}/*** Validate the data from any form fields added using {@see add_settings_form_fields()}.** @param array $errors the errors found so far.* @param array $data the submitted form data.* @param array $files information about any uploaded files.* @param mod_quiz_mod_form $quizform the quiz form object.* @return array $errors the updated $errors array.*/public static function validate_settings_form_fields(array $errors,array $data, array $files, mod_quiz_mod_form $quizform): array {foreach (self::get_rule_classes() as $rule) {$errors = $rule::validate_settings_form_fields($errors, $data, $files, $quizform);}return $errors;}/*** Save any submitted settings when the quiz settings form is submitted.** Note that the standard plugins do not use this mechanism because their* settings are stored in the quiz table.** @param stdClass $quiz the data from the quiz form, including $quiz->id* which is the id of the quiz being saved.*/public static function save_settings(stdClass $quiz): void {foreach (self::get_rule_classes() as $rule) {$rule::save_settings($quiz);}}/*** Delete any rule-specific settings when the quiz is deleted.** Note that the standard plugins do not use this mechanism because their* settings are stored in the quiz table.** @param stdClass $quiz the data from the database, including $quiz->id* which is the id of the quiz being deleted.* @since Moodle 2.7.1, 2.6.4, 2.5.7*/public static function delete_settings(stdClass $quiz): void {foreach (self::get_rule_classes() as $rule) {$rule::delete_settings($quiz);}}/*** Build the SQL for loading all the access settings in one go.** @param int $quizid the quiz id.* @param array $rules list of rule plugins, from {@see get_rule_classes()}.* @param string $basefields initial part of the select list.* @return array with two elements, the sql and the placeholder values.* If $basefields is '' then you must allow for the possibility that* there is no data to load, in which case this method returns $sql = ''.*/protected static function get_load_sql(int $quizid, array $rules, string $basefields): array {$allfields = $basefields;$alljoins = '{quiz} quiz';$allparams = ['quizid' => $quizid];foreach ($rules as $rule) {[$fields, $joins, $params] = $rule::get_settings_sql($quizid);if ($fields) {if ($allfields) {$allfields .= ', ';}$allfields .= $fields;}if ($joins) {$alljoins .= ' ' . $joins;}if ($params) {$allparams += $params;}}if ($allfields === '') {return ['', []];}return ["SELECT $allfields FROM $alljoins WHERE quiz.id = :quizid", $allparams];}/*** Load any settings required by the access rules. We try to do this with* a single DB query.** Note that the standard plugins do not use this mechanism, becuase all their* settings are stored in the quiz table.** @param int $quizid the quiz id.* @return array setting value name => value. The value names should all* start with the name of the corresponding plugin to avoid collisions.*/public static function load_settings(int $quizid): array {global $DB;$rules = self::get_rule_classes();[$sql, $params] = self::get_load_sql($quizid, $rules, '');if ($sql) {$data = (array) $DB->get_record_sql($sql, $params);} else {$data = [];}foreach ($rules as $rule) {$data += $rule::get_extra_settings($quizid);}return $data;}/*** Load the quiz settings and any settings required by the access rules.* We try to do this with a single DB query.** Note that the standard plugins do not use this mechanism, becuase all their* settings are stored in the quiz table.** @param int $quizid the quiz id.* @return stdClass mdl_quiz row with extra fields.*/public static function load_quiz_and_settings(int $quizid): stdClass {global $DB;$rules = self::get_rule_classes();[$sql, $params] = self::get_load_sql($quizid, $rules, 'quiz.*');$quiz = $DB->get_record_sql($sql, $params, MUST_EXIST);foreach ($rules as $rule) {foreach ($rule::get_extra_settings($quizid) as $name => $value) {$quiz->$name = $value;}}return $quiz;}/*** Get an array of the class names of all the active rules.** Mainly useful for debugging.** @return array*/public function get_active_rule_names(): array {$classnames = [];foreach ($this->rules as $rule) {$classnames[] = get_class($rule);}return $classnames;}/*** Accumulates an array of messages.** @param array $messages the current list of messages.* @param string|array $new the new messages or messages.* @return array the updated array of messages.*/protected function accumulate_messages(array $messages, $new): array {if (is_array($new)) {$messages = array_merge($messages, $new);} else if (is_string($new) && $new) {$messages[] = $new;}return $messages;}/*** Provide a description of the rules that apply to this quiz, such* as is shown at the top of the quiz view page. Note that not all* rules consider themselves important enough to output a description.** @return array an array of description messages which may be empty. It* would be sensible to output each one surrounded by <p> tags.*/public function describe_rules(): array {$result = [];foreach ($this->rules as $rule) {$result = $this->accumulate_messages($result, $rule->description());}return $result;}/*** Whether a user should be allowed to start a new attempt at this quiz now.* If there are any restrictions in force now, return an array of reasons why access* should be blocked. If access is OK, return false.** @param int $numprevattempts the number of previous attempts this user has made.* @param stdClass|false $lastattempt information about the user's last completed attempt.* if there is not a previous attempt, the false is passed.* @return array an array of reason why access is not allowed. An empty array* (== false) if access should be allowed.*/public function prevent_new_attempt(int $numprevattempts, $lastattempt): array {$reasons = [];foreach ($this->rules as $rule) {$reasons = $this->accumulate_messages($reasons,$rule->prevent_new_attempt($numprevattempts, $lastattempt));}return $reasons;}/*** Whether the user should be blocked from starting a new attempt or continuing* an attempt now. If there are any restrictions in force now, return an array* of reasons why access should be blocked. If access is OK, return false.** @return array An array of reason why access is not allowed, or an empty array* (== false) if access should be allowed.*/public function prevent_access(): array {$reasons = [];foreach ($this->rules as $rule) {$reasons = $this->accumulate_messages($reasons, $rule->prevent_access());}return $reasons;}/*** Is a UI check is required before the user starts/continues their attempt.** @param int|null $attemptid the id of the current attempt, if there is one,* otherwise null.* @return bool whether a check is required.*/public function is_preflight_check_required(?int $attemptid): bool {foreach ($this->rules as $rule) {if ($rule->is_preflight_check_required($attemptid)) {return true;}}return false;}/*** Build the form required to do the pre-flight checks.* @param moodle_url $url the form action URL.* @param int|null $attemptid the id of the current attempt, if there is one,* otherwise null.* @return preflight_check_form the form.*/public function get_preflight_check_form(moodle_url $url, ?int $attemptid): preflight_check_form {// This form normally wants POST submissions. However, it also needs to// accept GET submissions. Since formslib is strict, we have to detect// which case we are in, and set the form property appropriately.$method = 'post';if (!empty($_GET['_qf__preflight_check_form'])) {$method = 'get';}return new preflight_check_form($url->out_omit_querystring(),['rules' => $this->rules, 'quizobj' => $this->quizobj,'attemptid' => $attemptid, 'hidden' => $url->params()], $method);}/*** The pre-flight check has passed. This is a chance to record that fact in some way.** @param int|null $attemptid the id of the current attempt, if there is one,* otherwise null.*/public function notify_preflight_check_passed(?int $attemptid): void {foreach ($this->rules as $rule) {$rule->notify_preflight_check_passed($attemptid);}}/*** Inform the rules that the current attempt is finished.** This is use, for example by the password rule, to clear the flag in the session.*/public function current_attempt_finished(): void {foreach ($this->rules as $rule) {$rule->current_attempt_finished();}}/*** Do any of the rules mean that this student will no be allowed any further attempts at this* quiz. Used, for example, to change the label by the grade displayed on the view page from* 'your current grade is' to 'your final grade is'.** @param int $numprevattempts the number of previous attempts this user has made.* @param stdClass|false $lastattempt information about the user's last completed attempt.* @return bool true if there is no way the user will ever be allowed to attempt* this quiz again.*/public function is_finished(int $numprevattempts, $lastattempt): bool {foreach ($this->rules as $rule) {if ($rule->is_finished($numprevattempts, $lastattempt)) {return true;}}return false;}/*** Sets up the attempt (review or summary) page with any properties required* by the access rules.** @param moodle_page $page the page object to initialise.*/public function setup_attempt_page(moodle_page $page): void {foreach ($this->rules as $rule) {$rule->setup_attempt_page($page);}}/*** Compute when the attempt must be submitted.** @param stdClass $attempt the data from the relevant quiz_attempts row.* @return int|false the attempt close time. False if there is no limit.*/public function get_end_time(stdClass $attempt) {$timeclose = false;foreach ($this->rules as $rule) {$ruletimeclose = $rule->end_time($attempt);if ($ruletimeclose !== false && ($timeclose === false || $ruletimeclose < $timeclose)) {$timeclose = $ruletimeclose;}}return $timeclose;}/*** Compute what should be displayed to the user for time remaining in this attempt.** @param stdClass $attempt the data from the relevant quiz_attempts row.* @param int $timenow the time to consider as 'now'.* @return int|false the number of seconds remaining for this attempt.* False if no limit should be displayed.*/public function get_time_left_display(stdClass $attempt, int $timenow) {$timeleft = false;foreach ($this->rules as $rule) {$ruletimeleft = $rule->time_left_display($attempt, $timenow);if ($ruletimeleft !== false && ($timeleft === false || $ruletimeleft < $timeleft)) {$timeleft = $ruletimeleft;}}return $timeleft;}/*** Is this quiz required to be shown in a popup window?** @return bool true if a popup is required.*/public function attempt_must_be_in_popup(): bool {foreach ($this->rules as $rule) {if ($rule->attempt_must_be_in_popup()) {return true;}}return false;}/*** Get options required for opening the attempt in a popup window.** @return array any options that are required for showing the attempt page* in a popup window.*/public function get_popup_options(): array {$options = [];foreach ($this->rules as $rule) {$options += $rule->get_popup_options();}return $options;}/*** Send the user back to the quiz view page. Normally this is just a redirect, but* If we were in a secure window, we close this window, and reload the view window we came from.** This method does not return;** @param renderer $output the quiz renderer.* @param string $message optional message to output while redirecting.*/public function back_to_view_page(renderer $output, string $message = ''): void {// Actually return type 'never' on the previous line, once 8.1 is our minimum PHP version.if ($this->attempt_must_be_in_popup()) {echo $output->close_attempt_popup(new moodle_url($this->quizobj->view_url()), $message);die();} else {redirect($this->quizobj->view_url(), $message);}}/*** Make some text into a link to review the quiz, if that is appropriate.** @param stdClass $attempt the attempt object* @param mixed $nolongerused not used any more.* @param renderer $output quiz renderer instance.* @return string some HTML, the $linktext either unmodified or wrapped in a* link to the review page.*/public function make_review_link(stdClass $attempt, $nolongerused, renderer $output): string {// If the attempt is still open, don't link.if (in_array($attempt->state, [quiz_attempt::IN_PROGRESS, quiz_attempt::OVERDUE])) {return $output->no_review_message('');}$when = quiz_attempt_state($this->quizobj->get_quiz(), $attempt);$reviewoptions = display_options::make_from_quiz($this->quizobj->get_quiz(), $when);if (!$reviewoptions->attempt) {return $output->no_review_message($this->quizobj->cannot_review_message($when, true, $attempt->timefinish));} else {return $output->review_link($this->quizobj->review_url($attempt->id),$this->attempt_must_be_in_popup(), $this->get_popup_options());}}/*** Run the preflight checks using the given data in all the rules supporting them.** @param array $data passed data for validation* @param array $files un-used, Moodle seems to not support it anymore* @param int|null $attemptid the id of the current attempt, if there is one,* otherwise null.* @return array of errors, empty array means no errors* @since Moodle 3.1*/public function validate_preflight_check(array $data, array $files, ?int $attemptid): array {$errors = [];foreach ($this->rules as $rule) {if ($rule->is_preflight_check_required($attemptid)) {$errors = $rule->validate_preflight_check($data, $files, $errors, $attemptid);}}return $errors;}}