MDL-54613 unit tests: Add iteminstance to test grade_item
[moodle.git] / lib / grade / grade_scale.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  * Definition of grade scale class
19  *
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
24  */
26 defined('MOODLE_INTERNAL') || die();
28 require_once('grade_object.php');
30 /**
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
39  */
40 class grade_scale extends grade_object {
41     /**
42      * DB Table (used by grade_object).
43      * @var string $table
44      */
45     public $table = 'scale';
47     /**
48      * Array of required table fields, must start with 'id'.
49      * @var array $required_fields
50      */
51     public $required_fields = array('id', 'courseid', 'userid', 'name', 'scale', 'description', 'descriptionformat', 'timemodified');
53     /**
54      * The course this scale belongs to.
55      * @var int $courseid
56      */
57     public $courseid;
59     /**
60      * The ID of the user who created the scale
61      * @var int $userid
62      */
63     public $userid;
65     /**
66      * The name of the scale.
67      * @var string $name
68      */
69     public $name;
71     /**
72      * The items in this scale.
73      * @var array $scale_items
74      */
75     public $scale_items = array();
77     /**
78      * A string representation of the scale items (a comma-separated list).
79      * @var string $scale
80      */
81     public $scale;
83     /**
84      * A description for this scale.
85      * @var string $description
86      */
87     public $description;
89     /**
90      * Finds and returns a grade_scale instance based on params.
91      *
92      * @static
93      * @param array $params associative arrays varname=>value
94      * @return object grade_scale instance or false if none found.
95      */
96     public static function fetch($params) {
97         return grade_object::fetch_helper('scale', 'grade_scale', $params);
98     }
100     /**
101      * Finds and returns all grade_scale instances based on params.
102      *
103      * @static
104      * @param array $params associative arrays varname=>value
105      * @return array array of grade_scale instances or false if none found.
106      */
107     public static function fetch_all($params) {
108         return grade_object::fetch_all_helper('scale', 'grade_scale', $params);
109     }
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.
115      *
116      * @param string $source from where was the object inserted (mod/forum, manual, etc.)
117      * @return int PK ID if successful, false otherwise
118      */
119     public function insert($source=null) {
120         $this->timecreated = time();
121         $this->timemodified = time();
122         return parent::insert($source);
123     }
125     /**
126      * In addition to update() it also updates grade_outcomes_courses if needed
127      *
128      * @param string $source from where was the object inserted
129      * @return bool success
130      */
131     public function update($source=null) {
132         $this->timemodified = time();
133         return parent::update($source);
134     }
136     /**
137      * Deletes this outcome from the database.
138      *
139      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
140      * @return bool success
141      */
142     public function delete($source=null) {
143         global $DB;
144         if (parent::delete($source)) {
145             $context = context_system::instance();
146             $fs = get_file_storage();
147             $files = $fs->get_area_files($context->id, 'grade', 'scale', $this->id);
148             foreach ($files as $file) {
149                 $file->delete();
150             }
151             return true;
152         }
153         return false;
154     }
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.
159      *
160      * @return string name
161      */
162     public function get_name() {
163         return format_string($this->name);
164     }
166     /**
167      * Loads the scale's items into the $scale_items array.
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      */
176     public function load_items($items=NULL) {
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         }
185         // Trim whitespace around each value
186         foreach ($this->scale_items as $key => $val) {
187             $this->scale_items[$key] = trim($val);
188         }
190         return $this->scale_items;
191     }
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      */
206     public function compact_items($items=NULL) {
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         }
215         return $this->scale;
216     }
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.
223      *
224      * @param float $grade
225      * @return string
226      */
227     public function get_nearest_item($grade) {
228         global $DB;
229         // Obtain nearest scale item from average
230         $scales_array = $DB->get_records('scale', array('id' => $this->id));
231         $scale = $scales_array[$this->id];
232         $scales = explode(",", $scale->scale);
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         }
239         return $scales[$grade-1];
240     }
242     /**
243      * Static function returning all global scales
244      *
245      * @return object
246      */
247     public static function fetch_all_global() {
248         return grade_scale::fetch_all(array('courseid'=>0));
249     }
251     /**
252      * Static function returning all local course scales
253      *
254      * @param int $courseid The course ID
255      * @return array Returns an array of grade_scale instances
256      */
257     public static function fetch_all_local($courseid) {
258         return grade_scale::fetch_all(array('courseid'=>$courseid));
259     }
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     }
270     /**
271      * Checks if scale can be deleted.
272      *
273      * @return bool
274      */
275     public function can_delete() {
276         return !$this->is_used() && !$this->is_last_global_scale();
277     }
279     /**
280      * Returns if scale used anywhere - activities, grade items, outcomes, etc.
281      *
282      * @return bool
283      */
284     public function is_used() {
285         global $DB;
286         global $CFG;
288         // count grade items excluding the
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)) {
292             return true;
293         }
295         // count outcomes
296         $sql = "SELECT COUNT(id) FROM {grade_outcomes} WHERE scaleid = ?";
297         if ($DB->count_records_sql($sql, $params)) {
298             return true;
299         }
301         // Ask the competency subsystem.
302         if (\core_competency\api::is_scale_used_anywhere($this->id)) {
303             return true;
304         }
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)) {
311                     return true;
312                 }
313             }
314         }
316         return false;
317     }
319     /**
320      * Returns the formatted grade description with URLs converted
321      *
322      * @return string
323      */
324     public function get_description() {
325         global $CFG;
326         require_once($CFG->libdir . '/filelib.php');
328         $systemcontext = context_system::instance();
329         $options = new stdClass;
330         $options->noclean = true;
331         $description = file_rewrite_pluginfile_urls($this->description, 'pluginfile.php', $systemcontext->id, 'grade', 'scale', $this->id);
332         return format_text($description, $this->descriptionformat, $options);
333     }