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/>.
  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->libdir.'/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', 'deleted', 'timenotified',
  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 $deleted set to 1 if this record has been deleted */
  55     public $deleted;
  56
  57     /* @var int Timestamp the interested parties were notified of this user's completion. */
  58     public $timenotified;
  59
  60     /* @var int Time of course enrolment {@link completion_completion::mark_enrolled()} */
  61     public $timeenrolled;
  62
  63     /**
  64      * Time the user started their course completion {@link completion_completion::mark_inprogress()}
  65      * @var int
  66      */
  67     public $timestarted;
  68
  69     /* @var int Timestamp of course completion {@link completion_completion::mark_complete()} */
  70     public $timecompleted;
  71
  72     /* @var int Flag to trigger cron aggregation (timestamp) */
  73     public $reaggregate;
  74
  75
  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     }
  86
  87     /**
  88      * Return status of this completion
  89      *
  90      * @return bool
  91      */
  92     public function is_complete() {
  93         return (bool) $this->timecompleted;
  94     }
  95
  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) {
 104
 105         if ($this->timeenrolled === null) {
 106
 107             if ($timeenrolled === null) {
 108                 $timeenrolled = time();
 109             }
 110
 111             $this->timeenrolled = $timeenrolled;
 112         }
 113
 114         return $this->_save();
 115     }
 116
 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) {
 125
 126         $timenow = time();
 127
 128         // Set reaggregate flag
 129         $this->reaggregate = $timenow;
 130
 131         if (!$this->timestarted) {
 132
 133             if (!$timestarted) {
 134                 $timestarted = $timenow;
 135             }
 136
 137             $this->timestarted = $timestarted;
 138         }
 139
 140         return $this->_save();
 141     }
 142
 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) {
 153
 154         // Never change a completion time
 155         if ($this->timecompleted) {
 156             return;
 157         }
 158
 159         // Use current time if nothing supplied
 160         if (!$timecomplete) {
 161             $timecomplete = time();
 162         }
 163
 164         // Set time complete
 165         $this->timecompleted = $timecomplete;
 166
 167         // Save record
 168         return $this->_save();
 169     }
 170
 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         }
 182
 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             }
 191
 192             // Make sure timestarted is not null
 193             if (!$this->timestarted) {
 194                 $this->timestarted = 0;
 195             }
 196
 197             return $this->insert();
 198         }
 199     }
 200 }