completion/completion_completion.php

   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             $event = \core\event\course_completed::create(
 165                 array(
 166                     'objectid' => $data->id,
 167                     'userid' => $USER->id,
 168                     'context' => context_course::instance($data->course),
 169                     'courseid' => $data->course,
 170                     'other' => array('relateduserid' => $data->userid)
 171                     )
 172                 );
 173             $event->add_record_snapshot('course_completions', $data);
 174             $event->trigger();
 175         }
 176
 177         return $result;
 178     }
 179
 180     /**
 181      * Save course completion status
 182      *
 183      * This method creates a course_completions record if none exists
 184      * @access  private
 185      * @return  bool
 186      */
 187     private function _save() {
 188         if ($this->timeenrolled === null) {
 189             $this->timeenrolled = 0;
 190         }
 191
 192         // Save record
 193         if ($this->id) {
 194             return $this->update();
 195         } else {
 196             // Make sure reaggregate field is not null
 197             if (!$this->reaggregate) {
 198                 $this->reaggregate = 0;
 199             }
 200
 201             // Make sure timestarted is not null
 202             if (!$this->timestarted) {
 203                 $this->timestarted = 0;
 204             }
 205
 206             return $this->insert();
 207         }
 208     }
 209 }