[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   * Course completion status for a particular user/course
  19   *
  20   * @package core_completion
  21   * @category completion
  22   * @copyright 2009 Catalyst IT Ltd
  23   * @author Aaron Barnes <aaronb@catalyst.net.nz>
  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->dirroot.'/completion/data_object.php');
  29  
  30  /**
  31   * Course completion status for a particular user/course
  32   *
  33   * @package core_completion
  34   * @category completion
  35   * @copyright 2009 Catalyst IT Ltd
  36   * @author Aaron Barnes <aaronb@catalyst.net.nz>
  37   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   */
  39  class completion_completion extends data_object {
  40  
  41      /* @var string $table Database table name that stores completion information */
  42      public $table = 'course_completions';
  43  
  44      /* @var array $required_fields Array of required table fields, must start with 'id'. */
  45      public $required_fields = array('id', 'userid', 'course',
  46          'timeenrolled', 'timestarted', 'timecompleted', 'reaggregate');
  47  
  48      /* @var int $userid User ID */
  49      public $userid;
  50  
  51      /* @var int $course Course ID */
  52      public $course;
  53  
  54      /* @var int Time of course enrolment {@link completion_completion::mark_enrolled()} */
  55      public $timeenrolled;
  56  
  57      /**
  58       * Time the user started their course completion {@link completion_completion::mark_inprogress()}
  59       * @var int
  60       */
  61      public $timestarted;
  62  
  63      /* @var int Timestamp of course completion {@link completion_completion::mark_complete()} */
  64      public $timecompleted;
  65  
  66      /* @var int Flag to trigger cron aggregation (timestamp) */
  67      public $reaggregate;
  68  
  69  
  70      /**
  71       * Finds and returns a data_object instance based on params.
  72       *
  73       * @param array $params associative arrays varname = >value
  74       * @return data_object instance of data_object or false if none found.
  75       */
  76      public static function fetch($params) {
  77          return self::fetch_helper('course_completions', __CLASS__, $params);
  78      }
  79  
  80      /**
  81       * Return status of this completion
  82       *
  83       * @return bool
  84       */
  85      public function is_complete() {
  86          return (bool) $this->timecompleted;
  87      }
  88  
  89      /**
  90       * Mark this user as started (or enrolled) in this course
  91       *
  92       * If the user is already marked as started, no change will occur
  93       *
  94       * @param integer $timeenrolled Time enrolled (optional)
  95       */
  96      public function mark_enrolled($timeenrolled = null) {
  97  
  98          if ($this->timeenrolled === null) {
  99  
 100              if ($timeenrolled === null) {
 101                  $timeenrolled = time();
 102              }
 103  
 104              $this->timeenrolled = $timeenrolled;
 105          }
 106  
 107          return $this->_save();
 108      }
 109  
 110      /**
 111       * Mark this user as inprogress in this course
 112       *
 113       * If the user is already marked as inprogress, the time will not be changed
 114       *
 115       * @param integer $timestarted Time started (optional)
 116       */
 117      public function mark_inprogress($timestarted = null) {
 118  
 119          $timenow = time();
 120  
 121          // Set reaggregate flag
 122          $this->reaggregate = $timenow;
 123  
 124          if (!$this->timestarted) {
 125  
 126              if (!$timestarted) {
 127                  $timestarted = $timenow;
 128              }
 129  
 130              $this->timestarted = $timestarted;
 131          }
 132  
 133          return $this->_save();
 134      }
 135  
 136      /**
 137       * Mark this user complete in this course
 138       *
 139       * This generally happens when the required completion criteria
 140       * in the course are complete.
 141       *
 142       * @param integer $timecomplete Time completed (optional)
 143       * @return void
 144       */
 145      public function mark_complete($timecomplete = null) {
 146          global $USER;
 147  
 148          // Never change a completion time.
 149          if ($this->timecompleted) {
 150              return;
 151          }
 152  
 153          // Use current time if nothing supplied.
 154          if (!$timecomplete) {
 155              $timecomplete = time();
 156          }
 157  
 158          // Set time complete.
 159          $this->timecompleted = $timecomplete;
 160  
 161          // Save record.
 162          if ($result = $this->_save()) {
 163              $data = $this->get_record_data();
 164              \core\event\course_completed::create_from_completion($data)->trigger();
 165          }
 166  
 167          return $result;
 168      }
 169  
 170      /**
 171       * Save course completion status
 172       *
 173       * This method creates a course_completions record if none exists
 174       * @access  private
 175       * @return  bool
 176       */
 177      private function _save() {
 178          if ($this->timeenrolled === null) {
 179              $this->timeenrolled = 0;
 180          }
 181  
 182          // Save record
 183          if ($this->id) {
 184              return $this->update();
 185          } else {
 186              // Make sure reaggregate field is not null
 187              if (!$this->reaggregate) {
 188                  $this->reaggregate = 0;
 189              }
 190  
 191              // Make sure timestarted is not null
 192              if (!$this->timestarted) {
 193                  $this->timestarted = 0;
 194              }
 195  
 196              return $this->insert();
 197          }
 198      }
 199  }