e6523eadf263828a517fc6668dbc4dec06c513ab
[moodle.git] / lib / 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->libdir.'/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', 'deleted', 'timenotified',
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 $deleted set to 1 if this record has been deleted */
55     public $deleted;
57     /* @var int Timestamp the interested parties were notified of this user's completion. */
58     public $timenotified;
60     /* @var int Time of course enrolment {@link completion_completion::mark_enrolled()} */
61     public $timeenrolled;
63     /**
64      * Time the user started their course completion {@link completion_completion::mark_inprogress()}
65      * @var int
66      */
67     public $timestarted;
69     /* @var int Timestamp of course completion {@link completion_completion::mark_complete()} */
70     public $timecompleted;
72     /* @var int Flag to trigger cron aggregation (timestamp) */
73     public $reaggregate;
76     /**
77      * Finds and returns a data_object instance based on params.
78      *
79      * @param array $params associative arrays varname = >value
80      * @return data_object instance of data_object or false if none found.
81      */
82     public static function fetch($params) {
83         $params['deleted'] = null;
84         return self::fetch_helper('course_completions', __CLASS__, $params);
85     }
87     /**
88      * Return status of this completion
89      *
90      * @return bool
91      */
92     public function is_complete() {
93         return (bool) $this->timecompleted;
94     }
96     /**
97      * Mark this user as started (or enrolled) in this course
98      *
99      * If the user is already marked as started, no change will occur
100      *
101      * @param integer $timeenrolled Time enrolled (optional)
102      */
103     public function mark_enrolled($timeenrolled = null) {
105         if ($this->timeenrolled === null) {
107             if ($timeenrolled === null) {
108                 $timeenrolled = time();
109             }
111             $this->timeenrolled = $timeenrolled;
112         }
114         return $this->_save();
115     }
117     /**
118      * Mark this user as inprogress in this course
119      *
120      * If the user is already marked as inprogress, the time will not be changed
121      *
122      * @param integer $timestarted Time started (optional)
123      */
124     public function mark_inprogress($timestarted = null) {
126         $timenow = time();
128         // Set reaggregate flag
129         $this->reaggregate = $timenow;
131         if (!$this->timestarted) {
133             if (!$timestarted) {
134                 $timestarted = $timenow;
135             }
137             $this->timestarted = $timestarted;
138         }
140         return $this->_save();
141     }
143     /**
144      * Mark this user complete in this course
145      *
146      * This generally happens when the required completion criteria
147      * in the course are complete.
148      *
149      * @param integer $timecomplete Time completed (optional)
150      * @return void
151      */
152     public function mark_complete($timecomplete = null) {
154         // Never change a completion time
155         if ($this->timecompleted) {
156             return;
157         }
159         // Use current time if nothing supplied
160         if (!$timecomplete) {
161             $timecomplete = time();
162         }
164         // Set time complete
165         $this->timecompleted = $timecomplete;
167         // Save record
168         return $this->_save();
169     }
171     /**
172      * Save course completion status
173      *
174      * This method creates a course_completions record if none exists
175      * @access  private
176      * @return  bool
177      */
178     private function _save() {
179         if ($this->timeenrolled === null) {
180             $this->timeenrolled = 0;
181         }
183         // Save record
184         if ($this->id) {
185             return $this->update();
186         } else {
187             // Make sure reaggregate field is not null
188             if (!$this->reaggregate) {
189                 $this->reaggregate = 0;
190             }
192             // Make sure timestarted is not null
193             if (!$this->timestarted) {
194                 $this->timestarted = 0;
195             }
197             return $this->insert();
198         }
199     }