MDL-65276 core: fix CiBoT complains
[moodle.git] / completion / criteria / completion_criteria.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 criteria
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');
29 require_once($CFG->dirroot.'/completion/completion_criteria_completion.php');
31 /**
32  * Self completion criteria type
33  * Criteria type constant, primarily for storing criteria type in the database.
34  */
35 define('COMPLETION_CRITERIA_TYPE_SELF',         1);
37 /**
38  * Date completion criteria type
39  * Criteria type constant, primarily for storing criteria type in the database.
40  */
41 define('COMPLETION_CRITERIA_TYPE_DATE',         2);
43 /**
44  * Unenrol completion criteria type
45  * Criteria type constant, primarily for storing criteria type in the database.
46  */
47 define('COMPLETION_CRITERIA_TYPE_UNENROL',      3);
49 /**
50  * Activity completion criteria type
51  * Criteria type constant, primarily for storing criteria type in the database.
52  */
53 define('COMPLETION_CRITERIA_TYPE_ACTIVITY',     4);
55 /**
56  * Duration completion criteria type
57  * Criteria type constant, primarily for storing criteria type in the database.
58  */
59 define('COMPLETION_CRITERIA_TYPE_DURATION',     5);
61 /**
62  * Grade completion criteria type
63  * Criteria type constant, primarily for storing criteria type in the database.
64  */
65 define('COMPLETION_CRITERIA_TYPE_GRADE',        6);
67 /**
68  * Role completion criteria type
69  * Criteria type constant, primarily for storing criteria type in the database.
70  */
71 define('COMPLETION_CRITERIA_TYPE_ROLE',         7);
73 /**
74  * Course completion criteria type
75  * Criteria type constant, primarily for storing criteria type in the database.
76  */
77 define('COMPLETION_CRITERIA_TYPE_COURSE',       8);
79 /**
80  * Criteria type constant to class name mapping.
81  *
82  * This global variable would be improved if it was implemented as a cache.
83  */
84 global $COMPLETION_CRITERIA_TYPES;
85 $COMPLETION_CRITERIA_TYPES = array(
86     COMPLETION_CRITERIA_TYPE_SELF       => 'self',
87     COMPLETION_CRITERIA_TYPE_DATE       => 'date',
88     COMPLETION_CRITERIA_TYPE_UNENROL    => 'unenrol',
89     COMPLETION_CRITERIA_TYPE_ACTIVITY   => 'activity',
90     COMPLETION_CRITERIA_TYPE_DURATION   => 'duration',
91     COMPLETION_CRITERIA_TYPE_GRADE      => 'grade',
92     COMPLETION_CRITERIA_TYPE_ROLE       => 'role',
93     COMPLETION_CRITERIA_TYPE_COURSE     => 'course',
94 );
97 /**
98  * Completion criteria abstract definition
99  *
100  * @package core_completion
101  * @category completion
102  * @copyright 2009 Catalyst IT Ltd
103  * @author Aaron Barnes <aaronb@catalyst.net.nz>
104  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
105  */
106 abstract class completion_criteria extends data_object {
108     /* @var string Database table name that stores completion criteria information  */
109     public $table = 'course_completion_criteria';
111     /**
112      * Array of required table fields, must start with 'id'.
113      * Defaults to id, course, criteriatype, module, moduleinstane, courseinstance,
114      * enrolperiod, timeend, gradepass, role
115      * @var array
116      */
117     public $required_fields = array('id', 'course', 'criteriatype', 'module', 'moduleinstance', 'courseinstance', 'enrolperiod', 'timeend', 'gradepass', 'role');
119     /* @var int Course id  */
120     public $course;
122     /**
123      * Criteria type
124      * One of the COMPLETION_CRITERIA_TYPE_* constants
125      * @var int
126      */
127     public $criteriatype;
129     /* @var string Module type this criteria relates to (for activity criteria)  */
130     public $module;
132     /* @var int Course module instance id this criteria relates to (for activity criteria) */
133     public $moduleinstance;
135     /**
136      * Period after enrolment completion will be triggered (for period criteria)
137      * The value here is the number of days as an int.
138      * @var int
139      */
140     public $enrolperiod;
142     /**
143      * Date of course completion (for date criteria)
144      * This is a timestamp value
145      * @var int
146      */
147     public $date;
149     /* @var float Passing grade required to complete course (for grade completion) */
150     public $gradepass;
152     /* @var int Role ID that has the ability to mark a user as complete (for role completion) */
153     public $role;
155     /**
156      * Finds and returns all data_object instances based on params.
157      *
158      * @param array $params associative arrays varname=>value
159      * @return array array of data_object insatnces or false if none found.
160      */
161     public static function fetch_all($params) {}
163     /**
164      * Factory method for creating correct class object
165      *
166      * @param array $params associative arrays varname=>value
167      * @return completion_criteria
168      */
169     public static function factory($params) {
170         global $CFG, $COMPLETION_CRITERIA_TYPES;
172         if (!isset($params['criteriatype']) || !isset($COMPLETION_CRITERIA_TYPES[$params['criteriatype']])) {
173             print_error('invalidcriteriatype', 'completion');
174         }
176         $class = 'completion_criteria_'.$COMPLETION_CRITERIA_TYPES[$params['criteriatype']];
177         require_once($CFG->dirroot.'/completion/criteria/'.$class.'.php');
179         return new $class($params, false);
180     }
182     /**
183      * Add appropriate form elements to the critieria form
184      *
185      * @param moodleform $mform Moodle forms object
186      * @param mixed $data optional Any additional data that can be used to set default values in the form
187      * @return void
188      */
189     abstract public function config_form_display(&$mform, $data = null);
191     /**
192      * Update the criteria information stored in the database
193      *
194      * @param array $data Form data
195      * @return void
196      */
197     abstract public function update_config(&$data);
199     /**
200      * Review this criteria and decide if the user has completed
201      *
202      * @param object $completion The user's completion record
203      * @param boolean $mark Optionally set false to not save changes to database
204      * @return boolean
205      */
206     abstract public function review($completion, $mark = true);
208     /**
209      * Return criteria title for display in reports
210      *
211      * @return string
212      */
213     abstract public function get_title();
215     /**
216      * Return a more detailed criteria title for display in reports
217      *
218      * @return string
219      */
220     abstract public function get_title_detailed();
222     /**
223      * Return criteria type title for display in reports
224      *
225      * @return string
226      */
227     abstract public function get_type_title();
229     /**
230      * Return criteria progress details for display in reports
231      *
232      * @param completion_completion $completion The user's completion record
233      * @return array
234      */
235     abstract public function get_details($completion);
237     /**
238      * Return pix_icon for display in reports.
239      *
240      * @param string $alt The alt text to use for the icon
241      * @param array $attributes html attributes
242      * @return pix_icon
243      */
244     public function get_icon($alt, array $attributes = null) {
245         global $COMPLETION_CRITERIA_TYPES;
247         $criteriatype = $COMPLETION_CRITERIA_TYPES[$this->criteriatype];
248         return new pix_icon('i/'.$criteriatype, $alt, 'moodle', $attributes);
249     }
251     /**
252      * Return criteria status text for display in reports
253      *
254      * @param completion_completion $completion The user's completion record
255      * @return string
256      */
257     public function get_status($completion) {
258         return $completion->is_complete() ? get_string('yes') : get_string('no');
259     }
261     /**
262      * Return true if the criteria's current status is different to what is sorted
263      * in the database, e.g. pending an update
264      *
265      * @param completion_completion $completion The user's criteria completion record
266      * @return bool
267      */
268     public function is_pending($completion) {
269         $review = $this->review($completion, false);
271         return $review !== $completion->is_complete();
272     }