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/>.
  16
  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  */
  25
  26 defined('MOODLE_INTERNAL') || die();
  27
  28 require_once('grade_object.php');
  29
  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';
  46
  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');
  52
  53     /**
  54      * The course this scale belongs to.
  55      * @var int $courseid
  56      */
  57     public $courseid;
  58
  59     /**
  60      * The ID of the user who created the scale
  61      * @var int $userid
  62      */
  63     public $userid;
  64
  65     /**
  66      * The name of the scale.
  67      * @var string $name
  68      */
  69     public $name;
  70
  71     /**
  72      * The items in this scale.
  73      * @var array $scale_items
  74      */
  75     public $scale_items = array();
  76
  77     /**
  78      * A string representation of the scale items (a comma-separated list).
  79      * @var string $scale
  80      */
  81     public $scale;
  82
  83     /**
  84      * A description for this scale.
  85      * @var string $description
  86      */
  87     public $description;
  88
  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     }
  99
 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     }
 110
 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     }
 124
 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     }
 135
 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     }
 155
 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     }
 165
 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         }
 184
 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      */
 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         }
 214
 215         return $this->scale;
 216     }
 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.
 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);
 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     }
 241
 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     }
 250
 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     }
 260
 261     /**
 262      * Checks if scale can be deleted.
 263      *
 264      * @return bool
 265      */
 266     public function can_delete() {
 267         return !$this->is_used();
 268     }
 269
 270     /**
 271      * Returns if scale used anywhere - activities, grade items, outcomes, etc.
 272      *
 273      * @return bool
 274      */
 275     public function is_used() {
 276         global $DB;
 277         global $CFG;
 278
 279         // count grade items excluding the
 280         $params = array($this->id);
 281         $sql = "SELECT COUNT(id) FROM {grade_items} WHERE scaleid = ? AND outcomeid IS NULL";
 282         if ($DB->count_records_sql($sql, $params)) {
 283             return true;
 284         }
 285
 286         // count outcomes
 287         $sql = "SELECT COUNT(id) FROM {grade_outcomes} WHERE scaleid = ?";
 288         if ($DB->count_records_sql($sql, $params)) {
 289             return true;
 290         }
 291
 292         // Ask the competency subsystem.
 293         if (\core_competency\api::is_scale_used_anywhere($this->id)) {
 294             return true;
 295         }
 296
 297         // Ask all plugins if the scale is used anywhere.
 298         $pluginsfunction = get_plugins_with_function('scale_used_anywhere');
 299         foreach ($pluginsfunction as $plugintype => $plugins) {
 300             foreach ($plugins as $pluginfunction) {
 301                 if ($pluginfunction($this->id)) {
 302                     return true;
 303                 }
 304             }
 305         }
 306
 307         return false;
 308     }
 309
 310     /**
 311      * Returns the formatted grade description with URLs converted
 312      *
 313      * @return string
 314      */
 315     public function get_description() {
 316         global $CFG;
 317         require_once($CFG->libdir . '/filelib.php');
 318
 319         $systemcontext = context_system::instance();
 320         $options = new stdClass;
 321         $options->noclean = true;
 322         $description = file_rewrite_pluginfile_urls($this->description, 'pluginfile.php', $systemcontext->id, 'grade', 'scale', $this->id);
 323         return format_text($description, $this->descriptionformat, $options);
 324     }
 325 }