Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 311 and 401] [Versions 401 and 402] [Versions 401 and 403]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   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.
   8  //
   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.
  13  //
  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/>.
  16  
  17  declare(strict_types=1);
  18  
  19  namespace mod_quiz\completion;
  20  
  21  use context_module;
  22  use core_completion\activity_custom_completion;
  23  use grade_grade;
  24  use grade_item;
  25  use quiz;
  26  use quiz_access_manager;
  27  
  28  /**
  29   * Activity custom completion subclass for the quiz activity.
  30   *
  31   * Class for defining mod_quiz's custom completion rules and fetching the completion statuses
  32   * of the custom completion rules for a given quiz instance and a user.
  33   *
  34   * @package   mod_quiz
  35   * @copyright 2021 Shamim Rezaie <shamim@moodle.com>
  36   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37   */
  38  class custom_completion extends activity_custom_completion {
  39  
  40      /**
  41       * Check passing grade (or no attempts left) requirement for completion.
  42       *
  43       * @return bool True if the passing grade (or no attempts left) requirement is disabled or met.
  44       */
  45      protected function check_passing_grade_or_all_attempts(): bool {
  46          global $CFG;
  47          require_once($CFG->libdir . '/gradelib.php');
  48  
  49          $completionpassorattempts = $this->cm->customdata['customcompletionrules']['completionpassorattemptsexhausted'];
  50  
  51          if (empty($completionpassorattempts['completionpassgrade'])) {
  52              return true;
  53          }
  54  
  55          if ($this->completionstate &&
  56                  isset($this->completionstate['passgrade']) &&
  57                  $this->completionstate['passgrade'] == COMPLETION_COMPLETE_PASS) {
  58              return true;
  59          }
  60  
  61          // If a passing grade is required and exhausting all available attempts is not accepted for completion,
  62          // then this quiz is not complete.
  63          if (empty($completionpassorattempts['completionattemptsexhausted'])) {
  64              return false;
  65          }
  66  
  67          // Check if all attempts are used up.
  68          $attempts = quiz_get_user_attempts($this->cm->instance, $this->userid, 'finished', true);
  69          if (!$attempts) {
  70              return false;
  71          }
  72          $lastfinishedattempt = end($attempts);
  73          $context = context_module::instance($this->cm->id);
  74          $quizobj = quiz::create($this->cm->instance, $this->userid);
  75          $accessmanager = new quiz_access_manager(
  76              $quizobj,
  77              time(),
  78              has_capability('mod/quiz:ignoretimelimits', $context, $this->userid, false)
  79          );
  80  
  81          return $accessmanager->is_finished(count($attempts), $lastfinishedattempt);
  82      }
  83  
  84      /**
  85       * Check minimum attempts requirement for completion.
  86       *
  87       * @return bool True if minimum attempts requirement is disabled or met.
  88       */
  89      protected function check_min_attempts() {
  90          $minattempts = $this->cm->customdata['customcompletionrules']['completionminattempts'];
  91          if (!$minattempts) {
  92              return true;
  93          }
  94  
  95          // Check if the user has done enough attempts.
  96          $attempts = quiz_get_user_attempts($this->cm->instance, $this->userid, 'finished', true);
  97          return $minattempts <= count($attempts);
  98      }
  99  
 100      /**
 101       * Fetches the completion state for a given completion rule.
 102       *
 103       * @param string $rule The completion rule.
 104       * @return int The completion state.
 105       */
 106      public function get_state(string $rule): int {
 107          $this->validate_rule($rule);
 108  
 109          switch ($rule) {
 110              case 'completionpassorattemptsexhausted':
 111                  $status = static::check_passing_grade_or_all_attempts();
 112                  break;
 113              case 'completionminattempts':
 114                  $status = static::check_min_attempts();
 115                  break;
 116          }
 117  
 118          return empty($status) ? COMPLETION_INCOMPLETE : COMPLETION_COMPLETE;
 119      }
 120  
 121      /**
 122       * Fetch the list of custom completion rules that this module defines.
 123       *
 124       * @return array
 125       */
 126      public static function get_defined_custom_rules(): array {
 127          return [
 128              'completionpassorattemptsexhausted',
 129              'completionminattempts',
 130          ];
 131      }
 132  
 133      /**
 134       * Returns an associative array of the descriptions of custom completion rules.
 135       *
 136       * @return array
 137       */
 138      public function get_custom_rule_descriptions(): array {
 139          $minattempts = $this->cm->customdata['customcompletionrules']['completionminattempts'] ?? 0;
 140          $description['completionminattempts'] = get_string('completiondetail:minattempts', 'mod_quiz', $minattempts);
 141  
 142          // Completion pass grade is now part of core. Only show the following if it's combined with min attempts.
 143          $completionpassorattempts = $this->cm->customdata['customcompletionrules']['completionpassorattemptsexhausted'] ?? [];
 144          if (!empty($completionpassorattempts['completionattemptsexhausted'])) {
 145              $description['completionpassorattemptsexhausted'] = get_string('completiondetail:passorexhaust', 'mod_quiz');
 146          }
 147  
 148          return $description;
 149      }
 150  
 151      /**
 152       * Returns an array of all completion rules, in the order they should be displayed to users.
 153       *
 154       * @return array
 155       */
 156      public function get_sort_order(): array {
 157          return [
 158              'completionview',
 159              'completionminattempts',
 160              'completionusegrade',
 161              'completionpassgrade',
 162              'completionpassorattemptsexhausted',
 163          ];
 164      }
 165  }