Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 311 and 400] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

       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 a class to represent a grade category
      19   *
      20   * @package   core_grades
      21   * @copyright 2006 Nicolas Connault
      22   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      23   */
      24  
      25  defined('MOODLE_INTERNAL') || die();
      26  
      27  require_once (__DIR__ . '/grade_object.php');
      28  
      29  /**
      30   * grade_category is an object mapped to DB table {prefix}grade_categories
      31   *
      32   * @package   core_grades
      33   * @category  grade
      34   * @copyright 2007 Nicolas Connault
      35   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
      36   */
      37  class grade_category extends grade_object {
      38      /**
      39       * The DB table.
      40       * @var string $table
      41       */
      42      public $table = 'grade_categories';
      43  
      44      /**
      45       * Array of required table fields, must start with 'id'.
      46       * @var array $required_fields
      47       */
      48      public $required_fields = array('id', 'courseid', 'parent', 'depth', 'path', 'fullname', 'aggregation',
      49                                   'keephigh', 'droplow', 'aggregateonlygraded', 'aggregateoutcomes',
      50                                   'timecreated', 'timemodified', 'hidden');
      51  
      52      /**
      53       * The course this category belongs to.
      54       * @var int $courseid
      55       */
      56      public $courseid;
      57  
      58      /**
      59       * The category this category belongs to (optional).
      60       * @var int $parent
      61       */
      62      public $parent;
      63  
      64      /**
      65       * The grade_category object referenced by $this->parent (PK).
      66       * @var grade_category $parent_category
      67       */
      68      public $parent_category;
      69  
      70      /**
      71       * The number of parents this category has.
      72       * @var int $depth
      73       */
      74      public $depth = 0;
      75  
      76      /**
      77       * Shows the hierarchical path for this category as /1/2/3/ (like course_categories), the last number being
      78       * this category's autoincrement ID number.
      79       * @var string $path
      80       */
      81      public $path;
      82  
      83      /**
      84       * The name of this category.
      85       * @var string $fullname
      86       */
      87      public $fullname;
      88  
      89      /**
      90       * A constant pointing to one of the predefined aggregation strategies (none, mean, median, sum etc) .
      91       * @var int $aggregation
      92       */
      93      public $aggregation = GRADE_AGGREGATE_SUM;
      94  
      95      /**
      96       * Keep only the X highest items.
      97       * @var int $keephigh
      98       */
      99      public $keephigh = 0;
     100  
     101      /**
     102       * Drop the X lowest items.
     103       * @var int $droplow
     104       */
     105      public $droplow = 0;
     106  
     107      /**
     108       * Aggregate only graded items
     109       * @var int $aggregateonlygraded
     110       */
     111      public $aggregateonlygraded = 0;
     112  
     113      /**
     114       * Aggregate outcomes together with normal items
     115       * @var int $aggregateoutcomes
     116       */
     117      public $aggregateoutcomes = 0;
     118  
     119      /**
     120       * Array of grade_items or grade_categories nested exactly 1 level below this category
     121       * @var array $children
     122       */
     123      public $children;
     124  
     125      /**
     126       * A hierarchical array of all children below this category. This is stored separately from
     127       * $children because it is more memory-intensive and may not be used as often.
     128       * @var array $all_children
     129       */
     130      public $all_children;
     131  
     132      /**
     133       * An associated grade_item object, with itemtype=category, used to calculate and cache a set of grade values
     134       * for this category.
     135       * @var grade_item $grade_item
     136       */
     137      public $grade_item;
     138  
     139      /**
     140       * Temporary sortorder for speedup of children resorting
     141       * @var int $sortorder
     142       */
     143      public $sortorder;
     144  
     145      /**
     146       * List of options which can be "forced" from site settings.
     147       * @var array $forceable
     148       */
     149      public $forceable = array('aggregation', 'keephigh', 'droplow', 'aggregateonlygraded', 'aggregateoutcomes');
     150  
     151      /**
     152       * String representing the aggregation coefficient. Variable is used as cache.
     153       * @var string $coefstring
     154       */
     155      public $coefstring = null;
     156  
     157      /**
     158       * Static variable storing the result from {@link self::can_apply_limit_rules}.
     159       * @var bool
     160       */
     161      protected $canapplylimitrules;
     162  
     163      /**
     164       * Builds this category's path string based on its parents (if any) and its own id number.
     165       * This is typically done just before inserting this object in the DB for the first time,
     166       * or when a new parent is added or changed. It is a recursive function: once the calling
     167       * object no longer has a parent, the path is complete.
     168       *
     169       * @param grade_category $grade_category A Grade_Category object
     170       * @return string The category's path string
     171       */
     172      public static function build_path($grade_category) {
     173          global $DB;
     174  
     175          if (empty($grade_category->parent)) {
     176              return '/'.$grade_category->id.'/';
     177  
     178          } else {
     179              $parent = $DB->get_record('grade_categories', array('id' => $grade_category->parent));
     180              return grade_category::build_path($parent).$grade_category->id.'/';
     181          }
     182      }
     183  
     184      /**
     185       * Finds and returns a grade_category instance based on params.
     186       *
     187       * @param array $params associative arrays varname=>value
     188       * @return grade_category The retrieved grade_category instance or false if none found.
     189       */
     190      public static function fetch($params) {
     191          if ($records = self::retrieve_record_set($params)) {
     192              return reset($records);
     193          }
     194  
     195          $record = grade_object::fetch_helper('grade_categories', 'grade_category', $params);
     196  
     197          // We store it as an array to keep a key => result set interface in the cache, grade_object::fetch_helper is
     198          // managing exceptions. We return only the first element though.
     199          $records = false;
     200          if ($record) {
     201              $records = array($record->id => $record);
     202          }
     203  
     204          self::set_record_set($params, $records);
     205  
     206          return $record;
     207      }
     208  
     209      /**
     210       * Finds and returns all grade_category instances based on params.
     211       *
     212       * @param array $params associative arrays varname=>value
     213       * @return array array of grade_category insatnces or false if none found.
     214       */
     215      public static function fetch_all($params) {
     216          if ($records = self::retrieve_record_set($params)) {
     217              return $records;
     218          }
     219  
     220          $records = grade_object::fetch_all_helper('grade_categories', 'grade_category', $params);
     221          self::set_record_set($params, $records);
     222  
     223          return $records;
     224      }
     225  
     226      /**
     227       * In addition to update() as defined in grade_object, call force_regrading of parent categories, if applicable.
     228       *
     229       * @param string $source from where was the object updated (mod/forum, manual, etc.)
     230       * @return bool success
     231       */
     232      public function update($source=null) {
     233          // load the grade item or create a new one
     234          $this->load_grade_item();
     235  
     236          // force recalculation of path;
     237          if (empty($this->path)) {
     238              $this->path  = grade_category::build_path($this);
     239              $this->depth = substr_count($this->path, '/') - 1;
     240              $updatechildren = true;
     241  
     242          } else {
     243              $updatechildren = false;
     244          }
     245  
     246          $this->apply_forced_settings();
     247  
     248          // these are exclusive
     249          if ($this->droplow > 0) {
     250              $this->keephigh = 0;
     251  
     252          } else if ($this->keephigh > 0) {
     253              $this->droplow = 0;
     254          }
     255  
     256          // Recalculate grades if needed
     257          if ($this->qualifies_for_regrading()) {
     258              $this->force_regrading();
     259          }
     260  
     261          $this->timemodified = time();
     262  
     263          $result = parent::update($source);
     264  
     265          // now update paths in all child categories
     266          if ($result and $updatechildren) {
     267  
     268              if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
     269  
     270                  foreach ($children as $child) {
     271                      $child->path  = null;
     272                      $child->depth = 0;
     273                      $child->update($source);
     274                  }
     275              }
     276          }
     277  
     278          return $result;
     279      }
     280  
     281      /**
     282       * If parent::delete() is successful, send force_regrading message to parent category.
     283       *
     284       * @param string $source from where was the object deleted (mod/forum, manual, etc.)
     285       * @return bool success
     286       */
     287      public function delete($source=null) {
     288          global $DB;
     289  
     290          $transaction = $DB->start_delegated_transaction();
     291          $grade_item = $this->load_grade_item();
     292  
     293          if ($this->is_course_category()) {
     294  
     295              if ($categories = grade_category::fetch_all(array('courseid'=>$this->courseid))) {
     296  
     297                  foreach ($categories as $category) {
     298  
     299                      if ($category->id == $this->id) {
     300                          continue; // do not delete course category yet
     301                      }
     302                      $category->delete($source);
     303                  }
     304              }
     305  
     306              if ($items = grade_item::fetch_all(array('courseid'=>$this->courseid))) {
     307  
     308                  foreach ($items as $item) {
     309  
     310                      if ($item->id == $grade_item->id) {
     311                          continue; // do not delete course item yet
     312                      }
     313                      $item->delete($source);
     314                  }
     315              }
     316  
     317          } else {
     318              $this->force_regrading();
     319  
     320              $parent = $this->load_parent_category();
     321  
     322              // Update children's categoryid/parent field first
     323              if ($children = grade_item::fetch_all(array('categoryid'=>$this->id))) {
     324                  foreach ($children as $child) {
     325                      $child->set_parent($parent->id);
     326                  }
     327              }
     328  
     329              if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
     330                  foreach ($children as $child) {
     331                      $child->set_parent($parent->id);
     332                  }
     333              }
     334          }
     335  
     336          // first delete the attached grade item and grades
     337          $grade_item->delete($source);
     338  
     339          // delete category itself
     340          $success = parent::delete($source);
     341  
     342          $transaction->allow_commit();
     343          return $success;
     344      }
     345  
     346      /**
     347       * In addition to the normal insert() defined in grade_object, this method sets the depth
     348       * and path for this object, and update the record accordingly.
     349       *
     350       * We do this here instead of in the constructor as they both need to know the record's
     351       * ID number, which only gets created at insertion time.
     352       * This method also creates an associated grade_item if this wasn't done during construction.
     353       *
     354       * @param string $source from where was the object inserted (mod/forum, manual, etc.)
     355       * @return int PK ID if successful, false otherwise
     356       */
     357      public function insert($source=null) {
     358  
     359          if (empty($this->courseid)) {
     360              print_error('cannotinsertgrade');
     361          }
     362  
     363          if (empty($this->parent)) {
     364              $course_category = grade_category::fetch_course_category($this->courseid);
     365              $this->parent = $course_category->id;
     366          }
     367  
     368          $this->path = null;
     369  
     370          $this->timecreated = $this->timemodified = time();
     371  
     372          if (!parent::insert($source)) {
     373              debugging("Could not insert this category: " . print_r($this, true));
     374              return false;
     375          }
     376  
     377          $this->force_regrading();
     378  
     379          // build path and depth
     380          $this->update($source);
     381  
     382          return $this->id;
     383      }
     384  
     385      /**
     386       * Internal function - used only from fetch_course_category()
     387       * Normal insert() can not be used for course category
     388       *
     389       * @param int $courseid The course ID
     390       * @return int The ID of the new course category
     391       */
     392      public function insert_course_category($courseid) {
     393          $this->courseid    = $courseid;
     394          $this->fullname    = '?';
     395          $this->path        = null;
     396          $this->parent      = null;
     397          $this->aggregation = GRADE_AGGREGATE_WEIGHTED_MEAN2;
     398  
     399          $this->apply_default_settings();
     400          $this->apply_forced_settings();
     401  
     402          $this->timecreated = $this->timemodified = time();
     403  
     404          if (!parent::insert('system')) {
     405              debugging("Could not insert this category: " . print_r($this, true));
     406              return false;
     407          }
     408  
     409          // build path and depth
     410          $this->update('system');
     411  
     412          return $this->id;
     413      }
     414  
     415      /**
     416       * Compares the values held by this object with those of the matching record in DB, and returns
     417       * whether or not these differences are sufficient to justify an update of all parent objects.
     418       * This assumes that this object has an ID number and a matching record in DB. If not, it will return false.
     419       *
     420       * @return bool
     421       */
     422      public function qualifies_for_regrading() {
     423          if (empty($this->id)) {
     424              debugging("Can not regrade non existing category");
     425              return false;
     426          }
     427  
     428          $db_item = grade_category::fetch(array('id'=>$this->id));
     429  
     430          $aggregationdiff = $db_item->aggregation         != $this->aggregation;
     431          $keephighdiff    = $db_item->keephigh            != $this->keephigh;
     432          $droplowdiff     = $db_item->droplow             != $this->droplow;
     433          $aggonlygrddiff  = $db_item->aggregateonlygraded != $this->aggregateonlygraded;
     434          $aggoutcomesdiff = $db_item->aggregateoutcomes   != $this->aggregateoutcomes;
     435  
     436          return ($aggregationdiff || $keephighdiff || $droplowdiff || $aggonlygrddiff || $aggoutcomesdiff);
     437      }
     438  
     439      /**
     440       * Marks this grade categories' associated grade item as needing regrading
     441       */
     442      public function force_regrading() {
     443          $grade_item = $this->load_grade_item();
     444          $grade_item->force_regrading();
     445      }
     446  
     447      /**
     448       * Something that should be called before we start regrading the whole course.
     449       *
     450       * @return void
     451       */
     452      public function pre_regrade_final_grades() {
     453          $this->auto_update_weights();
     454          $this->auto_update_max();
     455      }
     456  
     457      /**
     458       * Generates and saves final grades in associated category grade item.
     459       * These immediate children must already have their own final grades.
     460       * The category's aggregation method is used to generate final grades.
     461       *
     462       * Please note that category grade is either calculated or aggregated, not both at the same time.
     463       *
     464       * This method must be used ONLY from grade_item::regrade_final_grades(),
     465       * because the calculation must be done in correct order!
     466       *
     467       * Steps to follow:
     468       *  1. Get final grades from immediate children
     469       *  3. Aggregate these grades
     470       *  4. Save them in final grades of associated category grade item
     471       *
     472       * @param int $userid The user ID if final grade generation should be limited to a single user
     473       * @return bool
     474       */
     475      public function generate_grades($userid=null) {
     476          global $CFG, $DB;
     477  
     478          $this->load_grade_item();
     479  
     480          if ($this->grade_item->is_locked()) {
     481              return true; // no need to recalculate locked items
     482          }
     483  
     484          // find grade items of immediate children (category or grade items) and force site settings
     485          $depends_on = $this->grade_item->depends_on();
     486  
     487          if (empty($depends_on)) {
     488              $items = false;
     489  
     490          } else {
     491              list($usql, $params) = $DB->get_in_or_equal($depends_on);
     492              $sql = "SELECT *
     493                        FROM {grade_items}
     494                       WHERE id $usql";
     495              $items = $DB->get_records_sql($sql, $params);
     496              foreach ($items as $id => $item) {
     497                  $items[$id] = new grade_item($item, false);
     498              }
     499          }
     500  
     501          $grade_inst = new grade_grade();
     502          $fields = 'g.'.implode(',g.', $grade_inst->required_fields);
     503  
     504          // where to look for final grades - include grade of this item too, we will store the results there
     505          $gis = array_merge($depends_on, array($this->grade_item->id));
     506          list($usql, $params) = $DB->get_in_or_equal($gis);
     507  
     508          if ($userid) {
     509              $usersql = "AND g.userid=?";
     510              $params[] = $userid;
     511  
     512          } else {
     513              $usersql = "";
     514          }
     515  
     516          $sql = "SELECT $fields
     517                    FROM {grade_grades} g, {grade_items} gi
     518                   WHERE gi.id = g.itemid AND gi.id $usql $usersql
     519                ORDER BY g.userid";
     520  
     521          // group the results by userid and aggregate the grades for this user
     522          $rs = $DB->get_recordset_sql($sql, $params);
     523          if ($rs->valid()) {
     524              $prevuser = 0;
     525              $grade_values = array();
     526              $excluded     = array();
     527              $oldgrade     = null;
     528              $grademaxoverrides = array();
     529              $grademinoverrides = array();
     530  
     531              foreach ($rs as $used) {
     532                  $grade = new grade_grade($used, false);
     533                  if (isset($items[$grade->itemid])) {
     534                      // Prevent grade item to be fetched from DB.
     535                      $grade->grade_item =& $items[$grade->itemid];
     536                  } else if ($grade->itemid == $this->grade_item->id) {
     537                      // This grade's grade item is not in $items.
     538                      $grade->grade_item =& $this->grade_item;
     539                  }
     540                  if ($grade->userid != $prevuser) {
     541                      $this->aggregate_grades($prevuser,
     542                                              $items,
     543                                              $grade_values,
     544                                              $oldgrade,
     545                                              $excluded,
     546                                              $grademinoverrides,
     547                                              $grademaxoverrides);
     548                      $prevuser = $grade->userid;
     549                      $grade_values = array();
     550                      $excluded     = array();
     551                      $oldgrade     = null;
     552                      $grademaxoverrides = array();
     553                      $grademinoverrides = array();
     554                  }
     555                  $grade_values[$grade->itemid] = $grade->finalgrade;
     556                  $grademaxoverrides[$grade->itemid] = $grade->get_grade_max();
     557                  $grademinoverrides[$grade->itemid] = $grade->get_grade_min();
     558  
     559                  if ($grade->excluded) {
     560                      $excluded[] = $grade->itemid;
     561                  }
     562  
     563                  if ($this->grade_item->id == $grade->itemid) {
     564                      $oldgrade = $grade;
     565                  }
     566              }
     567              $this->aggregate_grades($prevuser,
     568                                      $items,
     569                                      $grade_values,
     570                                      $oldgrade,
     571                                      $excluded,
     572                                      $grademinoverrides,
     573                                      $grademaxoverrides);//the last one
     574          }
     575          $rs->close();
     576  
     577          return true;
     578      }
     579  
     580      /**
     581       * Internal function for grade category grade aggregation
     582       *
     583       * @param int    $userid The User ID
     584       * @param array  $items Grade items
     585       * @param array  $grade_values Array of grade values
     586       * @param object $oldgrade Old grade
     587       * @param array  $excluded Excluded
     588       * @param array  $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid)
     589       * @param array  $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid)
     590       */
     591      private function aggregate_grades($userid,
     592                                        $items,
     593                                        $grade_values,
     594                                        $oldgrade,
     595                                        $excluded,
     596                                        $grademinoverrides,
     597                                        $grademaxoverrides) {
     598          global $CFG, $DB;
     599  
     600          // Remember these so we can set flags on them to describe how they were used in the aggregation.
     601          $novalue = array();
     602          $dropped = array();
     603          $extracredit = array();
     604          $usedweights = array();
     605  
     606          if (empty($userid)) {
     607              //ignore first call
     608              return;
     609          }
     610  
     611          if ($oldgrade) {
     612              $oldfinalgrade = $oldgrade->finalgrade;
     613              $grade = new grade_grade($oldgrade, false);
     614              $grade->grade_item =& $this->grade_item;
     615  
     616          } else {
     617              // insert final grade - it will be needed later anyway
     618              $grade = new grade_grade(array('itemid'=>$this->grade_item->id, 'userid'=>$userid), false);
     619              $grade->grade_item =& $this->grade_item;
     620              $grade->insert('system');
     621              $oldfinalgrade = null;
     622          }
     623  
     624          // no need to recalculate locked or overridden grades
     625          if ($grade->is_locked() or $grade->is_overridden()) {
     626              return;
     627          }
     628  
     629          // can not use own final category grade in calculation
     630          unset($grade_values[$this->grade_item->id]);
     631  
     632          // Make sure a grade_grade exists for every grade_item.
     633          // We need to do this so we can set the aggregationstatus
     634          // with a set_field call instead of checking if each one exists and creating/updating.
     635          if (!empty($items)) {
     636              list($ggsql, $params) = $DB->get_in_or_equal(array_keys($items), SQL_PARAMS_NAMED, 'g');
     637  
     638  
     639              $params['userid'] = $userid;
     640              $sql = "SELECT itemid
     641                        FROM {grade_grades}
     642                       WHERE itemid $ggsql AND userid = :userid";
     643              $existingitems = $DB->get_records_sql($sql, $params);
     644  
     645              $notexisting = array_diff(array_keys($items), array_keys($existingitems));
     646              foreach ($notexisting as $itemid) {
     647                  $gradeitem = $items[$itemid];
     648                  $gradegrade = new grade_grade(array('itemid' => $itemid,
     649                                                      'userid' => $userid,
     650                                                      'rawgrademin' => $gradeitem->grademin,
     651                                                      'rawgrademax' => $gradeitem->grademax), false);
     652                  $gradegrade->grade_item = $gradeitem;
     653                  $gradegrade->insert('system');
     654              }
     655          }
     656  
     657          // if no grades calculation possible or grading not allowed clear final grade
     658          if (empty($grade_values) or empty($items) or ($this->grade_item->gradetype != GRADE_TYPE_VALUE and $this->grade_item->gradetype != GRADE_TYPE_SCALE)) {
     659              $grade->finalgrade = null;
     660  
     661              if (!is_null($oldfinalgrade)) {
     662                  $grade->timemodified = time();
     663                  $success = $grade->update('aggregation');
     664  
     665                  // If successful trigger a user_graded event.
     666                  if ($success) {
     667                      \core\event\user_graded::create_from_grade($grade, \core\event\base::USER_OTHER)->trigger();
     668                  }
     669              }
     670              $dropped = $grade_values;
     671              $this->set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit);
     672              return;
     673          }
     674  
     675          // Normalize the grades first - all will have value 0...1
     676          // ungraded items are not used in aggregation.
     677          foreach ($grade_values as $itemid=>$v) {
     678              if (is_null($v)) {
     679                  // If null, it means no grade.
     680                  if ($this->aggregateonlygraded) {
     681                      unset($grade_values[$itemid]);
     682                      // Mark this item as "excluded empty" because it has no grade.
     683                      $novalue[$itemid] = 0;
     684                      continue;
     685                  }
     686              }
     687              if (in_array($itemid, $excluded)) {
     688                  unset($grade_values[$itemid]);
     689                  $dropped[$itemid] = 0;
     690                  continue;
     691              }
     692              // Check for user specific grade min/max overrides.
     693              $usergrademin = $items[$itemid]->grademin;
     694              $usergrademax = $items[$itemid]->grademax;
     695              if (isset($grademinoverrides[$itemid])) {
     696                  $usergrademin = $grademinoverrides[$itemid];
     697              }
     698              if (isset($grademaxoverrides[$itemid])) {
     699                  $usergrademax = $grademaxoverrides[$itemid];
     700              }
     701              if ($this->aggregation == GRADE_AGGREGATE_SUM) {
     702                  // Assume that the grademin is 0 when standardising the score, to preserve negative grades.
     703                  $grade_values[$itemid] = grade_grade::standardise_score($v, 0, $usergrademax, 0, 1);
     704              } else {
     705                  $grade_values[$itemid] = grade_grade::standardise_score($v, $usergrademin, $usergrademax, 0, 1);
     706              }
     707  
     708          }
     709  
     710          // For items with no value, and not excluded - either set their grade to 0 or exclude them.
     711          foreach ($items as $itemid=>$value) {
     712              if (!isset($grade_values[$itemid]) and !in_array($itemid, $excluded)) {
     713                  if (!$this->aggregateonlygraded) {
     714                      $grade_values[$itemid] = 0;
     715                  } else {
     716                      // We are specifically marking these items as "excluded empty".
     717                      $novalue[$itemid] = 0;
     718                  }
     719              }
     720          }
     721  
     722          // limit and sort
     723          $allvalues = $grade_values;
     724          if ($this->can_apply_limit_rules()) {
     725              $this->apply_limit_rules($grade_values, $items);
     726          }
     727  
     728          $moredropped = array_diff($allvalues, $grade_values);
     729          foreach ($moredropped as $drop => $unused) {
     730              $dropped[$drop] = 0;
     731          }
     732  
     733          foreach ($grade_values as $itemid => $val) {
     734              if (self::is_extracredit_used() && ($items[$itemid]->aggregationcoef > 0)) {
     735                  $extracredit[$itemid] = 0;
     736              }
     737          }
     738  
     739          asort($grade_values, SORT_NUMERIC);
     740  
     741          // let's see we have still enough grades to do any statistics
     742          if (count($grade_values) == 0) {
     743              // not enough attempts yet
     744              $grade->finalgrade = null;
     745  
     746              if (!is_null($oldfinalgrade)) {
     747                  $grade->timemodified = time();
     748                  $success = $grade->update('aggregation');
     749  
     750                  // If successful trigger a user_graded event.
     751                  if ($success) {
     752                      \core\event\user_graded::create_from_grade($grade, \core\event\base::USER_OTHER)->trigger();
     753                  }
     754              }
     755              $this->set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit);
     756              return;
     757          }
     758  
     759          // do the maths
     760          $result = $this->aggregate_values_and_adjust_bounds($grade_values,
     761                                                              $items,
     762                                                              $usedweights,
     763                                                              $grademinoverrides,
     764                                                              $grademaxoverrides);
     765          $agg_grade = $result['grade'];
     766  
     767          // Set the actual grademin and max to bind the grade properly.
     768          $this->grade_item->grademin = $result['grademin'];
     769          $this->grade_item->grademax = $result['grademax'];
     770  
     771          if ($this->aggregation == GRADE_AGGREGATE_SUM) {
     772              // The natural aggregation always displays the range as coming from 0 for categories.
     773              // However, when we bind the grade we allow for negative values.
     774              $result['grademin'] = 0;
     775          }
     776  
     777          // Recalculate the grade back to requested range.
     778          $finalgrade = grade_grade::standardise_score($agg_grade, 0, 1, $result['grademin'], $result['grademax']);
     779          $grade->finalgrade = $this->grade_item->bounded_grade($finalgrade);
     780  
     781          $oldrawgrademin = $grade->rawgrademin;
     782          $oldrawgrademax = $grade->rawgrademax;
     783          $grade->rawgrademin = $result['grademin'];
     784          $grade->rawgrademax = $result['grademax'];
     785  
     786          // Update in db if changed.
     787          if (grade_floats_different($grade->finalgrade, $oldfinalgrade) ||
     788                  grade_floats_different($grade->rawgrademax, $oldrawgrademax) ||
     789                  grade_floats_different($grade->rawgrademin, $oldrawgrademin)) {
     790              $grade->timemodified = time();
     791              $success = $grade->update('aggregation');
     792  
     793              // If successful trigger a user_graded event.
     794              if ($success) {
     795                  \core\event\user_graded::create_from_grade($grade, \core\event\base::USER_OTHER)->trigger();
     796              }
     797          }
     798  
     799          $this->set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit);
     800  
     801          return;
     802      }
     803  
     804      /**
     805       * Set the flags on the grade_grade items to indicate how individual grades are used
     806       * in the aggregation.
     807       *
     808       * WARNING: This function is called a lot during gradebook recalculation, be very performance considerate.
     809       *
     810       * @param int $userid The user we have aggregated the grades for.
     811       * @param array $usedweights An array with keys for each of the grade_item columns included in the aggregation. The value are the relative weight.
     812       * @param array $novalue An array with keys for each of the grade_item columns skipped because
     813       *                       they had no value in the aggregation.
     814       * @param array $dropped An array with keys for each of the grade_item columns dropped
     815       *                       because of any drop lowest/highest settings in the aggregation.
     816       * @param array $extracredit An array with keys for each of the grade_item columns
     817       *                       considered extra credit by the aggregation.
     818       */
     819      private function set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit) {
     820          global $DB;
     821  
     822          // We want to know all current user grades so we can decide whether they need to be updated or they already contain the
     823          // expected value.
     824          $sql = "SELECT gi.id, gg.aggregationstatus, gg.aggregationweight FROM {grade_grades} gg
     825                    JOIN {grade_items} gi ON (gg.itemid = gi.id)
     826                   WHERE gg.userid = :userid";
     827          $params = array('categoryid' => $this->id, 'userid' => $userid);
     828  
     829          // These are all grade_item ids which grade_grades will NOT end up being 'unknown' (because they are not unknown or
     830          // because we will update them to something different that 'unknown').
     831          $giids = array_keys($usedweights + $novalue + $dropped + $extracredit);
     832  
     833          if ($giids) {
     834              // We include grade items that might not be in categoryid.
     835              list($itemsql, $itemlist) = $DB->get_in_or_equal($giids, SQL_PARAMS_NAMED, 'gg');
     836              $sql .= ' AND (gi.categoryid = :categoryid OR gi.id ' . $itemsql . ')';
     837              $params = $params + $itemlist;
     838          } else {
     839              $sql .= ' AND gi.categoryid = :categoryid';
     840          }
     841          $currentgrades = $DB->get_recordset_sql($sql, $params);
     842  
     843          // We will store here the grade_item ids that need to be updated on db.
     844          $toupdate = array();
     845  
     846          if ($currentgrades->valid()) {
     847  
     848              // Iterate through the user grades to see if we really need to update any of them.
     849              foreach ($currentgrades as $currentgrade) {
     850  
     851                  // Unset $usedweights that we do not need to update.
     852                  if (!empty($usedweights) && isset($usedweights[$currentgrade->id]) && $currentgrade->aggregationstatus === 'used') {
     853                      // We discard the ones that already have the contribution specified in $usedweights and are marked as 'used'.
     854                      if (grade_floats_equal($currentgrade->aggregationweight, $usedweights[$currentgrade->id])) {
     855                          unset($usedweights[$currentgrade->id]);
     856                      }
     857                      // Used weights can be present in multiple set_usedinaggregation arguments.
     858                      if (!isset($novalue[$currentgrade->id]) && !isset($dropped[$currentgrade->id]) &&
     859                              !isset($extracredit[$currentgrade->id])) {
     860                          continue;
     861                      }
     862                  }
     863  
     864                  // No value grades.
     865                  if (!empty($novalue) && isset($novalue[$currentgrade->id])) {
     866                      if ($currentgrade->aggregationstatus !== 'novalue' ||
     867                              grade_floats_different($currentgrade->aggregationweight, 0)) {
     868                          $toupdate['novalue'][] = $currentgrade->id;
     869                      }
     870                      continue;
     871                  }
     872  
     873                  // Dropped grades.
     874                  if (!empty($dropped) && isset($dropped[$currentgrade->id])) {
     875                      if ($currentgrade->aggregationstatus !== 'dropped' ||
     876                              grade_floats_different($currentgrade->aggregationweight, 0)) {
     877                          $toupdate['dropped'][] = $currentgrade->id;
     878                      }
     879                      continue;
     880                  }
     881  
     882                  // Extra credit grades.
     883                  if (!empty($extracredit) && isset($extracredit[$currentgrade->id])) {
     884  
     885                      // If this grade item is already marked as 'extra' and it already has the provided $usedweights value would be
     886                      // silly to update to 'used' to later update to 'extra'.
     887                      if (!empty($usedweights) && isset($usedweights[$currentgrade->id]) &&
     888                              grade_floats_equal($currentgrade->aggregationweight, $usedweights[$currentgrade->id])) {
     889                          unset($usedweights[$currentgrade->id]);
     890                      }
     891  
     892                      // Update the item to extra if it is not already marked as extra in the database or if the item's
     893                      // aggregationweight will be updated when going through $usedweights items.
     894                      if ($currentgrade->aggregationstatus !== 'extra' ||
     895                              (!empty($usedweights) && isset($usedweights[$currentgrade->id]))) {
     896                          $toupdate['extracredit'][] = $currentgrade->id;
     897                      }
     898                      continue;
     899                  }
     900  
     901                  // If is not in any of the above groups it should be set to 'unknown', checking that the item is not already
     902                  // unknown, if it is we don't need to update it.
     903                  if ($currentgrade->aggregationstatus !== 'unknown' || grade_floats_different($currentgrade->aggregationweight, 0)) {
     904                      $toupdate['unknown'][] = $currentgrade->id;
     905                  }
     906              }
     907              $currentgrades->close();
     908          }
     909  
     910          // Update items to 'unknown' status.
     911          if (!empty($toupdate['unknown'])) {
     912              list($itemsql, $itemlist) = $DB->get_in_or_equal($toupdate['unknown'], SQL_PARAMS_NAMED, 'g');
     913  
     914              $itemlist['userid'] = $userid;
     915  
     916              $sql = "UPDATE {grade_grades}
     917                         SET aggregationstatus = 'unknown',
     918                             aggregationweight = 0
     919                       WHERE itemid $itemsql AND userid = :userid";
     920              $DB->execute($sql, $itemlist);
     921          }
     922  
     923          // Update items to 'used' status and setting the proper weight.
     924          if (!empty($usedweights)) {
     925              // The usedweights items are updated individually to record the weights.
     926              foreach ($usedweights as $gradeitemid => $contribution) {
     927                  $sql = "UPDATE {grade_grades}
     928                             SET aggregationstatus = 'used',
     929                                 aggregationweight = :contribution
     930                           WHERE itemid = :itemid AND userid = :userid";
     931  
     932                  $params = array('contribution' => $contribution, 'itemid' => $gradeitemid, 'userid' => $userid);
     933                  $DB->execute($sql, $params);
     934              }
     935          }
     936  
     937          // Update items to 'novalue' status.
     938          if (!empty($toupdate['novalue'])) {
     939              list($itemsql, $itemlist) = $DB->get_in_or_equal($toupdate['novalue'], SQL_PARAMS_NAMED, 'g');
     940  
     941              $itemlist['userid'] = $userid;
     942  
     943              $sql = "UPDATE {grade_grades}
     944                         SET aggregationstatus = 'novalue',
     945                             aggregationweight = 0
     946                       WHERE itemid $itemsql AND userid = :userid";
     947  
     948              $DB->execute($sql, $itemlist);
     949          }
     950  
     951          // Update items to 'dropped' status.
     952          if (!empty($toupdate['dropped'])) {
     953              list($itemsql, $itemlist) = $DB->get_in_or_equal($toupdate['dropped'], SQL_PARAMS_NAMED, 'g');
     954  
     955              $itemlist['userid'] = $userid;
     956  
     957              $sql = "UPDATE {grade_grades}
     958                         SET aggregationstatus = 'dropped',
     959                             aggregationweight = 0
     960                       WHERE itemid $itemsql AND userid = :userid";
     961  
     962              $DB->execute($sql, $itemlist);
     963          }
     964  
     965          // Update items to 'extracredit' status.
     966          if (!empty($toupdate['extracredit'])) {
     967              list($itemsql, $itemlist) = $DB->get_in_or_equal($toupdate['extracredit'], SQL_PARAMS_NAMED, 'g');
     968  
     969              $itemlist['userid'] = $userid;
     970  
     971              $DB->set_field_select('grade_grades',
     972                                    'aggregationstatus',
     973                                    'extra',
     974                                    "itemid $itemsql AND userid = :userid",
     975                                    $itemlist);
     976          }
     977      }
     978  
     979      /**
     980       * Internal function that calculates the aggregated grade and new min/max for this grade category
     981       *
     982       * Must be public as it is used by grade_grade::get_hiding_affected()
     983       *
     984       * @param array $grade_values An array of values to be aggregated
     985       * @param array $items The array of grade_items
     986       * @since Moodle 2.6.5, 2.7.2
     987       * @param array & $weights If provided, will be filled with the normalized weights
     988       *                         for each grade_item as used in the aggregation.
     989       *                         Some rules for the weights are:
     990       *                         1. The weights must add up to 1 (unless there are extra credit)
     991       *                         2. The contributed points column must add up to the course
     992       *                         final grade and this column is calculated from these weights.
     993       * @param array  $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid)
     994       * @param array  $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid)
     995       * @return array containing values for:
     996       *                'grade' => the new calculated grade
     997       *                'grademin' => the new calculated min grade for the category
     998       *                'grademax' => the new calculated max grade for the category
     999       */
    1000      public function aggregate_values_and_adjust_bounds($grade_values,
    1001                                                         $items,
    1002                                                         & $weights = null,
    1003                                                         $grademinoverrides = array(),
    1004                                                         $grademaxoverrides = array()) {
    1005          global $CFG;
    1006  
    1007          $category_item = $this->load_grade_item();
    1008          $grademin = $category_item->grademin;
    1009          $grademax = $category_item->grademax;
    1010  
    1011          switch ($this->aggregation) {
    1012  
    1013              case GRADE_AGGREGATE_MEDIAN: // Middle point value in the set: ignores frequencies
    1014                  $num = count($grade_values);
    1015                  $grades = array_values($grade_values);
    1016  
    1017                  // The median gets 100% - others get 0.
    1018                  if ($weights !== null && $num > 0) {
    1019                      $count = 0;
    1020                      foreach ($grade_values as $itemid=>$grade_value) {
    1021                          if (($num % 2 == 0) && ($count == intval($num/2)-1 || $count == intval($num/2))) {
    1022                              $weights[$itemid] = 0.5;
    1023                          } else if (($num % 2 != 0) && ($count == intval(($num/2)-0.5))) {
    1024                              $weights[$itemid] = 1.0;
    1025                          } else {
    1026                              $weights[$itemid] = 0;
    1027                          }
    1028                          $count++;
    1029                      }
    1030                  }
    1031                  if ($num % 2 == 0) {
    1032                      $agg_grade = ($grades[intval($num/2)-1] + $grades[intval($num/2)]) / 2;
    1033                  } else {
    1034                      $agg_grade = $grades[intval(($num/2)-0.5)];
    1035                  }
    1036  
    1037                  break;
    1038  
    1039              case GRADE_AGGREGATE_MIN:
    1040                  $agg_grade = reset($grade_values);
    1041                  // Record the weights as used.
    1042                  if ($weights !== null) {
    1043                      foreach ($grade_values as $itemid=>$grade_value) {
    1044                          $weights[$itemid] = 0;
    1045                      }
    1046                  }
    1047                  // Set the first item to 1.
    1048                  $itemids = array_keys($grade_values);
    1049                  $weights[reset($itemids)] = 1;
    1050                  break;
    1051  
    1052              case GRADE_AGGREGATE_MAX:
    1053                  // Record the weights as used.
    1054                  if ($weights !== null) {
    1055                      foreach ($grade_values as $itemid=>$grade_value) {
    1056                          $weights[$itemid] = 0;
    1057                      }
    1058                  }
    1059                  // Set the last item to 1.
    1060                  $itemids = array_keys($grade_values);
    1061                  $weights[end($itemids)] = 1;
    1062                  $agg_grade = end($grade_values);
    1063                  break;
    1064  
    1065              case GRADE_AGGREGATE_MODE:       // the most common value
    1066                  // array_count_values only counts INT and STRING, so if grades are floats we must convert them to string
    1067                  $converted_grade_values = array();
    1068  
    1069                  foreach ($grade_values as $k => $gv) {
    1070  
    1071                      if (!is_int($gv) && !is_string($gv)) {
    1072                          $converted_grade_values[$k] = (string) $gv;
    1073  
    1074                      } else {
    1075                          $converted_grade_values[$k] = $gv;
    1076                      }
    1077                      if ($weights !== null) {
    1078                          $weights[$k] = 0;
    1079                      }
    1080                  }
    1081  
    1082                  $freq = array_count_values($converted_grade_values);
    1083                  arsort($freq);                      // sort by frequency keeping keys
    1084                  $top = reset($freq);               // highest frequency count
    1085                  $modes = array_keys($freq, $top);  // search for all modes (have the same highest count)
    1086                  rsort($modes, SORT_NUMERIC);       // get highest mode
    1087                  $agg_grade = reset($modes);
    1088                  // Record the weights as used.
    1089                  if ($weights !== null && $top > 0) {
    1090                      foreach ($grade_values as $k => $gv) {
    1091                          if ($gv == $agg_grade) {
    1092                              $weights[$k] = 1.0 / $top;
    1093                          }
    1094                      }
    1095                  }
    1096                  break;
    1097  
    1098              case GRADE_AGGREGATE_WEIGHTED_MEAN: // Weighted average of all existing final grades, weight specified in coef
    1099                  $weightsum = 0;
    1100                  $sum       = 0;
    1101  
    1102                  foreach ($grade_values as $itemid=>$grade_value) {
    1103                      if ($weights !== null) {
    1104                          $weights[$itemid] = $items[$itemid]->aggregationcoef;
    1105                      }
    1106                      if ($items[$itemid]->aggregationcoef <= 0) {
    1107                          continue;
    1108                      }
    1109                      $weightsum += $items[$itemid]->aggregationcoef;
    1110                      $sum       += $items[$itemid]->aggregationcoef * $grade_value;
    1111                  }
    1112                  if ($weightsum == 0) {
    1113                      $agg_grade = null;
    1114  
    1115                  } else {
    1116                      $agg_grade = $sum / $weightsum;
    1117                      if ($weights !== null) {
    1118                          // Normalise the weights.
    1119                          foreach ($weights as $itemid => $weight) {
    1120                              $weights[$itemid] = $weight / $weightsum;
    1121                          }
    1122                      }
    1123  
    1124                  }
    1125                  break;
    1126  
    1127              case GRADE_AGGREGATE_WEIGHTED_MEAN2:
    1128                  // Weighted average of all existing final grades with optional extra credit flag,
    1129                  // weight is the range of grade (usually grademax)
    1130                  $this->load_grade_item();
    1131                  $weightsum = 0;
    1132                  $sum       = null;
    1133  
    1134                  foreach ($grade_values as $itemid=>$grade_value) {
    1135                      if ($items[$itemid]->aggregationcoef > 0) {
    1136                          continue;
    1137                      }
    1138  
    1139                      $weight = $items[$itemid]->grademax - $items[$itemid]->grademin;
    1140                      if ($weight <= 0) {
    1141                          continue;
    1142                      }
    1143  
    1144                      $weightsum += $weight;
    1145                      $sum += $weight * $grade_value;
    1146                  }
    1147  
    1148                  // Handle the extra credit items separately to calculate their weight accurately.
    1149                  foreach ($grade_values as $itemid => $grade_value) {
    1150                      if ($items[$itemid]->aggregationcoef <= 0) {
    1151                          continue;
    1152                      }
    1153  
    1154                      $weight = $items[$itemid]->grademax - $items[$itemid]->grademin;
    1155                      if ($weight <= 0) {
    1156                          $weights[$itemid] = 0;
    1157                          continue;
    1158                      }
    1159  
    1160                      $oldsum = $sum;
    1161                      $weightedgrade = $weight * $grade_value;
    1162                      $sum += $weightedgrade;
    1163  
    1164                      if ($weights !== null) {
    1165                          if ($weightsum <= 0) {
    1166                              $weights[$itemid] = 0;
    1167                              continue;
    1168                          }
    1169  
    1170                          $oldgrade = $oldsum / $weightsum;
    1171                          $grade = $sum / $weightsum;
    1172                          $normoldgrade = grade_grade::standardise_score($oldgrade, 0, 1, $grademin, $grademax);
    1173                          $normgrade = grade_grade::standardise_score($grade, 0, 1, $grademin, $grademax);
    1174                          $boundedoldgrade = $this->grade_item->bounded_grade($normoldgrade);
    1175                          $boundedgrade = $this->grade_item->bounded_grade($normgrade);
    1176  
    1177                          if ($boundedgrade - $boundedoldgrade <= 0) {
    1178                              // Nothing new was added to the grade.
    1179                              $weights[$itemid] = 0;
    1180                          } else if ($boundedgrade < $normgrade) {
    1181                              // The grade has been bounded, the extra credit item needs to have a different weight.
    1182                              $gradediff = $boundedgrade - $normoldgrade;
    1183                              $gradediffnorm = grade_grade::standardise_score($gradediff, $grademin, $grademax, 0, 1);
    1184                              $weights[$itemid] = $gradediffnorm / $grade_value;
    1185                          } else {
    1186                              // Default weighting.
    1187                              $weights[$itemid] = $weight / $weightsum;
    1188                          }
    1189                      }
    1190                  }
    1191  
    1192                  if ($weightsum == 0) {
    1193                      $agg_grade = $sum; // only extra credits
    1194  
    1195                  } else {
    1196                      $agg_grade = $sum / $weightsum;
    1197                  }
    1198  
    1199                  // Record the weights as used.
    1200                  if ($weights !== null) {
    1201                      foreach ($grade_values as $itemid=>$grade_value) {
    1202                          if ($items[$itemid]->aggregationcoef > 0) {
    1203                              // Ignore extra credit items, the weights have already been computed.
    1204                              continue;
    1205                          }
    1206                          if ($weightsum > 0) {
    1207                              $weight = $items[$itemid]->grademax - $items[$itemid]->grademin;
    1208                              $weights[$itemid] = $weight / $weightsum;
    1209                          } else {
    1210                              $weights[$itemid] = 0;
    1211                          }
    1212                      }
    1213                  }
    1214                  break;
    1215  
    1216              case GRADE_AGGREGATE_EXTRACREDIT_MEAN: // special average
    1217                  $this->load_grade_item();
    1218                  $num = 0;
    1219                  $sum = null;
    1220  
    1221                  foreach ($grade_values as $itemid=>$grade_value) {
    1222                      if ($items[$itemid]->aggregationcoef == 0) {
    1223                          $num += 1;
    1224                          $sum += $grade_value;
    1225                          if ($weights !== null) {
    1226                              $weights[$itemid] = 1;
    1227                          }
    1228                      }
    1229                  }
    1230  
    1231                  // Treating the extra credit items separately to get a chance to calculate their effective weights.
    1232                  foreach ($grade_values as $itemid=>$grade_value) {
    1233                      if ($items[$itemid]->aggregationcoef > 0) {
    1234                          $oldsum = $sum;
    1235                          $sum += $items[$itemid]->aggregationcoef * $grade_value;
    1236  
    1237                          if ($weights !== null) {
    1238                              if ($num <= 0) {
    1239                                  // The category only contains extra credit items, not setting the weight.
    1240                                  continue;
    1241                              }
    1242  
    1243                              $oldgrade = $oldsum / $num;
    1244                              $grade = $sum / $num;
    1245                              $normoldgrade = grade_grade::standardise_score($oldgrade, 0, 1, $grademin, $grademax);
    1246                              $normgrade = grade_grade::standardise_score($grade, 0, 1, $grademin, $grademax);
    1247                              $boundedoldgrade = $this->grade_item->bounded_grade($normoldgrade);
    1248                              $boundedgrade = $this->grade_item->bounded_grade($normgrade);
    1249  
    1250                              if ($boundedgrade - $boundedoldgrade <= 0) {
    1251                                  // Nothing new was added to the grade.
    1252                                  $weights[$itemid] = 0;
    1253                              } else if ($boundedgrade < $normgrade) {
    1254                                  // The grade has been bounded, the extra credit item needs to have a different weight.
    1255                                  $gradediff = $boundedgrade - $normoldgrade;
    1256                                  $gradediffnorm = grade_grade::standardise_score($gradediff, $grademin, $grademax, 0, 1);
    1257                                  $weights[$itemid] = $gradediffnorm / $grade_value;
    1258                              } else {
    1259                                  // Default weighting.
    1260                                  $weights[$itemid] = 1.0 / $num;
    1261                              }
    1262                          }
    1263                      }
    1264                  }
    1265  
    1266                  if ($weights !== null && $num > 0) {
    1267                      foreach ($grade_values as $itemid=>$grade_value) {
    1268                          if ($items[$itemid]->aggregationcoef > 0) {
    1269                              // Extra credit weights were already calculated.
    1270                              continue;
    1271                          }
    1272                          if ($weights[$itemid]) {
    1273                              $weights[$itemid] = 1.0 / $num;
    1274                          }
    1275                      }
    1276                  }
    1277  
    1278                  if ($num == 0) {
    1279                      $agg_grade = $sum; // only extra credits or wrong coefs
    1280  
    1281                  } else {
    1282                      $agg_grade = $sum / $num;
    1283                  }
    1284  
    1285                  break;
    1286  
    1287              case GRADE_AGGREGATE_SUM:    // Add up all the items.
    1288                  $this->load_grade_item();
    1289                  $num = count($grade_values);
    1290                  $sum = 0;
    1291  
    1292                  // This setting indicates if we should use algorithm prior to MDL-49257 fix for calculating extra credit weights.
    1293                  // Even though old algorith has bugs in it, we need to preserve existing grades.
    1294                  $gradebookcalculationfreeze = 'gradebook_calculations_freeze_' . $this->courseid;
    1295                  $oldextracreditcalculation = isset($CFG->$gradebookcalculationfreeze)
    1296                          && ($CFG->$gradebookcalculationfreeze <= 20150619);
    1297  
    1298                  $sumweights = 0;
    1299                  $grademin = 0;
    1300                  $grademax = 0;
    1301                  $extracredititems = array();
    1302                  foreach ($grade_values as $itemid => $gradevalue) {
    1303                      // We need to check if the grademax/min was adjusted per user because of excluded items.
    1304                      $usergrademin = $items[$itemid]->grademin;
    1305                      $usergrademax = $items[$itemid]->grademax;
    1306                      if (isset($grademinoverrides[$itemid])) {
    1307                          $usergrademin = $grademinoverrides[$itemid];
    1308                      }
    1309                      if (isset($grademaxoverrides[$itemid])) {
    1310                          $usergrademax = $grademaxoverrides[$itemid];
    1311                      }
    1312  
    1313                      // Keep track of the extra credit items, we will need them later on.
    1314                      if ($items[$itemid]->aggregationcoef > 0) {
    1315                          $extracredititems[$itemid] = $items[$itemid];
    1316                      }
    1317  
    1318                      // Ignore extra credit and items with a weight of 0.
    1319                      if (!isset($extracredititems[$itemid]) && $items[$itemid]->aggregationcoef2 > 0) {
    1320                          $grademin += $usergrademin;
    1321                          $grademax += $usergrademax;
    1322                          $sumweights += $items[$itemid]->aggregationcoef2;
    1323                      }
    1324                  }
    1325                  $userweights = array();
    1326                  $totaloverriddenweight = 0;
    1327                  $totaloverriddengrademax = 0;
    1328                  // We first need to rescale all manually assigned weights down by the
    1329                  // percentage of weights missing from the category.
    1330                  foreach ($grade_values as $itemid => $gradevalue) {
    1331                      if ($items[$itemid]->weightoverride) {
    1332                          if ($items[$itemid]->aggregationcoef2 <= 0) {
    1333                              // Records the weight of 0 and continue.
    1334                              $userweights[$itemid] = 0;
    1335                              continue;
    1336                          }
    1337                          $userweights[$itemid] = $sumweights ? ($items[$itemid]->aggregationcoef2 / $sumweights) : 0;
    1338                          if (!$oldextracreditcalculation && isset($extracredititems[$itemid])) {
    1339                              // Extra credit items do not affect totals.
    1340                              continue;
    1341                          }
    1342                          $totaloverriddenweight += $userweights[$itemid];
    1343                          $usergrademax = $items[$itemid]->grademax;
    1344                          if (isset($grademaxoverrides[$itemid])) {
    1345                              $usergrademax = $grademaxoverrides[$itemid];
    1346                          }
    1347                          $totaloverriddengrademax += $usergrademax;
    1348                      }
    1349                  }
    1350                  $nonoverriddenpoints = $grademax - $totaloverriddengrademax;
    1351  
    1352                  // Then we need to recalculate the automatic weights except for extra credit items.
    1353                  foreach ($grade_values as $itemid => $gradevalue) {
    1354                      if (!$items[$itemid]->weightoverride && ($oldextracreditcalculation || !isset($extracredititems[$itemid]))) {
    1355                          $usergrademax = $items[$itemid]->grademax;
    1356                          if (isset($grademaxoverrides[$itemid])) {
    1357                              $usergrademax = $grademaxoverrides[$itemid];
    1358                          }
    1359                          if ($nonoverriddenpoints > 0) {
    1360                              $userweights[$itemid] = ($usergrademax/$nonoverriddenpoints) * (1 - $totaloverriddenweight);
    1361                          } else {
    1362                              $userweights[$itemid] = 0;
    1363                              if ($items[$itemid]->aggregationcoef2 > 0) {
    1364                                  // Items with a weight of 0 should not count for the grade max,
    1365                                  // though this only applies if the weight was changed to 0.
    1366                                  $grademax -= $usergrademax;
    1367                              }
    1368                          }
    1369                      }
    1370                  }
    1371  
    1372                  // Now when we finally know the grademax we can adjust the automatic weights of extra credit items.
    1373                  if (!$oldextracreditcalculation) {
    1374                      foreach ($grade_values as $itemid => $gradevalue) {
    1375                          if (!$items[$itemid]->weightoverride && isset($extracredititems[$itemid])) {
    1376                              $usergrademax = $items[$itemid]->grademax;
    1377                              if (isset($grademaxoverrides[$itemid])) {
    1378                                  $usergrademax = $grademaxoverrides[$itemid];
    1379                              }
    1380                              $userweights[$itemid] = $grademax ? ($usergrademax / $grademax) : 0;
    1381                          }
    1382                      }
    1383                  }
    1384  
    1385                  // We can use our freshly corrected weights below.
    1386                  foreach ($grade_values as $itemid => $gradevalue) {
    1387                      if (isset($extracredititems[$itemid])) {
    1388                          // We skip the extra credit items first.
    1389                          continue;
    1390                      }
    1391                      $sum += $gradevalue * $userweights[$itemid] * $grademax;
    1392                      if ($weights !== null) {
    1393                          $weights[$itemid] = $userweights[$itemid];
    1394                      }
    1395                  }
    1396  
    1397                  // No we proceed with the extra credit items. They might have a different final
    1398                  // weight in case the final grade was bounded. So we need to treat them different.
    1399                  // Also, as we need to use the bounded_grade() method, we have to inject the
    1400                  // right values there, and restore them afterwards.
    1401                  $oldgrademax = $this->grade_item->grademax;
    1402                  $oldgrademin = $this->grade_item->grademin;
    1403                  foreach ($grade_values as $itemid => $gradevalue) {
    1404                      if (!isset($extracredititems[$itemid])) {
    1405                          continue;
    1406                      }
    1407                      $oldsum = $sum;
    1408                      $weightedgrade = $gradevalue * $userweights[$itemid] * $grademax;
    1409                      $sum += $weightedgrade;
    1410  
    1411                      // Only go through this when we need to record the weights.
    1412                      if ($weights !== null) {
    1413                          if ($grademax <= 0) {
    1414                              // There are only extra credit items in this category,
    1415                              // all the weights should be accurate (and be 0).
    1416                              $weights[$itemid] = $userweights[$itemid];
    1417                              continue;
    1418                          }
    1419  
    1420                          $oldfinalgrade = $this->grade_item->bounded_grade($oldsum);
    1421                          $newfinalgrade = $this->grade_item->bounded_grade($sum);
    1422                          $finalgradediff = $newfinalgrade - $oldfinalgrade;
    1423                          if ($finalgradediff <= 0) {
    1424                              // This item did not contribute to the category total at all.
    1425                              $weights[$itemid] = 0;
    1426                          } else if ($finalgradediff < $weightedgrade) {
    1427                              // The weight needs to be adjusted because only a portion of the
    1428                              // extra credit item contributed to the category total.
    1429                              $weights[$itemid] = $finalgradediff / ($gradevalue * $grademax);
    1430                          } else {
    1431                              // The weight was accurate.
    1432                              $weights[$itemid] = $userweights[$itemid];
    1433                          }
    1434                      }
    1435                  }
    1436                  $this->grade_item->grademax = $oldgrademax;
    1437                  $this->grade_item->grademin = $oldgrademin;
    1438  
    1439                  if ($grademax > 0) {
    1440                      $agg_grade = $sum / $grademax; // Re-normalize score.
    1441                  } else {
    1442                      // Every item in the category is extra credit.
    1443                      $agg_grade = $sum;
    1444                      $grademax = $sum;
    1445                  }
    1446  
    1447                  break;
    1448  
    1449              case GRADE_AGGREGATE_MEAN:    // Arithmetic average of all grade items (if ungraded aggregated, NULL counted as minimum)
    1450              default:
    1451                  $num = count($grade_values);
    1452                  $sum = array_sum($grade_values);
    1453                  $agg_grade = $sum / $num;
    1454                  // Record the weights evenly.
    1455                  if ($weights !== null && $num > 0) {
    1456                      foreach ($grade_values as $itemid=>$grade_value) {
    1457                          $weights[$itemid] = 1.0 / $num;
    1458                      }
    1459                  }
    1460                  break;
    1461          }
    1462  
    1463          return array('grade' => $agg_grade, 'grademin' => $grademin, 'grademax' => $grademax);
    1464      }
    1465  
    1466      /**
    1467       * Internal function that calculates the aggregated grade for this grade category
    1468       *
    1469       * Must be public as it is used by grade_grade::get_hiding_affected()
    1470       *
    1471       * @deprecated since Moodle 2.8
    1472       * @param array $grade_values An array of values to be aggregated
    1473       * @param array $items The array of grade_items
    1474       * @return float The aggregate grade for this grade category
    1475       */
    1476      public function aggregate_values($grade_values, $items) {
    1477          debugging('grade_category::aggregate_values() is deprecated.
    1478                     Call grade_category::aggregate_values_and_adjust_bounds() instead.', DEBUG_DEVELOPER);
    1479          $result = $this->aggregate_values_and_adjust_bounds($grade_values, $items);
    1480          return $result['grade'];
    1481      }
    1482  
    1483      /**
    1484       * Some aggregation types may need to update their max grade.
    1485       *
    1486       * This must be executed after updating the weights as it relies on them.
    1487       *
    1488       * @return void
    1489       */
    1490      private function auto_update_max() {
    1491          global $CFG, $DB;
    1492          if ($this->aggregation != GRADE_AGGREGATE_SUM) {
    1493              // not needed at all
    1494              return;
    1495          }
    1496  
    1497          // Find grade items of immediate children (category or grade items) and force site settings.
    1498          $this->load_grade_item();
    1499          $depends_on = $this->grade_item->depends_on();
    1500  
    1501          // Check to see if the gradebook is frozen. This allows grades to not be altered at all until a user verifies that they
    1502          // wish to update the grades.
    1503          $gradebookcalculationfreeze = 'gradebook_calculations_freeze_' . $this->courseid;
    1504          $oldextracreditcalculation = isset($CFG->$gradebookcalculationfreeze) && ($CFG->$gradebookcalculationfreeze <= 20150627);
    1505          // Only run if the gradebook isn't frozen.
    1506          if (!$oldextracreditcalculation) {
    1507              // Don't automatically update the max for calculated items.
    1508              if ($this->grade_item->is_calculated()) {
    1509                  return;
    1510              }
    1511          }
    1512  
    1513          $items = false;
    1514          if (!empty($depends_on)) {
    1515              list($usql, $params) = $DB->get_in_or_equal($depends_on);
    1516              $sql = "SELECT *
    1517                        FROM {grade_items}
    1518                       WHERE id $usql";
    1519              $items = $DB->get_records_sql($sql, $params);
    1520          }
    1521  
    1522          if (!$items) {
    1523  
    1524              if ($this->grade_item->grademax != 0 or $this->grade_item->gradetype != GRADE_TYPE_VALUE) {
    1525                  $this->grade_item->grademax  = 0;
    1526                  $this->grade_item->grademin  = 0;
    1527                  $this->grade_item->gradetype = GRADE_TYPE_VALUE;
    1528                  $this->grade_item->update('aggregation');
    1529              }
    1530              return;
    1531          }
    1532  
    1533          //find max grade possible
    1534          $maxes = array();
    1535  
    1536          foreach ($items as $item) {
    1537  
    1538              if ($item->aggregationcoef > 0) {
    1539                  // extra credit from this activity - does not affect total
    1540                  continue;
    1541              } else if ($item->aggregationcoef2 <= 0) {
    1542                  // Items with a weight of 0 do not affect the total.
    1543                  continue;
    1544              }
    1545  
    1546              if ($item->gradetype == GRADE_TYPE_VALUE) {
    1547                  $maxes[$item->id] = $item->grademax;
    1548  
    1549              } else if ($item->gradetype == GRADE_TYPE_SCALE) {
    1550                  $maxes[$item->id] = $item->grademax; // 0 = nograde, 1 = first scale item, 2 = second scale item
    1551              }
    1552          }
    1553  
    1554          if ($this->can_apply_limit_rules()) {
    1555              // Apply droplow and keephigh.
    1556              $this->apply_limit_rules($maxes, $items);
    1557          }
    1558          $max = array_sum($maxes);
    1559  
    1560          // update db if anything changed
    1561          if ($this->grade_item->grademax != $max or $this->grade_item->grademin != 0 or $this->grade_item->gradetype != GRADE_TYPE_VALUE) {
    1562              $this->grade_item->grademax  = $max;
    1563              $this->grade_item->grademin  = 0;
    1564              $this->grade_item->gradetype = GRADE_TYPE_VALUE;
    1565              $this->grade_item->update('aggregation');
    1566          }
    1567      }
    1568  
    1569      /**
    1570       * Recalculate the weights of the grade items in this category.
    1571       *
    1572       * The category total is not updated here, a further call to
    1573       * {@link self::auto_update_max()} is required.
    1574       *
    1575       * @return void
    1576       */
    1577      private function auto_update_weights() {
    1578          global $CFG;
    1579          if ($this->aggregation != GRADE_AGGREGATE_SUM) {
    1580              // This is only required if we are using natural weights.
    1581              return;
    1582          }
    1583          $children = $this->get_children();
    1584  
    1585          $gradeitem = null;
    1586  
    1587          // Calculate the sum of the grademax's of all the items within this category.
    1588          $totalnonoverriddengrademax = 0;
    1589          $totalgrademax = 0;
    1590  
    1591          // Out of 1, how much weight has been manually overriden by a user?
    1592          $totaloverriddenweight  = 0;
    1593          $totaloverriddengrademax  = 0;
    1594  
    1595          // Has every assessment in this category been overridden?
    1596          $automaticgradeitemspresent = false;
    1597          // Does the grade item require normalising?
    1598          $requiresnormalising = false;
    1599  
    1600          // This array keeps track of the id and weight of every grade item that has been overridden.
    1601          $overridearray = array();
    1602          foreach ($children as $sortorder => $child) {
    1603              $gradeitem = null;
    1604  
    1605              if ($child['type'] == 'item') {
    1606                  $gradeitem = $child['object'];
    1607              } else if ($child['type'] == 'category') {
    1608                  $gradeitem = $child['object']->load_grade_item();
    1609              }
    1610  
    1611              if ($gradeitem->gradetype == GRADE_TYPE_NONE || $gradeitem->gradetype == GRADE_TYPE_TEXT) {
    1612                  // Text items and none items do not have a weight.
    1613                  continue;
    1614              } else if (!$this->aggregateoutcomes && $gradeitem->is_outcome_item()) {
    1615                  // We will not aggregate outcome items, so we can ignore them.
    1616                  continue;
    1617              } else if (empty($CFG->grade_includescalesinaggregation) && $gradeitem->gradetype == GRADE_TYPE_SCALE) {
    1618                  // The scales are not included in the aggregation, ignore them.
    1619                  continue;
    1620              }
    1621  
    1622              // Record the ID and the weight for this grade item.
    1623              $overridearray[$gradeitem->id] = array();
    1624              $overridearray[$gradeitem->id]['extracredit'] = intval($gradeitem->aggregationcoef);
    1625              $overridearray[$gradeitem->id]['weight'] = $gradeitem->aggregationcoef2;
    1626              $overridearray[$gradeitem->id]['weightoverride'] = intval($gradeitem->weightoverride);
    1627              // If this item has had its weight overridden then set the flag to true, but
    1628              // only if all previous items were also overridden. Note that extra credit items
    1629              // are counted as overridden grade items.
    1630              if (!$gradeitem->weightoverride && $gradeitem->aggregationcoef == 0) {
    1631                  $automaticgradeitemspresent = true;
    1632              }
    1633  
    1634              if ($gradeitem->aggregationcoef > 0) {
    1635                  // An extra credit grade item doesn't contribute to $totaloverriddengrademax.
    1636                  continue;
    1637              } else if ($gradeitem->weightoverride > 0 && $gradeitem->aggregationcoef2 <= 0) {
    1638                  // An overriden item that defines a weight of 0 does not contribute to $totaloverriddengrademax.
    1639                  continue;
    1640              }
    1641  
    1642              $totalgrademax += $gradeitem->grademax;
    1643              if ($gradeitem->weightoverride > 0) {
    1644                  $totaloverriddenweight += $gradeitem->aggregationcoef2;
    1645                  $totaloverriddengrademax += $gradeitem->grademax;
    1646              }
    1647          }
    1648  
    1649          // Initialise this variable (used to keep track of the weight override total).
    1650          $normalisetotal = 0;
    1651          // Keep a record of how much the override total is to see if it is above 100. It it is then we need to set the
    1652          // other weights to zero and normalise the others.
    1653          $overriddentotal = 0;
    1654          // If the overridden weight total is higher than 1 then set the other untouched weights to zero.
    1655          $setotherweightstozero = false;
    1656          // Total up all of the weights.
    1657          foreach ($overridearray as $gradeitemdetail) {
    1658              // If the grade item has extra credit, then don't add it to the normalisetotal.
    1659              if (!$gradeitemdetail['extracredit']) {
    1660                  $normalisetotal += $gradeitemdetail['weight'];
    1661              }
    1662              // The overridden total comprises of items that are set as overridden, that aren't extra credit and have a value
    1663              // greater than zero.
    1664              if ($gradeitemdetail['weightoverride'] && !$gradeitemdetail['extracredit'] && $gradeitemdetail['weight'] > 0) {
    1665                  // Add overriden weights up to see if they are greater than 1.
    1666                  $overriddentotal += $gradeitemdetail['weight'];
    1667              }
    1668          }
    1669          if ($overriddentotal > 1) {
    1670              // Make sure that this catergory of weights gets normalised.
    1671              $requiresnormalising = true;
    1672              // The normalised weights are only the overridden weights, so we just use the total of those.
    1673              $normalisetotal = $overriddentotal;
    1674          }
    1675  
    1676          $totalnonoverriddengrademax = $totalgrademax - $totaloverriddengrademax;
    1677  
    1678          // This setting indicates if we should use algorithm prior to MDL-49257 fix for calculating extra credit weights.
    1679          // Even though old algorith has bugs in it, we need to preserve existing grades.
    1680          $gradebookcalculationfreeze = (int)get_config('core', 'gradebook_calculations_freeze_' . $this->courseid);
    1681          $oldextracreditcalculation = $gradebookcalculationfreeze && ($gradebookcalculationfreeze <= 20150619);
    1682  
    1683          reset($children);
    1684          foreach ($children as $sortorder => $child) {
    1685              $gradeitem = null;
    1686  
    1687              if ($child['type'] == 'item') {
    1688                  $gradeitem = $child['object'];
    1689              } else if ($child['type'] == 'category') {
    1690                  $gradeitem = $child['object']->load_grade_item();
    1691              }
    1692  
    1693              if ($gradeitem->gradetype == GRADE_TYPE_NONE || $gradeitem->gradetype == GRADE_TYPE_TEXT) {
    1694                  // Text items and none items do not have a weight, no need to set their weight to
    1695                  // zero as they must never be used during aggregation.
    1696                  continue;
    1697              } else if (!$this->aggregateoutcomes && $gradeitem->is_outcome_item()) {
    1698                  // We will not aggregate outcome items, so we can ignore updating their weights.
    1699                  continue;
    1700              } else if (empty($CFG->grade_includescalesinaggregation) && $gradeitem->gradetype == GRADE_TYPE_SCALE) {
    1701                  // We will not aggregate the scales, so we can ignore upating their weights.
    1702                  continue;
    1703              } else if (!$oldextracreditcalculation && $gradeitem->aggregationcoef > 0 && $gradeitem->weightoverride) {
    1704                  // For an item with extra credit ignore other weigths and overrides but do not change anything at all
    1705                  // if it's weight was already overridden.
    1706                  continue;
    1707              }
    1708  
    1709              // Store the previous value here, no need to update if it is the same value.
    1710              $prevaggregationcoef2 = $gradeitem->aggregationcoef2;
    1711  
    1712              if (!$oldextracreditcalculation && $gradeitem->aggregationcoef > 0 && !$gradeitem->weightoverride) {
    1713                  // For an item with extra credit ignore other weigths and overrides.
    1714                  $gradeitem->aggregationcoef2 = $totalgrademax ? ($gradeitem->grademax / $totalgrademax) : 0;
    1715  
    1716              } else if (!$gradeitem->weightoverride) {
    1717                  // Calculations with a grade maximum of zero will cause problems. Just set the weight to zero.
    1718                  if ($totaloverriddenweight >= 1 || $totalnonoverriddengrademax == 0 || $gradeitem->grademax == 0) {
    1719                      // There is no more weight to distribute.
    1720                      $gradeitem->aggregationcoef2 = 0;
    1721                  } else {
    1722                      // Calculate this item's weight as a percentage of the non-overridden total grade maxes
    1723                      // then convert it to a proportion of the available non-overriden weight.
    1724                      $gradeitem->aggregationcoef2 = ($gradeitem->grademax/$totalnonoverriddengrademax) *
    1725                              (1 - $totaloverriddenweight);
    1726                  }
    1727  
    1728              } else if ((!$automaticgradeitemspresent && $normalisetotal != 1) || ($requiresnormalising)
    1729                      || $overridearray[$gradeitem->id]['weight'] < 0) {
    1730                  // Just divide the overriden weight for this item against the total weight override of all
    1731                  // items in this category.
    1732                  if ($normalisetotal == 0 || $overridearray[$gradeitem->id]['weight'] < 0) {
    1733                      // If the normalised total equals zero, or the weight value is less than zero,
    1734                      // set the weight for the grade item to zero.
    1735                      $gradeitem->aggregationcoef2 = 0;
    1736                  } else {
    1737                      $gradeitem->aggregationcoef2 = $overridearray[$gradeitem->id]['weight'] / $normalisetotal;
    1738                  }
    1739              }
    1740  
    1741              if (grade_floatval($prevaggregationcoef2) !== grade_floatval($gradeitem->aggregationcoef2)) {
    1742                  // Update the grade item to reflect these changes.
    1743                  $gradeitem->update();
    1744              }
    1745          }
    1746      }
    1747  
    1748      /**
    1749       * Given an array of grade values (numerical indices) applies droplow or keephigh rules to limit the final array.
    1750       *
    1751       * @param array $grade_values itemid=>$grade_value float
    1752       * @param array $items grade item objects
    1753       * @return array Limited grades.
    1754       */
    1755      public function apply_limit_rules(&$grade_values, $items) {
    1756          $extraused = $this->is_extracredit_used();
    1757  
    1758          if (!empty($this->droplow)) {
    1759              asort($grade_values, SORT_NUMERIC);
    1760              $dropped = 0;
    1761  
    1762              // If we have fewer grade items available to drop than $this->droplow, use this flag to escape the loop
    1763              // May occur because of "extra credit" or if droplow is higher than the number of grade items
    1764              $droppedsomething = true;
    1765  
    1766              while ($dropped < $this->droplow && $droppedsomething) {
    1767                  $droppedsomething = false;
    1768  
    1769                  $grade_keys = array_keys($grade_values);
    1770                  $gradekeycount = count($grade_keys);
    1771  
    1772                  if ($gradekeycount === 0) {
    1773                      //We've dropped all grade items
    1774                      break;
    1775                  }
    1776  
    1777                  $originalindex = $founditemid = $foundmax = null;
    1778  
    1779                  // Find the first remaining grade item that is available to be dropped
    1780                  foreach ($grade_keys as $gradekeyindex=>$gradekey) {
    1781                      if (!$extraused || $items[$gradekey]->aggregationcoef <= 0) {
    1782                          // Found a non-extra credit grade item that is eligible to be dropped
    1783                          $originalindex = $gradekeyindex;
    1784                          $founditemid = $grade_keys[$originalindex];
    1785                          $foundmax = $items[$founditemid]->grademax;
    1786                          break;
    1787                      }
    1788                  }
    1789  
    1790                  if (empty($founditemid)) {
    1791                      // No grade items available to drop
    1792                      break;
    1793                  }
    1794  
    1795                  // Now iterate over the remaining grade items
    1796                  // We're looking for other grade items with the same grade value but a higher grademax
    1797                  $i = 1;
    1798                  while ($originalindex + $i < $gradekeycount) {
    1799  
    1800                      $possibleitemid = $grade_keys[$originalindex+$i];
    1801                      $i++;
    1802  
    1803                      if ($grade_values[$founditemid] != $grade_values[$possibleitemid]) {
    1804                          // The next grade item has a different grade value. Stop looking.
    1805                          break;
    1806                      }
    1807  
    1808                      if ($extraused && $items[$possibleitemid]->aggregationcoef > 0) {
    1809                          // Don't drop extra credit grade items. Continue the search.
    1810                          continue;
    1811                      }
    1812  
    1813                      if ($foundmax < $items[$possibleitemid]->grademax) {
    1814                          // Found a grade item with the same grade value and a higher grademax
    1815                          $foundmax = $items[$possibleitemid]->grademax;
    1816                          $founditemid = $possibleitemid;
    1817                          // Continue searching to see if there is an even higher grademax
    1818                      }
    1819                  }
    1820  
    1821                  // Now drop whatever grade item we have found
    1822                  unset($grade_values[$founditemid]);
    1823                  $dropped++;
    1824                  $droppedsomething = true;
    1825              }
    1826  
    1827          } else if (!empty($this->keephigh)) {
    1828              arsort($grade_values, SORT_NUMERIC);
    1829              $kept = 0;
    1830  
    1831              foreach ($grade_values as $itemid=>$value) {
    1832  
    1833                  if ($extraused and $items[$itemid]->aggregationcoef > 0) {
    1834                      // we keep all extra credits
    1835  
    1836                  } else if ($kept < $this->keephigh) {
    1837                      $kept++;
    1838  
    1839                  } else {
    1840                      unset($grade_values[$itemid]);
    1841                  }
    1842              }
    1843          }
    1844      }
    1845  
    1846      /**
    1847       * Returns whether or not we can apply the limit rules.
    1848       *
    1849       * There are cases where drop lowest or keep highest should not be used
    1850       * at all. This method will determine whether or not this logic can be
    1851       * applied considering the current setup of the category.
    1852       *
    1853       * @return bool
    1854       */
    1855      public function can_apply_limit_rules() {
    1856          if ($this->canapplylimitrules !== null) {
    1857              return $this->canapplylimitrules;
    1858          }
    1859  
    1860          // Set it to be supported by default.
    1861          $this->canapplylimitrules = true;
    1862  
    1863          // Natural aggregation.
    1864          if ($this->aggregation == GRADE_AGGREGATE_SUM) {
    1865              $canapply = true;
    1866  
    1867              // Check until one child breaks the rules.
    1868              $gradeitems = $this->get_children();
    1869              $validitems = 0;
    1870              $lastweight = null;
    1871              $lastmaxgrade = null;
    1872              foreach ($gradeitems as $gradeitem) {
    1873                  $gi = $gradeitem['object'];
    1874  
    1875                  if ($gradeitem['type'] == 'category') {
    1876                      // Sub categories are not allowed because they can have dynamic weights/maxgrades.
    1877                      $canapply = false;
    1878                      break;
    1879                  }
    1880  
    1881                  if ($gi->aggregationcoef > 0) {
    1882                      // Extra credit items are not allowed.
    1883                      $canapply = false;
    1884                      break;
    1885                  }
    1886  
    1887                  if ($lastweight !== null && $lastweight != $gi->aggregationcoef2) {
    1888                      // One of the weight differs from another item.
    1889                      $canapply = false;
    1890                      break;
    1891                  }
    1892  
    1893                  if ($lastmaxgrade !== null && $lastmaxgrade != $gi->grademax) {
    1894                      // One of the max grade differ from another item. This is not allowed for now
    1895                      // because we could be end up with different max grade between users for this category.
    1896                      $canapply = false;
    1897                      break;
    1898                  }
    1899  
    1900                  $lastweight = $gi->aggregationcoef2;
    1901                  $lastmaxgrade = $gi->grademax;
    1902              }
    1903  
    1904              $this->canapplylimitrules = $canapply;
    1905          }
    1906  
    1907          return $this->canapplylimitrules;
    1908      }
    1909  
    1910      /**
    1911       * Returns true if category uses extra credit of any kind
    1912       *
    1913       * @return bool True if extra credit used
    1914       */
    1915      public function is_extracredit_used() {
    1916          return self::aggregation_uses_extracredit($this->aggregation);
    1917      }
    1918  
    1919      /**
    1920       * Returns true if aggregation passed is using extracredit.
    1921       *
    1922       * @param int $aggregation Aggregation const.
    1923       * @return bool True if extra credit used
    1924       */
    1925      public static function aggregation_uses_extracredit($aggregation) {
    1926          return ($aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN2
    1927               or $aggregation == GRADE_AGGREGATE_EXTRACREDIT_MEAN
    1928               or $aggregation == GRADE_AGGREGATE_SUM);
    1929      }
    1930  
    1931      /**
    1932       * Returns true if category uses special aggregation coefficient
    1933       *
    1934       * @return bool True if an aggregation coefficient is being used
    1935       */
    1936      public function is_aggregationcoef_used() {
    1937          return self::aggregation_uses_aggregationcoef($this->aggregation);
    1938  
    1939      }
    1940  
    1941      /**
    1942       * Returns true if aggregation uses aggregationcoef
    1943       *
    1944       * @param int $aggregation Aggregation const.
    1945       * @return bool True if an aggregation coefficient is being used
    1946       */
    1947      public static function aggregation_uses_aggregationcoef($aggregation) {
    1948          return ($aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN
    1949               or $aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN2
    1950               or $aggregation == GRADE_AGGREGATE_EXTRACREDIT_MEAN
    1951               or $aggregation == GRADE_AGGREGATE_SUM);
    1952  
    1953      }
    1954  
    1955      /**
    1956       * Recursive function to find which weight/extra credit field to use in the grade item form.
    1957       *
    1958       * @param string $first Whether or not this is the first item in the recursion
    1959       * @return string
    1960       */
    1961      public function get_coefstring($first=true) {
    1962          if (!is_null($this->coefstring)) {
    1963              return $this->coefstring;
    1964          }
    1965  
    1966          $overriding_coefstring = null;
    1967  
    1968          // Stop recursing upwards if this category has no parent
    1969          if (!$first) {
    1970  
    1971              if ($parent_category = $this->load_parent_category()) {
    1972                  return $parent_category->get_coefstring(false);
    1973  
    1974              } else {
    1975                  return null;
    1976              }
    1977  
    1978          } else if ($first) {
    1979  
    1980              if ($parent_category = $this->load_parent_category()) {
    1981                  $overriding_coefstring = $parent_category->get_coefstring(false);
    1982              }
    1983          }
    1984  
    1985          // If an overriding coefstring has trickled down from one of the parent categories, return it. Otherwise, return self.
    1986          if (!is_null($overriding_coefstring)) {
    1987              return $overriding_coefstring;
    1988          }
    1989  
    1990          // No parent category is overriding this category's aggregation, return its string
    1991          if ($this->aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN) {
    1992              $this->coefstring = 'aggregationcoefweight';
    1993  
    1994          } else if ($this->aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN2) {
    1995              $this->coefstring = 'aggregationcoefextrasum';
    1996  
    1997          } else if ($this->aggregation == GRADE_AGGREGATE_EXTRACREDIT_MEAN) {
    1998              $this->coefstring = 'aggregationcoefextraweight';
    1999  
    2000          } else if ($this->aggregation == GRADE_AGGREGATE_SUM) {
    2001              $this->coefstring = 'aggregationcoefextraweightsum';
    2002  
    2003          } else {
    2004              $this->coefstring = 'aggregationcoef';
    2005          }
    2006          return $this->coefstring;
    2007      }
    2008  
    2009      /**
    2010       * Returns tree with all grade_items and categories as elements
    2011       *
    2012       * @param int $courseid The course ID
    2013       * @param bool $include_category_items as category children
    2014       * @return array
    2015       */
    2016      public static function fetch_course_tree($courseid, $include_category_items=false) {
    2017          $course_category = grade_category::fetch_course_category($courseid);
    2018          $category_array = array('object'=>$course_category, 'type'=>'category', 'depth'=>1,
    2019                                  'children'=>$course_category->get_children($include_category_items));
    2020  
    2021          $course_category->sortorder = $course_category->get_sortorder();
    2022          $sortorder = $course_category->get_sortorder();
    2023          return grade_category::_fetch_course_tree_recursion($category_array, $sortorder);
    2024      }
    2025  
    2026      /**
    2027       * An internal function that recursively sorts grade categories within a course
    2028       *
    2029       * @param array $category_array The seed of the recursion
    2030       * @param int   $sortorder The current sortorder
    2031       * @return array An array containing 'object', 'type', 'depth' and optionally 'children'
    2032       */
    2033      static private function _fetch_course_tree_recursion($category_array, &$sortorder) {
    2034          if (isset($category_array['object']->gradetype) && $category_array['object']->gradetype==GRADE_TYPE_NONE) {
    2035              return null;
    2036          }
    2037  
    2038          // store the grade_item or grade_category instance with extra info
    2039          $result = array('object'=>$category_array['object'], 'type'=>$category_array['type'], 'depth'=>$category_array['depth']);
    2040  
    2041          // reuse final grades if there
    2042          if (array_key_exists('finalgrades', $category_array)) {
    2043              $result['finalgrades'] = $category_array['finalgrades'];
    2044          }
    2045  
    2046          // recursively resort children
    2047          if (!empty($category_array['children'])) {
    2048              $result['children'] = array();
    2049              //process the category item first
    2050              $child = null;
    2051  
    2052              foreach ($category_array['children'] as $oldorder=>$child_array) {
    2053  
    2054                  if ($child_array['type'] == 'courseitem' or $child_array['type'] == 'categoryitem') {
    2055                      $child = grade_category::_fetch_course_tree_recursion($child_array, $sortorder);
    2056                      if (!empty($child)) {
    2057                          $result['children'][$sortorder] = $child;
    2058                      }
    2059                  }
    2060              }
    2061  
    2062              foreach ($category_array['children'] as $oldorder=>$child_array) {
    2063  
    2064                  if ($child_array['type'] != 'courseitem' and $child_array['type'] != 'categoryitem') {
    2065                      $child = grade_category::_fetch_course_tree_recursion($child_array, $sortorder);
    2066                      if (!empty($child)) {
    2067                          $result['children'][++$sortorder] = $child;
    2068                      }
    2069                  }
    2070              }
    2071          }
    2072  
    2073          return $result;
    2074      }
    2075  
    2076      /**
    2077       * Fetches and returns all the children categories and/or grade_items belonging to this category.
    2078       * By default only returns the immediate children (depth=1), but deeper levels can be requested,
    2079       * as well as all levels (0). The elements are indexed by sort order.
    2080       *
    2081       * @param bool $include_category_items Whether or not to include category grade_items in the children array
    2082       * @return array Array of child objects (grade_category and grade_item).
    2083       */
    2084      public function get_children($include_category_items=false) {
    2085          global $DB;
    2086  
    2087          // This function must be as fast as possible ;-)
    2088          // fetch all course grade items and categories into memory - we do not expect hundreds of these in course
    2089          // we have to limit the number of queries though, because it will be used often in grade reports
    2090  
    2091          $cats  = $DB->get_records('grade_categories', array('courseid' => $this->courseid));
    2092          $items = $DB->get_records('grade_items', array('courseid' => $this->courseid));
    2093  
    2094          // init children array first
    2095          foreach ($cats as $catid=>$cat) {
    2096              $cats[$catid]->children = array();
    2097          }
    2098  
    2099          //first attach items to cats and add category sortorder
    2100          foreach ($items as $item) {
    2101  
    2102              if ($item->itemtype == 'course' or $item->itemtype == 'category') {
    2103                  $cats[$item->iteminstance]->sortorder = $item->sortorder;
    2104  
    2105                  if (!$include_category_items) {
    2106                      continue;
    2107                  }
    2108                  $categoryid = $item->iteminstance;
    2109  
    2110              } else {
    2111                  $categoryid = $item->categoryid;
    2112                  if (empty($categoryid)) {
    2113                      debugging('Found a grade item that isnt in a category');
    2114                  }
    2115              }
    2116  
    2117              // prevent problems with duplicate sortorders in db
    2118              $sortorder = $item->sortorder;
    2119  
    2120              while (array_key_exists($categoryid, $cats)
    2121                  && array_key_exists($sortorder, $cats[$categoryid]->children)) {
    2122  
    2123                  $sortorder++;
    2124              }
    2125  
    2126              $cats[$categoryid]->children[$sortorder] = $item;
    2127  
    2128          }
    2129  
    2130          // now find the requested category and connect categories as children
    2131          $category = false;
    2132  
    2133          foreach ($cats as $catid=>$cat) {
    2134  
    2135              if (empty($cat->parent)) {
    2136  
    2137                  if ($cat->path !== '/'.$cat->id.'/') {
    2138                      $grade_category = new grade_category($cat, false);
    2139                      $grade_category->path  = '/'.$cat->id.'/';
    2140                      $grade_category->depth = 1;
    2141                      $grade_category->update('system');
    2142                      return $this->get_children($include_category_items);
    2143                  }
    2144  
    2145              } else {
    2146  
    2147                  if (empty($cat->path) or !preg_match('|/'.$cat->parent.'/'.$cat->id.'/$|', $cat->path)) {
    2148                      //fix paths and depts
    2149                      static $recursioncounter = 0; // prevents infinite recursion
    2150                      $recursioncounter++;
    2151  
    2152                      if ($recursioncounter < 5) {
    2153                          // fix paths and depths!
    2154                          $grade_category = new grade_category($cat, false);
    2155                          $grade_category->depth = 0;
    2156                          $grade_category->path  = null;
    2157                          $grade_category->update('system');
    2158                          return $this->get_children($include_category_items);
    2159                      }
    2160                  }
    2161                  // prevent problems with duplicate sortorders in db
    2162                  $sortorder = $cat->sortorder;
    2163  
    2164                  while (array_key_exists($sortorder, $cats[$cat->parent]->children)) {
    2165                      //debugging("$sortorder exists in cat loop");
    2166                      $sortorder++;
    2167                  }
    2168  
    2169                  $cats[$cat->parent]->children[$sortorder] = &$cats[$catid];
    2170              }
    2171  
    2172              if ($catid == $this->id) {
    2173                  $category = &$cats[$catid];
    2174              }
    2175          }
    2176  
    2177          unset($items); // not needed
    2178          unset($cats); // not needed
    2179  
    2180          $children_array = array();
    2181          if (is_object($category)) {
    2182              $children_array = grade_category::_get_children_recursion($category);
    2183              ksort($children_array);
    2184          }
    2185  
    2186          return $children_array;
    2187  
    2188      }
    2189  
    2190      /**
    2191       * Private method used to retrieve all children of this category recursively
    2192       *
    2193       * @param grade_category $category Source of current recursion
    2194       * @return array An array of child grade categories
    2195       */
    2196      private static function _get_children_recursion($category) {
    2197  
    2198          $children_array = array();
    2199          foreach ($category->children as $sortorder=>$child) {
    2200  
    2201              if (property_exists($child, 'itemtype')) {
    2202                  $grade_item = new grade_item($child, false);
    2203  
    2204                  if (in_array($grade_item->itemtype, array('course', 'category'))) {
    2205                      $type  = $grade_item->itemtype.'item';
    2206                      $depth = $category->depth;
    2207  
    2208                  } else {
    2209                      $type  = 'item';
    2210                      $depth = $category->depth; // we use this to set the same colour
    2211                  }
    2212                  $children_array[$sortorder] = array('object'=>$grade_item, 'type'=>$type, 'depth'=>$depth);
    2213  
    2214              } else {
    2215                  $children = grade_category::_get_children_recursion($child);
    2216                  $grade_category = new grade_category($child, false);
    2217  
    2218                  if (empty($children)) {
    2219                      $children = array();
    2220                  }
    2221                  $children_array[$sortorder] = array('object'=>$grade_category, 'type'=>'category', 'depth'=>$grade_category->depth, 'children'=>$children);
    2222              }
    2223          }
    2224  
    2225          // sort the array
    2226          ksort($children_array);
    2227  
    2228          return $children_array;
    2229      }
    2230  
    2231      /**
    2232       * Uses {@link get_grade_item()} to load or create a grade_item, then saves it as $this->grade_item.
    2233       *
    2234       * @return grade_item
    2235       */
    2236      public function load_grade_item() {
    2237          if (empty($this->grade_item)) {
    2238              $this->grade_item = $this->get_grade_item();
    2239          }
    2240          return $this->grade_item;
    2241      }
    2242  
    2243      /**
    2244       * Retrieves this grade categories' associated grade_item from the database
    2245       *
    2246       * If no grade_item exists yet, creates one.
    2247       *
    2248       * @return grade_item
    2249       */
    2250      public function get_grade_item() {
    2251          if (empty($this->id)) {
    2252              debugging("Attempt to obtain a grade_category's associated grade_item without the category's ID being set.");
    2253              return false;
    2254          }
    2255  
    2256          if (empty($this->parent)) {
    2257              $params = array('courseid'=>$this->courseid, 'itemtype'=>'course', 'iteminstance'=>$this->id);
    2258  
    2259          } else {
    2260              $params = array('courseid'=>$this->courseid, 'itemtype'=>'category', 'iteminstance'=>$this->id);
    2261          }
    2262  
    2263          if (!$grade_items = grade_item::fetch_all($params)) {
    2264              // create a new one
    2265              $grade_item = new grade_item($params, false);
    2266              $grade_item->gradetype = GRADE_TYPE_VALUE;
    2267              $grade_item->insert('system');
    2268  
    2269          } else if (count($grade_items) == 1) {
    2270              // found existing one
    2271              $grade_item = reset($grade_items);
    2272  
    2273          } else {
    2274              debugging("Found more than one grade_item attached to category id:".$this->id);
    2275              // return first one
    2276              $grade_item = reset($grade_items);
    2277          }
    2278  
    2279          return $grade_item;
    2280      }
    2281  
    2282      /**
    2283       * Uses $this->parent to instantiate $this->parent_category based on the referenced record in the DB
    2284       *
    2285       * @return grade_category The parent category
    2286       */
    2287      public function load_parent_category() {
    2288          if (empty($this->parent_category) && !empty($this->parent)) {
    2289              $this->parent_category = $this->get_parent_category();
    2290          }
    2291          return $this->parent_category;
    2292      }
    2293  
    2294      /**
    2295       * Uses $this->parent to instantiate and return a grade_category object
    2296       *
    2297       * @return grade_category Returns the parent category or null if this category has no parent
    2298       */
    2299      public function get_parent_category() {
    2300          if (!empty($this->parent)) {
    2301              $parent_category = new grade_category(array('id' => $this->parent));
    2302              return $parent_category;
    2303          } else {
    2304              return null;
    2305          }
    2306      }
    2307  
    2308      /**
    2309       * Returns the most descriptive field for this grade category
    2310       *
    2311       * @return string name
    2312       * @param bool $escape Whether the returned category name is to be HTML escaped or not.
    2313       */
    2314      public function get_name($escape = true) {
    2315          global $DB;
    2316          // For a course category, we return the course name if the fullname is set to '?' in the DB (empty in the category edit form)
    2317          if (empty($this->parent) && $this->fullname == '?') {
    2318              $course = $DB->get_record('course', array('id'=> $this->courseid));
    2319              return format_string($course->fullname, false, ['context' => context_course::instance($this->courseid),
    2320                  'escape' => $escape]);
    2321  
    2322          } else {
    2323              // Grade categories can't be set up at system context (unlike scales and outcomes)
    2324              // We therefore must have a courseid, and don't need to handle system contexts when filtering.
    2325              return format_string($this->fullname, false, ['context' => context_course::instance($this->courseid),
    2326                  'escape' => $escape]);
    2327          }
    2328      }
    2329  
    2330      /**
    2331       * Describe the aggregation settings for this category so the reports make more sense.
    2332       *
    2333       * @return string description
    2334       */
    2335      public function get_description() {
    2336          $allhelp = array();
    2337          if ($this->aggregation != GRADE_AGGREGATE_SUM) {
    2338              $aggrstrings = grade_helper::get_aggregation_strings();
    2339              $allhelp[] = $aggrstrings[$this->aggregation];
    2340          }
    2341  
    2342          if ($this->droplow && $this->can_apply_limit_rules()) {
    2343              $allhelp[] = get_string('droplowestvalues', 'grades', $this->droplow);
    2344          }
    2345          if ($this->keephigh && $this->can_apply_limit_rules()) {
    2346              $allhelp[] = get_string('keephighestvalues', 'grades', $this->keephigh);
    2347          }
    2348          if (!$this->aggregateonlygraded) {
    2349              $allhelp[] = get_string('aggregatenotonlygraded', 'grades');
    2350          }
    2351          if ($allhelp) {
    2352              return implode('. ', $allhelp) . '.';
    2353          }
    2354          return '';
    2355      }
    2356  
    2357      /**
    2358       * Sets this category's parent id
    2359       *
    2360       * @param int $parentid The ID of the category that is the new parent to $this
    2361       * @param string $source From where was the object updated (mod/forum, manual, etc.)
    2362       * @return bool success
    2363       */
    2364      public function set_parent($parentid, $source=null) {
    2365          if ($this->parent == $parentid) {
    2366              return true;
    2367          }
    2368  
    2369          if ($parentid == $this->id) {
    2370              print_error('cannotassignselfasparent');
    2371          }
    2372  
    2373          if (empty($this->parent) and $this->is_course_category()) {
    2374              print_error('cannothaveparentcate');
    2375          }
    2376  
    2377          // find parent and check course id
    2378          if (!$parent_category = grade_category::fetch(array('id'=>$parentid, 'courseid'=>$this->courseid))) {
    2379              return false;
    2380          }
    2381  
    2382          $this->force_regrading();
    2383  
    2384          // set new parent category
    2385          $this->parent          = $parent_category->id;
    2386          $this->parent_category =& $parent_category;
    2387          $this->path            = null;       // remove old path and depth - will be recalculated in update()
    2388          $this->depth           = 0;          // remove old path and depth - will be recalculated in update()
    2389          $this->update($source);
    2390  
    2391          return $this->update($source);
    2392      }
    2393  
    2394      /**
    2395       * Returns the final grade values for this grade category.
    2396       *
    2397       * @param int $userid Optional user ID to retrieve a single user's final grade
    2398       * @return mixed An array of all final_grades (stdClass objects) for this grade_item, or a single final_grade.
    2399       */
    2400      public function get_final($userid=null) {
    2401          $this->load_grade_item();
    2402          return $this->grade_item->get_final($userid);
    2403      }
    2404  
    2405      /**
    2406       * Returns the sortorder of the grade categories' associated grade_item
    2407       *
    2408       * This method is also available in grade_item for cases where the object type is not known.
    2409       *
    2410       * @return int Sort order
    2411       */
    2412      public function get_sortorder() {
    2413          $this->load_grade_item();
    2414          return $this->grade_item->get_sortorder();
    2415      }
    2416  
    2417      /**
    2418       * Returns the idnumber of the grade categories' associated grade_item.
    2419       *
    2420       * This method is also available in grade_item for cases where the object type is not known.
    2421       *
    2422       * @return string idnumber
    2423       */
    2424      public function get_idnumber() {
    2425          $this->load_grade_item();
    2426          return $this->grade_item->get_idnumber();
    2427      }
    2428  
    2429      /**
    2430       * Sets the sortorder variable for this category.
    2431       *
    2432       * This method is also available in grade_item, for cases where the object type is not know.
    2433       *
    2434       * @param int $sortorder The sortorder to assign to this category
    2435       */
    2436      public function set_sortorder($sortorder) {
    2437          $this->load_grade_item();
    2438          $this->grade_item->set_sortorder($sortorder);
    2439      }
    2440  
    2441      /**
    2442       * Move this category after the given sortorder
    2443       *
    2444       * Does not change the parent
    2445       *
    2446       * @param int $sortorder to place after.
    2447       * @return void
    2448       */
    2449      public function move_after_sortorder($sortorder) {
    2450          $this->load_grade_item();
    2451          $this->grade_item->move_after_sortorder($sortorder);
    2452      }
    2453  
    2454      /**
    2455       * Return true if this is the top most category that represents the total course grade.
    2456       *
    2457       * @return bool
    2458       */
    2459      public function is_course_category() {
    2460          $this->load_grade_item();
    2461          return $this->grade_item->is_course_item();
    2462      }
    2463  
    2464      /**
    2465       * Return the course level grade_category object
    2466       *
    2467       * @param int $courseid The Course ID
    2468       * @return grade_category Returns the course level grade_category instance
    2469       */
    2470      public static function fetch_course_category($courseid) {
    2471          if (empty($courseid)) {
    2472              debugging('Missing course id!');
    2473              return false;
    2474          }
    2475  
    2476          // course category has no parent
    2477          if ($course_category = grade_category::fetch(array('courseid'=>$courseid, 'parent'=>null))) {
    2478              return $course_category;
    2479          }
    2480  
    2481          // create a new one
    2482          $course_category = new grade_category();
    2483          $course_category->insert_course_category($courseid);
    2484  
    2485          return $course_category;
    2486      }
    2487  
    2488      /**
    2489       * Is grading object editable?
    2490       *
    2491       * @return bool
    2492       */
    2493      public function is_editable() {
    2494          return true;
    2495      }
    2496  
    2497      /**
    2498       * Returns the locked state/date of the grade categories' associated grade_item.
    2499       *
    2500       * This method is also available in grade_item, for cases where the object type is not known.
    2501       *
    2502       * @return bool
    2503       */
    2504      public function is_locked() {
    2505          $this->load_grade_item();
    2506          return $this->grade_item->is_locked();
    2507      }
    2508  
    2509      /**
    2510       * Sets the grade_item's locked variable and updates the grade_item.
    2511       *
    2512       * Calls set_locked() on the categories' grade_item
    2513       *
    2514       * @param int  $lockedstate 0, 1 or a timestamp int(10) after which date the item will be locked.
    2515       * @param bool $cascade lock/unlock child objects too
    2516       * @param bool $refresh refresh grades when unlocking
    2517       * @return bool success if category locked (not all children mayb be locked though)
    2518       */
    2519      public function set_locked($lockedstate, $cascade=false, $refresh=true) {
    2520          $this->load_grade_item();
    2521  
    2522          $result = $this->grade_item->set_locked($lockedstate, $cascade, true);
    2523  
    2524          if ($cascade) {
    2525              //process all children - items and categories
    2526              if ($children = grade_item::fetch_all(array('categoryid'=>$this->id))) {
    2527  
    2528                  foreach ($children as $child) {
    2529                      $child->set_locked($lockedstate, true, false);
    2530  
    2531                      if (empty($lockedstate) and $refresh) {
    2532                          //refresh when unlocking
    2533                          $child->refresh_grades();
    2534                      }
    2535                  }
    2536              }
    2537  
    2538              if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
    2539  
    2540                  foreach ($children as $child) {
    2541                      $child->set_locked($lockedstate, true, true);
    2542                  }
    2543              }
    2544          }
    2545  
    2546          return $result;
    2547      }
    2548  
    2549      /**
    2550       * Overrides grade_object::set_properties() to add special handling for changes to category aggregation types
    2551       *
    2552       * @param stdClass $instance the object to set the properties on
    2553       * @param array|stdClass $params Either an associative array or an object containing property name, property value pairs
    2554       */
    2555      public static function set_properties(&$instance, $params) {
    2556          global $DB;
    2557  
    2558          $fromaggregation = $instance->aggregation;
    2559  
    2560          parent::set_properties($instance, $params);
    2561  
    2562          // The aggregation method is changing and this category has already been saved.
    2563          if (isset($params->aggregation) && !empty($instance->id)) {
    2564              $achildwasdupdated = false;
    2565  
    2566              // Get all its children.
    2567              $children = $instance->get_children();
    2568              foreach ($children as $child) {
    2569                  $item = $child['object'];
    2570                  if ($child['type'] == 'category') {
    2571                      $item = $item->load_grade_item();
    2572                  }
    2573  
    2574                  // Set the new aggregation fields.
    2575                  if ($item->set_aggregation_fields_for_aggregation($fromaggregation, $params->aggregation)) {
    2576                      $item->update();
    2577                      $achildwasdupdated = true;
    2578                  }
    2579              }
    2580  
    2581              // If this is the course category, it is possible that its grade item was set as needsupdate
    2582              // by one of its children. If we keep a reference to that stale object we might cause the
    2583              // needsupdate flag to be lost. It's safer to just reload the grade_item from the database.
    2584              if ($achildwasdupdated && !empty($instance->grade_item) && $instance->is_course_category()) {
    2585                  $instance->grade_item = null;
    2586                  $instance->load_grade_item();
    2587              }
    2588          }
    2589      }
    2590  
    2591      /**
    2592       * Sets the grade_item's hidden variable and updates the grade_item.
    2593       *
    2594       * Overrides grade_item::set_hidden() to add cascading of the hidden value to grade items in this grade category
    2595       *
    2596       * @param int $hidden 0 mean always visible, 1 means always hidden and a number > 1 is a timestamp to hide until
    2597       * @param bool $cascade apply to child objects too
    2598       */
    2599      public function set_hidden($hidden, $cascade=false) {
    2600          $this->load_grade_item();
    2601          //this hides the category itself and everything it contains
    2602          parent::set_hidden($hidden, $cascade);
    2603  
    2604          if ($cascade) {
    2605  
    2606              // This hides the associated grade item (the course/category total).
    2607              $this->grade_item->set_hidden($hidden, $cascade);
    2608  
    2609              if ($children = grade_item::fetch_all(array('categoryid'=>$this->id))) {
    2610  
    2611                  foreach ($children as $child) {
    2612                      if ($child->can_control_visibility()) {
    2613                          $child->set_hidden($hidden, $cascade);
    2614                      }
    2615                  }
    2616              }
    2617  
    2618              if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
    2619  
    2620                  foreach ($children as $child) {
    2621                      $child->set_hidden($hidden, $cascade);
    2622                  }
    2623              }
    2624          }
    2625  
    2626          //if marking category visible make sure parent category is visible MDL-21367
    2627          if( !$hidden ) {
    2628              $category_array = grade_category::fetch_all(array('id'=>$this->parent));
    2629              if ($category_array && array_key_exists($this->parent, $category_array)) {
    2630                  $category = $category_array[$this->parent];
    2631                  //call set_hidden on the category regardless of whether it is hidden as its parent might be hidden
    2632                  $category->set_hidden($hidden, false);
    2633              }
    2634          }
    2635      }
    2636  
    2637      /**
    2638       * Applies default settings on this category
    2639       *
    2640       * @return bool True if anything changed
    2641       */
    2642      public function apply_default_settings() {
    2643          global $CFG;
    2644  
    2645          foreach ($this->forceable as $property) {
    2646  
    2647              if (isset($CFG->{"grade_$property"})) {
    2648  
    2649                  if ($CFG->{"grade_$property"} == -1) {
    2650                      continue; //temporary bc before version bump
    2651                  }
    2652                  $this->$property = $CFG->{"grade_$property"};
    2653              }
    2654          }
    2655      }
    2656  
    2657      /**
    2658       * Applies forced settings on this category
    2659       *
    2660       * @return bool True if anything changed
    2661       */
    2662      public function apply_forced_settings() {
    2663          global $CFG;
    2664  
    2665          $updated = false;
    2666  
    2667          foreach ($this->forceable as $property) {
    2668  
    2669              if (isset($CFG->{"grade_$property"}) and isset($CFG->{"grade_{$property}_flag"}) and
    2670                                                      ((int) $CFG->{"grade_{$property}_flag"} & 1)) {
    2671  
    2672                  if ($CFG->{"grade_$property"} == -1) {
    2673                      continue; //temporary bc before version bump
    2674                  }
    2675                  $this->$property = $CFG->{"grade_$property"};
    2676                  $updated = true;
    2677              }
    2678          }
    2679  
    2680          return $updated;
    2681      }
    2682  
    2683      /**
    2684       * Notification of change in forced category settings.
    2685       *
    2686       * Causes all course and category grade items to be marked as needing to be updated
    2687       */
    2688      public static function updated_forced_settings() {
    2689          global $CFG, $DB;
    2690          $params = array(1, 'course', 'category');
    2691          $sql = "UPDATE {grade_items} SET needsupdate=? WHERE itemtype=? or itemtype=?";
    2692          $DB->execute($sql, $params);
    2693      }
    2694  
    2695      /**
    2696       * Determine the default aggregation values for a given aggregation method.
    2697       *
    2698       * @param int $aggregationmethod The aggregation method constant value.
    2699       * @return array Containing the keys 'aggregationcoef', 'aggregationcoef2' and 'weightoverride'.
    2700       */
    2701      public static function get_default_aggregation_coefficient_values($aggregationmethod) {
    2702          $defaultcoefficients = array(
    2703              'aggregationcoef' => 0,
    2704              'aggregationcoef2' => 0,
    2705              'weightoverride' => 0
    2706          );
    2707  
    2708          switch ($aggregationmethod) {
    2709              case GRADE_AGGREGATE_WEIGHTED_MEAN:
    2710                  $defaultcoefficients['aggregationcoef'] = 1;
    2711                  break;
    2712              case GRADE_AGGREGATE_SUM:
    2713                  $defaultcoefficients['aggregationcoef2'] = 1;
    2714                  break;
    2715          }
    2716  
    2717          return $defaultcoefficients;
    2718      }
    2719  
    2720      /**
    2721       * Cleans the cache.
    2722       *
    2723       * We invalidate them all so it can be completely reloaded.
    2724       *
    2725       * Being conservative here, if there is a new grade_category we purge them, the important part
    2726       * is that this is not purged when there are no changes in grade_categories.
    2727       *
    2728       * @param bool $deleted
    2729       * @return void
    2730       */
    2731      protected function notify_changed($deleted) {
    2732          self::clean_record_set();
    2733      }
    2734  
    2735      /**
    2736       * Generates a unique key per query.
    2737       *
    2738       * Not unique between grade_object children. self::retrieve_record_set and self::set_record_set will be in charge of
    2739       * selecting the appropriate cache.
    2740       *
    2741       * @param array $params An array of conditions like $fieldname => $fieldvalue
    2742       * @return string
    2743       */
    2744      protected static function generate_record_set_key($params) {
    2745          return sha1(json_encode($params));
    2746      }
    2747  
    2748      /**
    2749       * Tries to retrieve a record set from the cache.
    2750       *
    2751       * @param array $params The query params
    2752       * @return grade_object[]|bool An array of grade_objects or false if not found.
    2753       */
    2754      protected static function retrieve_record_set($params) {
    2755          $cache = cache::make('core', 'grade_categories');
    2756          return $cache->get(self::generate_record_set_key($params));
    2757      }
    2758  
    2759      /**
    2760       * Sets a result to the records cache, even if there were no results.
    2761       *
    2762       * @param string $params The query params
    2763       * @param grade_object[]|bool $records An array of grade_objects or false if there are no records matching the $key filters
    2764       * @return void
    2765       */
    2766      protected static function set_record_set($params, $records) {
    2767          $cache = cache::make('core', 'grade_categories');
    2768          return $cache->set(self::generate_record_set_key($params), $records);
    2769      }
    2770  
    2771      /**
    2772       * Cleans the cache.
    2773       *
    2774       * Aggressive deletion to be conservative given the gradebook design.
    2775       * The key is based on the requested params, not easy nor worth to purge selectively.
    2776       *
    2777       * @return void
    2778       */
    2779      public static function clean_record_set() {
    2780          cache_helper::purge_by_event('changesingradecategories');
    2781      }
    2782  }