2 // This file is part of Moodle - http://moodle.org/
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
18 * Classes to enforce the various access rules that can apply to a quiz.
21 * @copyright 2009 Tim Hunt
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 defined('MOODLE_INTERNAL') ||
die();
30 * This class keeps track of the various access rules that apply to a particular
31 * quiz, with convinient methods for seeing whether access is allowed.
33 * @copyright 2009 Tim Hunt
34 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37 class quiz_access_manager
{
38 /** @var quiz the quiz settings object. */
40 /** @var int the time to be considered as 'now'. */
42 /** @var array of quiz_access_rule_base. */
43 protected $rules = array();
46 * Create an instance for a particular quiz.
47 * @param object $quizobj An instance of the class quiz from attemptlib.php.
48 * The quiz we will be controlling access to.
49 * @param int $timenow The time to use as 'now'.
50 * @param bool $canignoretimelimits Whether this user is exempt from time
51 * limits (has_capability('mod/quiz:ignoretimelimits', ...)).
53 public function __construct($quizobj, $timenow, $canignoretimelimits) {
54 $this->quizobj
= $quizobj;
55 $this->timenow
= $timenow;
56 $this->rules
= $this->make_rules($quizobj, $timenow, $canignoretimelimits);
60 * Make all the rules relevant to a particular quiz.
61 * @param quiz $quizobj information about the quiz in question.
62 * @param int $timenow the time that should be considered as 'now'.
63 * @param bool $canignoretimelimits whether the current user is exempt from
64 * time limits by the mod/quiz:ignoretimelimits capability.
65 * @return array of {@link quiz_access_rule_base}s.
67 protected function make_rules($quizobj, $timenow, $canignoretimelimits) {
70 foreach (self
::get_rule_classes() as $ruleclass) {
71 $rule = $ruleclass::make($quizobj, $timenow, $canignoretimelimits);
73 $rules[$ruleclass] = $rule;
77 $superceededrules = array();
78 foreach ($rules as $rule) {
79 $superceededrules +
= $rule->get_superceded_rules();
82 foreach ($superceededrules as $superceededrule) {
83 unset($rules['quizaccess_' . $superceededrule]);
90 * @return array of all the installed rule class names.
92 protected static function get_rule_classes() {
93 return core_component
::get_plugin_list_with_class('quizaccess', '', 'rule.php');
97 * Add any form fields that the access rules require to the settings form.
99 * Note that the standard plugins do not use this mechanism, becuase all their
100 * settings are stored in the quiz table.
102 * @param mod_quiz_mod_form $quizform the quiz settings form that is being built.
103 * @param MoodleQuickForm $mform the wrapped MoodleQuickForm.
105 public static function add_settings_form_fields(
106 mod_quiz_mod_form
$quizform, MoodleQuickForm
$mform) {
108 foreach (self
::get_rule_classes() as $rule) {
109 $rule::add_settings_form_fields($quizform, $mform);
114 * The the options for the Browser security settings menu.
116 * @return array key => lang string.
118 public static function get_browser_security_choices() {
119 $options = array('-' => get_string('none', 'quiz'));
120 foreach (self
::get_rule_classes() as $rule) {
121 $options +
= $rule::get_browser_security_choices();
127 * Validate the data from any form fields added using {@link add_settings_form_fields()}.
128 * @param array $errors the errors found so far.
129 * @param array $data the submitted form data.
130 * @param array $files information about any uploaded files.
131 * @param mod_quiz_mod_form $quizform the quiz form object.
132 * @return array $errors the updated $errors array.
134 public static function validate_settings_form_fields(array $errors,
135 array $data, $files, mod_quiz_mod_form
$quizform) {
137 foreach (self
::get_rule_classes() as $rule) {
138 $errors = $rule::validate_settings_form_fields($errors, $data, $files, $quizform);
145 * Save any submitted settings when the quiz settings form is submitted.
147 * Note that the standard plugins do not use this mechanism because their
148 * settings are stored in the quiz table.
150 * @param object $quiz the data from the quiz form, including $quiz->id
151 * which is the id of the quiz being saved.
153 public static function save_settings($quiz) {
155 foreach (self
::get_rule_classes() as $rule) {
156 $rule::save_settings($quiz);
161 * Delete any rule-specific settings when the quiz is deleted.
163 * Note that the standard plugins do not use this mechanism because their
164 * settings are stored in the quiz table.
166 * @param object $quiz the data from the database, including $quiz->id
167 * which is the id of the quiz being deleted.
168 * @since Moodle 2.7.1, 2.6.4, 2.5.7
170 public static function delete_settings($quiz) {
172 foreach (self
::get_rule_classes() as $rule) {
173 $rule::delete_settings($quiz);
178 * Build the SQL for loading all the access settings in one go.
179 * @param int $quizid the quiz id.
180 * @param string $basefields initial part of the select list.
181 * @return array with two elements, the sql and the placeholder values.
182 * If $basefields is '' then you must allow for the possibility that
183 * there is no data to load, in which case this method returns $sql = ''.
185 protected static function get_load_sql($quizid, $rules, $basefields) {
186 $allfields = $basefields;
187 $alljoins = '{quiz} quiz';
188 $allparams = array('quizid' => $quizid);
190 foreach ($rules as $rule) {
191 list($fields, $joins, $params) = $rule::get_settings_sql($quizid);
196 $allfields .= $fields;
199 $alljoins .= ' ' . $joins;
202 $allparams +
= $params;
206 if ($allfields === '') {
207 return array('', array());
210 return array("SELECT $allfields FROM $alljoins WHERE quiz.id = :quizid", $allparams);
214 * Load any settings required by the access rules. We try to do this with
217 * Note that the standard plugins do not use this mechanism, becuase all their
218 * settings are stored in the quiz table.
220 * @param int $quizid the quiz id.
221 * @return array setting value name => value. The value names should all
222 * start with the name of the corresponding plugin to avoid collisions.
224 public static function load_settings($quizid) {
227 $rules = self
::get_rule_classes();
228 list($sql, $params) = self
::get_load_sql($quizid, $rules, '');
231 $data = (array) $DB->get_record_sql($sql, $params);
236 foreach ($rules as $rule) {
237 $data +
= $rule::get_extra_settings($quizid);
244 * Load the quiz settings and any settings required by the access rules.
245 * We try to do this with a single DB query.
247 * Note that the standard plugins do not use this mechanism, becuase all their
248 * settings are stored in the quiz table.
250 * @param int $quizid the quiz id.
251 * @return object mdl_quiz row with extra fields.
253 public static function load_quiz_and_settings($quizid) {
256 $rules = self
::get_rule_classes();
257 list($sql, $params) = self
::get_load_sql($quizid, $rules, 'quiz.*');
258 $quiz = $DB->get_record_sql($sql, $params, MUST_EXIST
);
260 foreach ($rules as $rule) {
261 foreach ($rule::get_extra_settings($quizid) as $name => $value) {
262 $quiz->$name = $value;
270 * @return array the class names of all the active rules. Mainly useful for
273 public function get_active_rule_names() {
274 $classnames = array();
275 foreach ($this->rules
as $rule) {
276 $classnames[] = get_class($rule);
282 * Accumulates an array of messages.
283 * @param array $messages the current list of messages.
284 * @param string|array $new the new messages or messages.
285 * @return array the updated array of messages.
287 protected function accumulate_messages($messages, $new) {
288 if (is_array($new)) {
289 $messages = array_merge($messages, $new);
290 } else if (is_string($new) && $new) {
297 * Provide a description of the rules that apply to this quiz, such
298 * as is shown at the top of the quiz view page. Note that not all
299 * rules consider themselves important enough to output a description.
301 * @return array an array of description messages which may be empty. It
302 * would be sensible to output each one surrounded by <p> tags.
304 public function describe_rules() {
306 foreach ($this->rules
as $rule) {
307 $result = $this->accumulate_messages($result, $rule->description());
313 * Whether or not a user should be allowed to start a new attempt at this quiz now.
314 * If there are any restrictions in force now, return an array of reasons why access
315 * should be blocked. If access is OK, return false.
317 * @param int $numattempts the number of previous attempts this user has made.
318 * @param object|false $lastattempt information about the user's last completed attempt.
319 * if there is not a previous attempt, the false is passed.
320 * @return mixed An array of reason why access is not allowed, or an empty array
321 * (== false) if access should be allowed.
323 public function prevent_new_attempt($numprevattempts, $lastattempt) {
325 foreach ($this->rules
as $rule) {
326 $reasons = $this->accumulate_messages($reasons,
327 $rule->prevent_new_attempt($numprevattempts, $lastattempt));
333 * Whether the user should be blocked from starting a new attempt or continuing
334 * an attempt now. If there are any restrictions in force now, return an array
335 * of reasons why access should be blocked. If access is OK, return false.
337 * @return mixed An array of reason why access is not allowed, or an empty array
338 * (== false) if access should be allowed.
340 public function prevent_access() {
342 foreach ($this->rules
as $rule) {
343 $reasons = $this->accumulate_messages($reasons, $rule->prevent_access());
349 * @param int|null $attemptid the id of the current attempt, if there is one,
351 * @return bool whether a check is required before the user starts/continues
354 public function is_preflight_check_required($attemptid) {
355 foreach ($this->rules
as $rule) {
356 if ($rule->is_preflight_check_required($attemptid)) {
364 * Build the form required to do the pre-flight checks.
365 * @param moodle_url $url the form action URL.
366 * @param int|null $attemptid the id of the current attempt, if there is one,
368 * @return mod_quiz_preflight_check_form the form.
370 public function get_preflight_check_form(moodle_url
$url, $attemptid) {
371 return new mod_quiz_preflight_check_form($url->out_omit_querystring(),
372 array('rules' => $this->rules
, 'quizobj' => $this->quizobj
,
373 'attemptid' => $attemptid, 'hidden' => $url->params()));
377 * The pre-flight check has passed. This is a chance to record that fact in
379 * @param int|null $attemptid the id of the current attempt, if there is one,
382 public function notify_preflight_check_passed($attemptid) {
383 foreach ($this->rules
as $rule) {
384 $rule->notify_preflight_check_passed($attemptid);
389 * Inform the rules that the current attempt is finished. This is use, for example
390 * by the password rule, to clear the flag in the session.
392 public function current_attempt_finished() {
393 foreach ($this->rules
as $rule) {
394 $rule->current_attempt_finished();
399 * Do any of the rules mean that this student will no be allowed any further attempts at this
400 * quiz. Used, for example, to change the label by the grade displayed on the view page from
401 * 'your current grade is' to 'your final grade is'.
403 * @param int $numattempts the number of previous attempts this user has made.
404 * @param object $lastattempt information about the user's last completed attempt.
405 * @return bool true if there is no way the user will ever be allowed to attempt
408 public function is_finished($numprevattempts, $lastattempt) {
409 foreach ($this->rules
as $rule) {
410 if ($rule->is_finished($numprevattempts, $lastattempt)) {
418 * Sets up the attempt (review or summary) page with any properties required
419 * by the access rules.
421 * @param moodle_page $page the page object to initialise.
423 public function setup_attempt_page($page) {
424 foreach ($this->rules
as $rule) {
425 $rule->setup_attempt_page($page);
430 * Compute when the attempt must be submitted.
432 * @param object $attempt the data from the relevant quiz_attempts row.
433 * @return int|false the attempt close time.
434 * False if there is no limit.
436 public function get_end_time($attempt) {
438 foreach ($this->rules
as $rule) {
439 $ruletimeclose = $rule->end_time($attempt);
440 if ($ruletimeclose !== false && ($timeclose === false ||
$ruletimeclose < $timeclose)) {
441 $timeclose = $ruletimeclose;
448 * Compute what should be displayed to the user for time remaining in this attempt.
450 * @param object $attempt the data from the relevant quiz_attempts row.
451 * @param int $timenow the time to consider as 'now'.
452 * @return int|false the number of seconds remaining for this attempt.
453 * False if no limit should be displayed.
455 public function get_time_left_display($attempt, $timenow) {
457 foreach ($this->rules
as $rule) {
458 $ruletimeleft = $rule->time_left_display($attempt, $timenow);
459 if ($ruletimeleft !== false && ($timeleft === false ||
$ruletimeleft < $timeleft)) {
460 $timeleft = $ruletimeleft;
467 * @return bolean if this quiz should only be shown to students in a popup window.
469 public function attempt_must_be_in_popup() {
470 foreach ($this->rules
as $rule) {
471 if ($rule->attempt_must_be_in_popup()) {
479 * @return array any options that are required for showing the attempt page
482 public function get_popup_options() {
484 foreach ($this->rules
as $rule) {
485 $options +
= $rule->get_popup_options();
491 * Send the user back to the quiz view page. Normally this is just a redirect, but
492 * If we were in a secure window, we close this window, and reload the view window we came from.
494 * This method does not return;
496 * @param mod_quiz_renderer $output the quiz renderer.
497 * @param string $message optional message to output while redirecting.
499 public function back_to_view_page($output, $message = '') {
500 if ($this->attempt_must_be_in_popup()) {
501 echo $output->close_attempt_popup($this->quizobj
->view_url(), $message);
504 redirect($this->quizobj
->view_url(), $message);
509 * Make some text into a link to review the quiz, if that is appropriate.
511 * @param string $linktext some text.
512 * @param object $attempt the attempt object
513 * @return string some HTML, the $linktext either unmodified or wrapped in a
514 * link to the review page.
516 public function make_review_link($attempt, $reviewoptions, $output) {
518 // If the attempt is still open, don't link.
519 if (in_array($attempt->state
, array(quiz_attempt
::IN_PROGRESS
, quiz_attempt
::OVERDUE
))) {
520 return $output->no_review_message('');
523 $when = quiz_attempt_state($this->quizobj
->get_quiz(), $attempt);
524 $reviewoptions = mod_quiz_display_options
::make_from_quiz(
525 $this->quizobj
->get_quiz(), $when);
527 if (!$reviewoptions->attempt
) {
528 return $output->no_review_message($this->quizobj
->cannot_review_message($when, true));
531 return $output->review_link($this->quizobj
->review_url($attempt->id
),
532 $this->attempt_must_be_in_popup(), $this->get_popup_options());