[Summary view] [Print] [Text view]

   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  /**
  18   * Cron job for reviewing and aggregating course completion criteria
  19   *
  20   * @package core_completion
  21   * @category completion
  22   * @copyright 2009 Catalyst IT Ltd
  23   * @author Aaron Barnes <[email protected]>
  24   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  require_once($CFG->libdir.'/completionlib.php');
  29  
  30  /**
  31   * Update user's course completion statuses
  32   *
  33   * First update all criteria completions, then aggregate all criteria completions
  34   * and update overall course completions
  35   */
  36  function completion_cron() {
  37  
  38      completion_cron_mark_started();
  39  
  40      completion_cron_criteria();
  41  
  42      completion_cron_completions();
  43  }
  44  
  45  /**
  46   * Mark users as started if the config option is set
  47   *
  48   * @return void
  49   */
  50  function completion_cron_mark_started() {
  51      global $CFG, $DB;
  52  
  53      if (debugging()) {
  54          mtrace('Marking users as started');
  55      }
  56  
  57      if (!empty($CFG->gradebookroles)) {
  58          $roles = ' AND ra.roleid IN ('.$CFG->gradebookroles.')';
  59      } else {
  60          // This causes it to default to everyone (if there is no student role)
  61          $roles = '';
  62      }
  63  
  64      /**
  65       * A quick explaination of this horrible looking query
  66       *
  67       * It's purpose is to locate all the active participants
  68       * of a course with course completion enabled.
  69       *
  70       * We also only want the users with no course_completions
  71       * record as this functions job is to create the missing
  72       * ones :)
  73       *
  74       * We want to record the user's enrolment start time for the
  75       * course. This gets tricky because there can be multiple
  76       * enrolment plugins active in a course, hence the possibility
  77       * of multiple records for each couse/user in the results
  78       */
  79      $sql = "
  80          SELECT
  81              c.id AS course,
  82              u.id AS userid,
  83              crc.id AS completionid,
  84              ue.timestart AS timeenrolled,
  85              ue.timecreated
  86          FROM
  87              {user} u
  88          INNER JOIN
  89              {user_enrolments} ue
  90           ON ue.userid = u.id
  91          INNER JOIN
  92              {enrol} e
  93           ON e.id = ue.enrolid
  94          INNER JOIN
  95              {course} c
  96           ON c.id = e.courseid
  97          INNER JOIN
  98              {role_assignments} ra
  99           ON ra.userid = u.id
 100          LEFT JOIN
 101              {course_completions} crc
 102           ON crc.course = c.id
 103          AND crc.userid = u.id
 104          WHERE
 105              c.enablecompletion = 1
 106          AND crc.timeenrolled IS NULL
 107          AND ue.status = 0
 108          AND e.status = 0
 109          AND u.deleted = 0
 110          AND ue.timestart < ?
 111          AND (ue.timeend > ? OR ue.timeend = 0)
 112              $roles
 113          ORDER BY
 114              course,
 115              userid
 116      ";
 117  
 118      $now = time();
 119      $rs = $DB->get_recordset_sql($sql, array($now, $now, $now, $now));
 120  
 121      // Check if result is empty
 122      if (!$rs->valid()) {
 123          $rs->close(); // Not going to iterate (but exit), close rs
 124          return;
 125      }
 126  
 127      /**
 128       * An explaination of the following loop
 129       *
 130       * We are essentially doing a group by in the code here (as I can't find
 131       * a decent way of doing it in the sql).
 132       *
 133       * Since there can be multiple enrolment plugins for each course, we can have
 134       * multiple rows for each particpant in the query result. This isn't really
 135       * a problem until you combine it with the fact that the enrolment plugins
 136       * can save the enrol start time in either timestart or timeenrolled.
 137       *
 138       * The purpose of this loop is to find the earliest enrolment start time for
 139       * each participant in each course.
 140       */
 141      $prev = null;
 142      while ($rs->valid() || $prev) {
 143  
 144          $current = $rs->current();
 145  
 146          if (!isset($current->course)) {
 147              $current = false;
 148          }
 149          else {
 150              // Not all enrol plugins fill out timestart correctly, so use whichever
 151              // is non-zero
 152              $current->timeenrolled = max($current->timecreated, $current->timeenrolled);
 153          }
 154  
 155          // If we are at the last record,
 156          // or we aren't at the first and the record is for a diff user/course
 157          if ($prev &&
 158              (!$rs->valid() ||
 159              ($current->course != $prev->course || $current->userid != $prev->userid))) {
 160  
 161              $completion = new completion_completion();
 162              $completion->userid = $prev->userid;
 163              $completion->course = $prev->course;
 164              $completion->timeenrolled = (string) $prev->timeenrolled;
 165              $completion->timestarted = 0;
 166              $completion->reaggregate = time();
 167  
 168              if ($prev->completionid) {
 169                  $completion->id = $prev->completionid;
 170              }
 171  
 172              $completion->mark_enrolled();
 173  
 174              if (debugging()) {
 175                  mtrace('Marked started user '.$prev->userid.' in course '.$prev->course);
 176              }
 177          }
 178          // Else, if this record is for the same user/course
 179          elseif ($prev && $current) {
 180              // Use oldest timeenrolled
 181              $current->timeenrolled = min($current->timeenrolled, $prev->timeenrolled);
 182          }
 183  
 184          // Move current record to previous
 185          $prev = $current;
 186  
 187          // Move to next record
 188          $rs->next();
 189      }
 190  
 191      $rs->close();
 192  }
 193  
 194  /**
 195   * Run installed criteria's data aggregation methods
 196   *
 197   * Loop through each installed criteria and run the
 198   * cron() method if it exists
 199   *
 200   * @return void
 201   */
 202  function completion_cron_criteria() {
 203  
 204      // Process each criteria type
 205      global $CFG, $COMPLETION_CRITERIA_TYPES;
 206  
 207      foreach ($COMPLETION_CRITERIA_TYPES as $type) {
 208  
 209          $object = 'completion_criteria_'.$type;
 210          require_once $CFG->dirroot.'/completion/criteria/'.$object.'.php';
 211  
 212          $class = new $object();
 213  
 214          // Run the criteria type's cron method, if it has one
 215          if (method_exists($class, 'cron')) {
 216  
 217              if (debugging()) {
 218                  mtrace('Running '.$object.'->cron()');
 219              }
 220              $class->cron();
 221          }
 222      }
 223  }
 224  
 225  /**
 226   * Aggregate each user's criteria completions
 227   */
 228  function completion_cron_completions() {
 229      global $DB;
 230  
 231      if (debugging()) {
 232          mtrace('Aggregating completions');
 233      }
 234  
 235      // Save time started
 236      $timestarted = time();
 237  
 238      // Grab all criteria and their associated criteria completions
 239      $sql = '
 240          SELECT DISTINCT
 241              c.id AS course,
 242              cr.id AS criteriaid,
 243              crc.userid AS userid,
 244              cr.criteriatype AS criteriatype,
 245              cc.timecompleted AS timecompleted
 246          FROM
 247              {course_completion_criteria} cr
 248          INNER JOIN
 249              {course} c
 250           ON cr.course = c.id
 251          INNER JOIN
 252              {course_completions} crc
 253           ON crc.course = c.id
 254          LEFT JOIN
 255              {course_completion_crit_compl} cc
 256           ON cc.criteriaid = cr.id
 257          AND crc.userid = cc.userid
 258          WHERE
 259              c.enablecompletion = 1
 260          AND crc.timecompleted IS NULL
 261          AND crc.reaggregate > 0
 262          AND crc.reaggregate < :timestarted
 263          ORDER BY
 264              course,
 265              userid
 266      ';
 267  
 268      $rs = $DB->get_recordset_sql($sql, array('timestarted' => $timestarted));
 269  
 270      // Check if result is empty
 271      if (!$rs->valid()) {
 272          $rs->close(); // Not going to iterate (but exit), close rs
 273          return;
 274      }
 275  
 276      $current_user = null;
 277      $current_course = null;
 278      $completions = array();
 279  
 280      while (1) {
 281  
 282          // Grab records for current user/course
 283          foreach ($rs as $record) {
 284              // If we are still grabbing the same users completions
 285              if ($record->userid === $current_user && $record->course === $current_course) {
 286                  $completions[$record->criteriaid] = $record;
 287              } else {
 288                  break;
 289              }
 290          }
 291  
 292          // Aggregate
 293          if (!empty($completions)) {
 294  
 295              if (debugging()) {
 296                  mtrace('Aggregating completions for user '.$current_user.' in course '.$current_course);
 297              }
 298  
 299              // Get course info object
 300              $info = new completion_info((object)array('id' => $current_course));
 301  
 302              // Setup aggregation
 303              $overall = $info->get_aggregation_method();
 304              $activity = $info->get_aggregation_method(COMPLETION_CRITERIA_TYPE_ACTIVITY);
 305              $prerequisite = $info->get_aggregation_method(COMPLETION_CRITERIA_TYPE_COURSE);
 306              $role = $info->get_aggregation_method(COMPLETION_CRITERIA_TYPE_ROLE);
 307  
 308              $overall_status = null;
 309              $activity_status = null;
 310              $prerequisite_status = null;
 311              $role_status = null;
 312  
 313              // Get latest timecompleted
 314              $timecompleted = null;
 315  
 316              // Check each of the criteria
 317              foreach ($completions as $params) {
 318                  $timecompleted = max($timecompleted, $params->timecompleted);
 319  
 320                  $completion = new completion_criteria_completion((array)$params, false);
 321  
 322                  // Handle aggregation special cases
 323                  if ($params->criteriatype == COMPLETION_CRITERIA_TYPE_ACTIVITY) {
 324                      completion_cron_aggregate($activity, $completion->is_complete(), $activity_status);
 325                  } else if ($params->criteriatype == COMPLETION_CRITERIA_TYPE_COURSE) {
 326                      completion_cron_aggregate($prerequisite, $completion->is_complete(), $prerequisite_status);
 327                  } else if ($params->criteriatype == COMPLETION_CRITERIA_TYPE_ROLE) {
 328                      completion_cron_aggregate($role, $completion->is_complete(), $role_status);
 329                  } else {
 330                      completion_cron_aggregate($overall, $completion->is_complete(), $overall_status);
 331                  }
 332              }
 333  
 334              // Include role criteria aggregation in overall aggregation
 335              if ($role_status !== null) {
 336                  completion_cron_aggregate($overall, $role_status, $overall_status);
 337              }
 338  
 339              // Include activity criteria aggregation in overall aggregation
 340              if ($activity_status !== null) {
 341                  completion_cron_aggregate($overall, $activity_status, $overall_status);
 342              }
 343  
 344              // Include prerequisite criteria aggregation in overall aggregation
 345              if ($prerequisite_status !== null) {
 346                  completion_cron_aggregate($overall, $prerequisite_status, $overall_status);
 347              }
 348  
 349              // If aggregation status is true, mark course complete for user
 350              if ($overall_status) {
 351                  if (debugging()) {
 352                      mtrace('Marking complete');
 353                  }
 354  
 355                  $ccompletion = new completion_completion(array('course' => $params->course, 'userid' => $params->userid));
 356                  $ccompletion->mark_complete($timecompleted);
 357              }
 358          }
 359  
 360          // If this is the end of the recordset, break the loop
 361          if (!$rs->valid()) {
 362              $rs->close();
 363              break;
 364          }
 365  
 366          // New/next user, update user details, reset completions
 367          $current_user = $record->userid;
 368          $current_course = $record->course;
 369          $completions = array();
 370          $completions[$record->criteriaid] = $record;
 371      }
 372  
 373      // Mark all users as aggregated
 374      $sql = "
 375          UPDATE
 376              {course_completions}
 377          SET
 378              reaggregate = 0
 379          WHERE
 380              reaggregate < :timestarted
 381          AND reaggregate > 0
 382      ";
 383  
 384      $DB->execute($sql, array('timestarted' => $timestarted));
 385  }
 386  
 387  /**
 388   * Aggregate criteria status's as per configured aggregation method
 389   *
 390   * @param int $method COMPLETION_AGGREGATION_* constant
 391   * @param bool $data Criteria completion status
 392   * @param bool|null $state Aggregation state
 393   */
 394  function completion_cron_aggregate($method, $data, &$state) {
 395      if ($method == COMPLETION_AGGREGATION_ALL) {
 396          if ($data && $state !== false) {
 397              $state = true;
 398          } else {
 399              $state = false;
 400          }
 401      } elseif ($method == COMPLETION_AGGREGATION_ANY) {
 402          if ($data) {
 403              $state = true;
 404          } else if (!$data && $state === null) {
 405              $state = false;
 406          }
 407      }
 408  }