Merge branch 'MDL-64784' of https://github.com/paulholden/moodle
[moodle.git] / 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/>.
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  */
27 defined('MOODLE_INTERNAL') || die();
28 require_once($CFG->dirroot.'/completion/data_object.php');
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 {
41     /* @var string $table Database table name that stores completion information */
42     public $table = 'course_completions';
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');
48     /* @var int $userid User ID */
49     public $userid;
51     /* @var int $course Course ID */
52     public $course;
54     /* @var int Time of course enrolment {@link completion_completion::mark_enrolled()} */
55     public $timeenrolled;
57     /**
58      * Time the user started their course completion {@link completion_completion::mark_inprogress()}
59      * @var int
60      */
61     public $timestarted;
63     /* @var int Timestamp of course completion {@link completion_completion::mark_complete()} */
64     public $timecompleted;
66     /* @var int Flag to trigger cron aggregation (timestamp) */
67     public $reaggregate;
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         $cache = cache::make('core', 'coursecompletion');
79         $key = $params['userid'] . '_' . $params['course'];
80         if ($hit = $cache->get($key)) {
81             return $hit['value'];
82         }
84         $tocache = self::fetch_helper('course_completions', __CLASS__, $params);
85         $cache->set($key, ['value' => $tocache]);
86         return $tocache;
87     }
89     /**
90      * Return status of this completion
91      *
92      * @return bool
93      */
94     public function is_complete() {
95         return (bool) $this->timecompleted;
96     }
98     /**
99      * Mark this user as started (or enrolled) in this course
100      *
101      * If the user is already marked as started, no change will occur
102      *
103      * @param integer $timeenrolled Time enrolled (optional)
104      */
105     public function mark_enrolled($timeenrolled = null) {
107         if ($this->timeenrolled === null) {
109             if ($timeenrolled === null) {
110                 $timeenrolled = time();
111             }
113             $this->timeenrolled = $timeenrolled;
114         }
116         return $this->_save();
117     }
119     /**
120      * Mark this user as inprogress in this course
121      *
122      * If the user is already marked as inprogress, the time will not be changed
123      *
124      * @param integer $timestarted Time started (optional)
125      */
126     public function mark_inprogress($timestarted = null) {
128         $timenow = time();
130         // Set reaggregate flag
131         $this->reaggregate = $timenow;
133         if (!$this->timestarted) {
135             if (!$timestarted) {
136                 $timestarted = $timenow;
137             }
139             $this->timestarted = $timestarted;
140         }
142         return $this->_save();
143     }
145     /**
146      * Mark this user complete in this course
147      *
148      * This generally happens when the required completion criteria
149      * in the course are complete.
150      *
151      * @param integer $timecomplete Time completed (optional)
152      * @return void
153      */
154     public function mark_complete($timecomplete = null) {
155         global $USER;
157         // Never change a completion time.
158         if ($this->timecompleted) {
159             return;
160         }
162         // Use current time if nothing supplied.
163         if (!$timecomplete) {
164             $timecomplete = time();
165         }
167         // Set time complete.
168         $this->timecompleted = $timecomplete;
170         // Save record.
171         if ($result = $this->_save()) {
172             $data = $this->get_record_data();
173             \core\event\course_completed::create_from_completion($data)->trigger();
174         }
176         return $result;
177     }
179     /**
180      * Save course completion status
181      *
182      * This method creates a course_completions record if none exists
183      * @access  private
184      * @return  bool
185      */
186     private function _save() {
187         if ($this->timeenrolled === null) {
188             $this->timeenrolled = 0;
189         }
191         $result = false;
192         // Save record
193         if ($this->id) {
194             $result = $this->update();
195         } else {
196             // Make sure reaggregate field is not null
197             if (!$this->reaggregate) {
198                 $this->reaggregate = 0;
199             }
201             // Make sure timestarted is not null
202             if (!$this->timestarted) {
203                 $this->timestarted = 0;
204             }
206             $result = $this->insert();
207         }
209         if ($result) {
210             // Update the cached record.
211             $cache = cache::make('core', 'coursecompletion');
212             $data = $this->get_record_data();
213             $key = $data->userid . '_' . $data->course;
214             $cache->set($key, ['value' => $data]);
215         }
217         return $result;
218     }