9685008808295fbcf07278ef796c071262983245
[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();
123         $result = parent::insert($source);
124         if ($result) {
125             // Trigger the scale created event.
126             if (!empty($this->standard)) {
127                 $eventcontext = context_system::instance();
128             } else {
129                 if ((!empty($this->courseid)) && ($this->courseid != SITEID)) {
130                     $eventcontext = context_course::instance($this->courseid);
131                 } else {
132                     $eventcontext = context_system::instance();
133                 }
134             }
135             $event = \core\event\scale_created::create(array(
136                 'objectid' => $result,
137                 'context' => $eventcontext
138             ));
139             $event->trigger();
140         }
141         return $result;
142     }
144     /**
145      * In addition to update() it also updates grade_outcomes_courses if needed
146      *
147      * @param string $source from where was the object inserted
148      * @return bool success
149      */
150     public function update($source=null) {
151         $this->timemodified = time();
153         $result = parent::update($source);
154         if ($result) {
155             // Trigger the scale updated event.
156             if (!empty($this->standard)) {
157                 $eventcontext = context_system::instance();
158             } else {
159                 if ((!empty($this->courseid)) && ($this->courseid != SITEID)) {
160                     $eventcontext = context_course::instance($this->courseid);
161                 } else {
162                     $eventcontext = context_system::instance();
163                 }
164             }
165             $event = \core\event\scale_updated::create(array(
166                 'objectid' => $this->id,
167                 'context' => $eventcontext
168             ));
169             $event->trigger();
170         }
171         return $result;
172     }
174     /**
175      * Deletes this scale from the database.
176      *
177      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
178      * @return bool success
179      */
180     public function delete($source=null) {
181         global $DB;
183         // Trigger the scale deleted event.
184         if (!empty($this->standard)) {
185             $eventcontext = context_system::instance();
186         } else {
187             if ((!empty($this->courseid)) && ($this->courseid != SITEID)) {
188                 $eventcontext = context_course::instance($this->courseid);
189             } else {
190                 $eventcontext = context_system::instance();
191             }
192         }
193         $event = \core\event\scale_deleted::create(array(
194             'objectid' => $this->id,
195             'context' => $eventcontext
196         ));
197         $event->trigger();
198         if (parent::delete($source)) {
199             $context = context_system::instance();
200             $fs = get_file_storage();
201             $files = $fs->get_area_files($context->id, 'grade', 'scale', $this->id);
202             foreach ($files as $file) {
203                 $file->delete();
204             }
205             return true;
206         }
207         return false;
208     }
210     /**
211      * Returns the most descriptive field for this object. This is a standard method used
212      * when we do not know the exact type of an object.
213      *
214      * @return string name
215      */
216     public function get_name() {
217         return format_string($this->name);
218     }
220     /**
221      * Loads the scale's items into the $scale_items array.
222      * There are three ways to achieve this:
223      * 1. No argument given: The $scale string is already loaded and exploded to an array of items.
224      * 2. A string is given: A comma-separated list of items is exploded into an array of items.
225      * 3. An array of items is given and saved directly as the array of items for this scale.
226      *
227      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
228      * @return array The resulting array of scale items or null if the method failed to produce one.
229      */
230     public function load_items($items=NULL) {
231         if (empty($items)) {
232             $this->scale_items = explode(',', $this->scale);
233         } elseif (is_array($items)) {
234             $this->scale_items = $items;
235         } else {
236             $this->scale_items = explode(',', $items);
237         }
239         // Trim whitespace around each value
240         foreach ($this->scale_items as $key => $val) {
241             $this->scale_items[$key] = trim($val);
242         }
244         return $this->scale_items;
245     }
247     /**
248      * Compacts (implodes) the array of items in $scale_items into a comma-separated string, $scale.
249      * There are three ways to achieve this:
250      * 1. No argument given: The $scale_items array is already loaded and imploded to a string of items.
251      * 2. An array is given and is imploded into a string of items.
252      * 3. A string of items is given and saved directly as the $scale variable.
253      * NOTE: This method is the exact reverse of load_items, and their input/output should be interchangeable. However,
254      * because load_items() trims the whitespace around the items, when the string is reconstructed these whitespaces will
255      * be missing. This is not an issue, but should be kept in mind when comparing the two strings.
256      *
257      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
258      * @return array The resulting string of scale items or null if the method failed to produce one.
259      */
260     public function compact_items($items=NULL) {
261         if (empty($items)) {
262             $this->scale = implode(',', $this->scale_items);
263         } elseif (is_array($items)) {
264             $this->scale = implode(',', $items);
265         } else {
266             $this->scale = $items;
267         }
269         return $this->scale;
270     }
272     /**
273      * When called on a loaded scale object (with a valid id) and given a float grade between
274      * the grademin and grademax, this method returns the scale item that falls closest to the
275      * float given (which is usually an average of several grades on a scale). If the float falls
276      * below 1 but above 0, it will be rounded up to 1.
277      *
278      * @param float $grade
279      * @return string
280      */
281     public function get_nearest_item($grade) {
282         global $DB;
283         // Obtain nearest scale item from average
284         $scales_array = $DB->get_records('scale', array('id' => $this->id));
285         $scale = $scales_array[$this->id];
286         $scales = explode(",", $scale->scale);
288         // this could be a 0 when summed and rounded, e.g, 1, no grade, no grade, no grade
289         if ($grade < 1) {
290             $grade = 1;
291         }
293         return $scales[$grade-1];
294     }
296     /**
297      * Static function returning all global scales
298      *
299      * @return object
300      */
301     public static function fetch_all_global() {
302         return grade_scale::fetch_all(array('courseid'=>0));
303     }
305     /**
306      * Static function returning all local course scales
307      *
308      * @param int $courseid The course ID
309      * @return array Returns an array of grade_scale instances
310      */
311     public static function fetch_all_local($courseid) {
312         return grade_scale::fetch_all(array('courseid'=>$courseid));
313     }
315     /**
316      * Checks if this is the last scale on the site.
317      *
318      * @return bool
319      */
320     public function is_last_global_scale() {
321         return ($this->courseid == 0) && (count(self::fetch_all_global()) == 1);
322     }
324     /**
325      * Checks if scale can be deleted.
326      *
327      * @return bool
328      */
329     public function can_delete() {
330         return !$this->is_used() && !$this->is_last_global_scale();
331     }
333     /**
334      * Returns if scale used anywhere - activities, grade items, outcomes, etc.
335      *
336      * @return bool
337      */
338     public function is_used() {
339         global $DB;
340         global $CFG;
342         // count grade items excluding the
343         $params = array($this->id);
344         $sql = "SELECT COUNT(id) FROM {grade_items} WHERE scaleid = ? AND outcomeid IS NULL";
345         if ($DB->count_records_sql($sql, $params)) {
346             return true;
347         }
349         // count outcomes
350         $sql = "SELECT COUNT(id) FROM {grade_outcomes} WHERE scaleid = ?";
351         if ($DB->count_records_sql($sql, $params)) {
352             return true;
353         }
355         // Ask the competency subsystem.
356         if (\core_competency\api::is_scale_used_anywhere($this->id)) {
357             return true;
358         }
360         // Ask all plugins if the scale is used anywhere.
361         $pluginsfunction = get_plugins_with_function('scale_used_anywhere');
362         foreach ($pluginsfunction as $plugintype => $plugins) {
363             foreach ($plugins as $pluginfunction) {
364                 if ($pluginfunction($this->id)) {
365                     return true;
366                 }
367             }
368         }
370         return false;
371     }
373     /**
374      * Returns the formatted grade description with URLs converted
375      *
376      * @return string
377      */
378     public function get_description() {
379         global $CFG;
380         require_once($CFG->libdir . '/filelib.php');
382         $systemcontext = context_system::instance();
383         $options = new stdClass;
384         $options->noclean = true;
385         $description = file_rewrite_pluginfile_urls($this->description, 'pluginfile.php', $systemcontext->id, 'grade', 'scale', $this->id);
386         return format_text($description, $this->descriptionformat, $options);
387     }