MDL-54613 unit tests: Add iteminstance to test grade_item
[moodle.git] / lib / grade / grade_scale.php
CommitLineData
4a0e2e63 1<?php
7ad5a627
PS
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/>.
a153c9f2 16
7ad5a627 17/**
a153c9f2 18 * Definition of grade scale class
7ad5a627 19 *
a153c9f2
AD
20 * @package core_grades
21 * @category grade
22 * @copyright 2006 Nicolas Connault
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
7ad5a627
PS
24 */
25
26defined('MOODLE_INTERNAL') || die();
97b868a3 27
28require_once('grade_object.php');
29
30/**
a153c9f2
AD
31 * Class representing a grade scale.
32 *
33 * It is responsible for handling its DB representation, modifying and returning its metadata.
34 *
35 * @package core_grades
36 * @category grade
37 * @copyright 2006 Nicolas Connault
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
97b868a3 39 */
40class grade_scale extends grade_object {
41 /**
42 * DB Table (used by grade_object).
43 * @var string $table
44 */
da3801e8 45 public $table = 'scale';
772ddfbf 46
97b868a3 47 /**
3f2b0c8a 48 * Array of required table fields, must start with 'id'.
49 * @var array $required_fields
97b868a3 50 */
8bdc9cac 51 public $required_fields = array('id', 'courseid', 'userid', 'name', 'scale', 'description', 'descriptionformat', 'timemodified');
772ddfbf 52
97b868a3 53 /**
54 * The course this scale belongs to.
55 * @var int $courseid
56 */
da3801e8 57 public $courseid;
772ddfbf 58
a153c9f2
AD
59 /**
60 * The ID of the user who created the scale
61 * @var int $userid
62 */
da3801e8 63 public $userid;
f92dcad8 64
97b868a3 65 /**
66 * The name of the scale.
67 * @var string $name
68 */
da3801e8 69 public $name;
97b868a3 70
71 /**
72 * The items in this scale.
73 * @var array $scale_items
74 */
da3801e8 75 public $scale_items = array();
97b868a3 76
77 /**
f7d515b6 78 * A string representation of the scale items (a comma-separated list).
97b868a3 79 * @var string $scale
80 */
da3801e8 81 public $scale;
97b868a3 82
83 /**
84 * A description for this scale.
85 * @var string $description
86 */
da3801e8 87 public $description;
772ddfbf 88
46566dd8 89 /**
f92dcad8 90 * Finds and returns a grade_scale instance based on params.
46566dd8 91 *
a153c9f2 92 * @static
f92dcad8 93 * @param array $params associative arrays varname=>value
94 * @return object grade_scale instance or false if none found.
46566dd8 95 */
da3801e8 96 public static function fetch($params) {
f3ac8eb4 97 return grade_object::fetch_helper('scale', 'grade_scale', $params);
f92dcad8 98 }
61c33818 99
f92dcad8 100 /**
101 * Finds and returns all grade_scale instances based on params.
f92dcad8 102 *
a153c9f2 103 * @static
f92dcad8 104 * @param array $params associative arrays varname=>value
f7d515b6 105 * @return array array of grade_scale instances or false if none found.
f92dcad8 106 */
da3801e8 107 public static function fetch_all($params) {
f3ac8eb4 108 return grade_object::fetch_all_helper('scale', 'grade_scale', $params);
46566dd8 109 }
772ddfbf 110
ced5ee59 111 /**
112 * Records this object in the Database, sets its id to the returned value, and returns that value.
113 * If successful this function also fetches the new object data from database and stores it
114 * in object properties.
a153c9f2 115 *
ced5ee59 116 * @param string $source from where was the object inserted (mod/forum, manual, etc.)
117 * @return int PK ID if successful, false otherwise
118 */
da3801e8 119 public function insert($source=null) {
1f0e4921 120 $this->timecreated = time();
ced5ee59 121 $this->timemodified = time();
122 return parent::insert($source);
123 }
124
125 /**
126 * In addition to update() it also updates grade_outcomes_courses if needed
a153c9f2 127 *
ced5ee59 128 * @param string $source from where was the object inserted
a153c9f2 129 * @return bool success
ced5ee59 130 */
da3801e8 131 public function update($source=null) {
ced5ee59 132 $this->timemodified = time();
133 return parent::update($source);
134 }
135
8bdc9cac
SH
136 /**
137 * Deletes this outcome from the database.
a153c9f2 138 *
8bdc9cac 139 * @param string $source from where was the object deleted (mod/forum, manual, etc.)
a153c9f2 140 * @return bool success
8bdc9cac
SH
141 */
142 public function delete($source=null) {
143 global $DB;
144 if (parent::delete($source)) {
b0c6dc1c 145 $context = context_system::instance();
8bdc9cac 146 $fs = get_file_storage();
64f93798 147 $files = $fs->get_area_files($context->id, 'grade', 'scale', $this->id);
8bdc9cac
SH
148 foreach ($files as $file) {
149 $file->delete();
150 }
151 return true;
152 }
153 return false;
154 }
155
173a9d21 156 /**
157 * Returns the most descriptive field for this object. This is a standard method used
158 * when we do not know the exact type of an object.
a153c9f2 159 *
173a9d21 160 * @return string name
161 */
da3801e8 162 public function get_name() {
173a9d21 163 return format_string($this->name);
164 }
165
97b868a3 166 /**
772ddfbf 167 * Loads the scale's items into the $scale_items array.
97b868a3 168 * There are three ways to achieve this:
169 * 1. No argument given: The $scale string is already loaded and exploded to an array of items.
170 * 2. A string is given: A comma-separated list of items is exploded into an array of items.
171 * 3. An array of items is given and saved directly as the array of items for this scale.
172 *
173 * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
174 * @return array The resulting array of scale items or null if the method failed to produce one.
175 */
da3801e8 176 public function load_items($items=NULL) {
97b868a3 177 if (empty($items)) {
178 $this->scale_items = explode(',', $this->scale);
179 } elseif (is_array($items)) {
180 $this->scale_items = $items;
181 } else {
182 $this->scale_items = explode(',', $items);
183 }
772ddfbf 184
97b868a3 185 // Trim whitespace around each value
186 foreach ($this->scale_items as $key => $val) {
187 $this->scale_items[$key] = trim($val);
188 }
189
190 return $this->scale_items;
191 }
192
193 /**
194 * Compacts (implodes) the array of items in $scale_items into a comma-separated string, $scale.
195 * There are three ways to achieve this:
196 * 1. No argument given: The $scale_items array is already loaded and imploded to a string of items.
197 * 2. An array is given and is imploded into a string of items.
198 * 3. A string of items is given and saved directly as the $scale variable.
199 * NOTE: This method is the exact reverse of load_items, and their input/output should be interchangeable. However,
200 * because load_items() trims the whitespace around the items, when the string is reconstructed these whitespaces will
201 * be missing. This is not an issue, but should be kept in mind when comparing the two strings.
202 *
203 * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
204 * @return array The resulting string of scale items or null if the method failed to produce one.
205 */
da3801e8 206 public function compact_items($items=NULL) {
97b868a3 207 if (empty($items)) {
208 $this->scale = implode(',', $this->scale_items);
209 } elseif (is_array($items)) {
210 $this->scale = implode(',', $items);
211 } else {
212 $this->scale = $items;
213 }
214
772ddfbf 215 return $this->scale;
216 }
acdc8e8a 217
218 /**
219 * When called on a loaded scale object (with a valid id) and given a float grade between
220 * the grademin and grademax, this method returns the scale item that falls closest to the
221 * float given (which is usually an average of several grades on a scale). If the float falls
222 * below 1 but above 0, it will be rounded up to 1.
a153c9f2 223 *
acdc8e8a 224 * @param float $grade
225 * @return string
226 */
da3801e8 227 public function get_nearest_item($grade) {
228 global $DB;
acdc8e8a 229 // Obtain nearest scale item from average
de0300ea 230 $scales_array = $DB->get_records('scale', array('id' => $this->id));
acdc8e8a 231 $scale = $scales_array[$this->id];
232 $scales = explode(",", $scale->scale);
233
234 // this could be a 0 when summed and rounded, e.g, 1, no grade, no grade, no grade
235 if ($grade < 1) {
236 $grade = 1;
237 }
238
239 return $scales[$grade-1];
240 }
78ad5f3f 241
242 /**
173a9d21 243 * Static function returning all global scales
a153c9f2 244 *
173a9d21 245 * @return object
246 */
f20edd52 247 public static function fetch_all_global() {
f3ac8eb4 248 return grade_scale::fetch_all(array('courseid'=>0));
173a9d21 249 }
250
251 /**
252 * Static function returning all local course scales
a153c9f2
AD
253 *
254 * @param int $courseid The course ID
255 * @return array Returns an array of grade_scale instances
173a9d21 256 */
da3801e8 257 public static function fetch_all_local($courseid) {
f3ac8eb4 258 return grade_scale::fetch_all(array('courseid'=>$courseid));
173a9d21 259 }
260
d03602c8
DW
261 /**
262 * Checks if this is the last scale on the site.
263 *
264 * @return bool
265 */
266 public function is_last_global_scale() {
267 return ($this->courseid == 0) && (count(self::fetch_all_global()) == 1);
268 }
269
173a9d21 270 /**
271 * Checks if scale can be deleted.
a153c9f2
AD
272 *
273 * @return bool
78ad5f3f 274 */
da3801e8 275 public function can_delete() {
d03602c8 276 return !$this->is_used() && !$this->is_last_global_scale();
78ad5f3f 277 }
278
279 /**
85c9ebb9 280 * Returns if scale used anywhere - activities, grade items, outcomes, etc.
a153c9f2 281 *
85c9ebb9 282 * @return bool
78ad5f3f 283 */
da3801e8 284 public function is_used() {
285 global $DB;
78ad5f3f 286 global $CFG;
287
ced5ee59 288 // count grade items excluding the
5b0af8c5 289 $params = array($this->id);
290 $sql = "SELECT COUNT(id) FROM {grade_items} WHERE scaleid = ? AND outcomeid IS NULL";
291 if ($DB->count_records_sql($sql, $params)) {
85c9ebb9 292 return true;
78ad5f3f 293 }
294
295 // count outcomes
5b0af8c5 296 $sql = "SELECT COUNT(id) FROM {grade_outcomes} WHERE scaleid = ?";
297 if ($DB->count_records_sql($sql, $params)) {
85c9ebb9 298 return true;
299 }
300
8d0c57ed 301 // Ask the competency subsystem.
4fd183d3 302 if (\core_competency\api::is_scale_used_anywhere($this->id)) {
8d0c57ed
FM
303 return true;
304 }
305
322f3141
MG
306 // Ask all plugins if the scale is used anywhere.
307 $pluginsfunction = get_plugins_with_function('scale_used_anywhere');
308 foreach ($pluginsfunction as $plugintype => $plugins) {
309 foreach ($plugins as $pluginfunction) {
310 if ($pluginfunction($this->id)) {
85c9ebb9 311 return true;
312 }
313 }
78ad5f3f 314 }
315
85c9ebb9 316 return false;
78ad5f3f 317 }
8bdc9cac
SH
318
319 /**
c1024411 320 * Returns the formatted grade description with URLs converted
a153c9f2 321 *
8bdc9cac
SH
322 * @return string
323 */
324 public function get_description() {
99d19c13
PS
325 global $CFG;
326 require_once($CFG->libdir . '/filelib.php');
327
b0c6dc1c 328 $systemcontext = context_system::instance();
8bdc9cac
SH
329 $options = new stdClass;
330 $options->noclean = true;
64f93798 331 $description = file_rewrite_pluginfile_urls($this->description, 'pluginfile.php', $systemcontext->id, 'grade', 'scale', $this->id);
8bdc9cac
SH
332 return format_text($description, $this->descriptionformat, $options);
333 }
97b868a3 334}