Search moodle.org's
Developer Documentation

See Release Notes

  • 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 310 and 311] [Versions 311 and 400] [Versions 311 and 401] [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 an individual user's grade
  19   *
  20   * @package   core_grades
  21   * @category  grade
  22   * @copyright 2006 Nicolas Connault
  23   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  require_once ('grade_object.php');
  29  
  30  /**
  31   * grade_grades is an object mapped to DB table {prefix}grade_grades
  32   *
  33   * @package   core_grades
  34   * @category  grade
  35   * @copyright 2006 Nicolas Connault
  36   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37   */
  38  class grade_grade extends grade_object {
  39  
  40      /**
  41       * The DB table.
  42       * @var string $table
  43       */
  44      public $table = 'grade_grades';
  45  
  46      /**
  47       * Array of required table fields, must start with 'id'.
  48       * @var array $required_fields
  49       */
  50      public $required_fields = array('id', 'itemid', 'userid', 'rawgrade', 'rawgrademax', 'rawgrademin',
  51                                   'rawscaleid', 'usermodified', 'finalgrade', 'hidden', 'locked',
  52                                   'locktime', 'exported', 'overridden', 'excluded', 'timecreated',
  53                                   'timemodified', 'aggregationstatus', 'aggregationweight');
  54  
  55      /**
  56       * Array of optional fields with default values (these should match db defaults)
  57       * @var array $optional_fields
  58       */
  59      public $optional_fields = array('feedback'=>null, 'feedbackformat'=>0, 'information'=>null, 'informationformat'=>0);
  60  
  61      /**
  62       * The id of the grade_item this grade belongs to.
  63       * @var int $itemid
  64       */
  65      public $itemid;
  66  
  67      /**
  68       * The grade_item object referenced by $this->itemid.
  69       * @var grade_item $grade_item
  70       */
  71      public $grade_item;
  72  
  73      /**
  74       * The id of the user this grade belongs to.
  75       * @var int $userid
  76       */
  77      public $userid;
  78  
  79      /**
  80       * The grade value of this raw grade, if such was provided by the module.
  81       * @var float $rawgrade
  82       */
  83      public $rawgrade;
  84  
  85      /**
  86       * The maximum allowable grade when this grade was created.
  87       * @var float $rawgrademax
  88       */
  89      public $rawgrademax = 100;
  90  
  91      /**
  92       * The minimum allowable grade when this grade was created.
  93       * @var float $rawgrademin
  94       */
  95      public $rawgrademin = 0;
  96  
  97      /**
  98       * id of the scale, if this grade is based on a scale.
  99       * @var int $rawscaleid
 100       */
 101      public $rawscaleid;
 102  
 103      /**
 104       * The userid of the person who last modified this grade.
 105       * @var int $usermodified
 106       */
 107      public $usermodified;
 108  
 109      /**
 110       * The final value of this grade.
 111       * @var float $finalgrade
 112       */
 113      public $finalgrade;
 114  
 115      /**
 116       * 0 if visible, 1 always hidden or date not visible until
 117       * @var float $hidden
 118       */
 119      public $hidden = 0;
 120  
 121      /**
 122       * 0 not locked, date when the item was locked
 123       * @var float locked
 124       */
 125      public $locked = 0;
 126  
 127      /**
 128       * 0 no automatic locking, date when to lock the grade automatically
 129       * @var float $locktime
 130       */
 131      public $locktime = 0;
 132  
 133      /**
 134       * Exported flag
 135       * @var bool $exported
 136       */
 137      public $exported = 0;
 138  
 139      /**
 140       * Overridden flag
 141       * @var bool $overridden
 142       */
 143      public $overridden = 0;
 144  
 145      /**
 146       * Grade excluded from aggregation functions
 147       * @var bool $excluded
 148       */
 149      public $excluded = 0;
 150  
 151      /**
 152       * TODO: HACK: create a new field datesubmitted - the date of submission if any (MDL-31377)
 153       * @var bool $timecreated
 154       */
 155      public $timecreated = null;
 156  
 157      /**
 158       * TODO: HACK: create a new field dategraded - the date of grading (MDL-31378)
 159       * @var bool $timemodified
 160       */
 161      public $timemodified = null;
 162  
 163      /**
 164       * Aggregation status flag. Can be one of 'unknown', 'dropped', 'novalue' or 'used'.
 165       * @var string $aggregationstatus
 166       */
 167      public $aggregationstatus = 'unknown';
 168  
 169      /**
 170       * Aggregation weight is the specific weight used in the aggregation calculation for this grade.
 171       * @var float $aggregationweight
 172       */
 173      public $aggregationweight = null;
 174  
 175      /**
 176       * Feedback files to copy.
 177       *
 178       * Example -
 179       *
 180       * [
 181       *     'contextid' => 1,
 182       *     'component' => 'mod_xyz',
 183       *     'filearea' => 'mod_xyz_feedback',
 184       *     'itemid' => 2
 185       * ];
 186       *
 187       * @var array
 188       */
 189      public $feedbackfiles = [];
 190  
 191      /**
 192       * Returns array of grades for given grade_item+users
 193       *
 194       * @param grade_item $grade_item
 195       * @param array $userids
 196       * @param bool $include_missing include grades that do not exist yet
 197       * @return array userid=>grade_grade array
 198       */
 199      public static function fetch_users_grades($grade_item, $userids, $include_missing=true) {
 200          global $DB;
 201  
 202          // hmm, there might be a problem with length of sql query
 203          // if there are too many users requested - we might run out of memory anyway
 204          $limit = 2000;
 205          $count = count($userids);
 206          if ($count > $limit) {
 207              $half = (int)($count/2);
 208              $first  = array_slice($userids, 0, $half);
 209              $second = array_slice($userids, $half);
 210              return grade_grade::fetch_users_grades($grade_item, $first, $include_missing) + grade_grade::fetch_users_grades($grade_item, $second, $include_missing);
 211          }
 212  
 213          list($user_ids_cvs, $params) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'uid0');
 214          $params['giid'] = $grade_item->id;
 215          $result = array();
 216          if ($grade_records = $DB->get_records_select('grade_grades', "itemid=:giid AND userid $user_ids_cvs", $params)) {
 217              foreach ($grade_records as $record) {
 218                  $result[$record->userid] = new grade_grade($record, false);
 219              }
 220          }
 221          if ($include_missing) {
 222              foreach ($userids as $userid) {
 223                  if (!array_key_exists($userid, $result)) {
 224                      $grade_grade = new grade_grade();
 225                      $grade_grade->userid = $userid;
 226                      $grade_grade->itemid = $grade_item->id;
 227                      $result[$userid] = $grade_grade;
 228                  }
 229              }
 230          }
 231  
 232          return $result;
 233      }
 234  
 235      /**
 236       * Loads the grade_item object referenced by $this->itemid and saves it as $this->grade_item for easy access
 237       *
 238       * @return grade_item The grade_item instance referenced by $this->itemid
 239       */
 240      public function load_grade_item() {
 241          if (empty($this->itemid)) {
 242              debugging('Missing itemid');
 243              $this->grade_item = null;
 244              return null;
 245          }
 246  
 247          if (empty($this->grade_item)) {
 248              $this->grade_item = grade_item::fetch(array('id'=>$this->itemid));
 249  
 250          } else if ($this->grade_item->id != $this->itemid) {
 251              debugging('Itemid mismatch');
 252              $this->grade_item = grade_item::fetch(array('id'=>$this->itemid));
 253          }
 254  
 255          if (empty($this->grade_item)) {
 256              debugging("Missing grade item id $this->itemid", DEBUG_DEVELOPER);
 257          }
 258  
 259          return $this->grade_item;
 260      }
 261  
 262      /**
 263       * Is grading object editable?
 264       *
 265       * @return bool
 266       */
 267      public function is_editable() {
 268          if ($this->is_locked()) {
 269              return false;
 270          }
 271  
 272          $grade_item = $this->load_grade_item();
 273  
 274          if ($grade_item->gradetype == GRADE_TYPE_NONE) {
 275              return false;
 276          }
 277  
 278          if ($grade_item->is_course_item() or $grade_item->is_category_item()) {
 279              return (bool)get_config('moodle', 'grade_overridecat');
 280          }
 281  
 282          return true;
 283      }
 284  
 285      /**
 286       * Check grade lock status. Uses both grade item lock and grade lock.
 287       * Internally any date in locked field (including future ones) means locked,
 288       * the date is stored for logging purposes only.
 289       *
 290       * @return bool True if locked, false if not
 291       */
 292      public function is_locked() {
 293          $this->load_grade_item();
 294          if (empty($this->grade_item)) {
 295              return !empty($this->locked);
 296          } else {
 297              return !empty($this->locked) or $this->grade_item->is_locked();
 298          }
 299      }
 300  
 301      /**
 302       * Checks if grade overridden
 303       *
 304       * @return bool True if grade is overriden
 305       */
 306      public function is_overridden() {
 307          return !empty($this->overridden);
 308      }
 309  
 310      /**
 311       * Returns timestamp of submission related to this grade, null if not submitted.
 312       *
 313       * @return int Timestamp
 314       */
 315      public function get_datesubmitted() {
 316          //TODO: HACK - create new fields (MDL-31379)
 317          return $this->timecreated;
 318      }
 319  
 320      /**
 321       * Returns the weight this grade contributed to the aggregated grade
 322       *
 323       * @return float|null
 324       */
 325      public function get_aggregationweight() {
 326          return $this->aggregationweight;
 327      }
 328  
 329      /**
 330       * Set aggregationweight.
 331       *
 332       * @param float $aggregationweight
 333       * @return void
 334       */
 335      public function set_aggregationweight($aggregationweight) {
 336          $this->aggregationweight = $aggregationweight;
 337          $this->update();
 338      }
 339  
 340      /**
 341       * Returns the info on how this value was used in the aggregated grade
 342       *
 343       * @return string One of 'dropped', 'excluded', 'novalue', 'used' or 'extra'
 344       */
 345      public function get_aggregationstatus() {
 346          return $this->aggregationstatus;
 347      }
 348  
 349      /**
 350       * Set aggregationstatus flag
 351       *
 352       * @param string $aggregationstatus
 353       * @return void
 354       */
 355      public function set_aggregationstatus($aggregationstatus) {
 356          $this->aggregationstatus = $aggregationstatus;
 357          $this->update();
 358      }
 359  
 360      /**
 361       * Returns the minimum and maximum number of points this grade is graded with respect to.
 362       *
 363       * @since  Moodle 2.8.7, 2.9.1
 364       * @return array A list containing, in order, the minimum and maximum number of points.
 365       */
 366      protected function get_grade_min_and_max() {
 367          global $CFG;
 368          $this->load_grade_item();
 369  
 370          // When the following setting is turned on we use the grade_grade raw min and max values.
 371          $minmaxtouse = grade_get_setting($this->grade_item->courseid, 'minmaxtouse', $CFG->grade_minmaxtouse);
 372  
 373          // Check to see if the gradebook is frozen. This allows grades to not be altered at all until a user verifies that they
 374          // wish to update the grades.
 375          $gradebookcalculationsfreeze = 'gradebook_calculations_freeze_' . $this->grade_item->courseid;
 376          // Gradebook is frozen, run through old code.
 377          if (isset($CFG->$gradebookcalculationsfreeze) && (int)$CFG->$gradebookcalculationsfreeze <= 20150627) {
 378              // Only aggregate items use separate min grades.
 379              if ($minmaxtouse == GRADE_MIN_MAX_FROM_GRADE_GRADE || $this->grade_item->is_aggregate_item()) {
 380                  return array($this->rawgrademin, $this->rawgrademax);
 381              } else {
 382                  return array($this->grade_item->grademin, $this->grade_item->grademax);
 383              }
 384          } else {
 385              // Only aggregate items use separate min grades, unless they are calculated grade items.
 386              if (($this->grade_item->is_aggregate_item() && !$this->grade_item->is_calculated())
 387                      || $minmaxtouse == GRADE_MIN_MAX_FROM_GRADE_GRADE) {
 388                  return array($this->rawgrademin, $this->rawgrademax);
 389              } else {
 390                  return array($this->grade_item->grademin, $this->grade_item->grademax);
 391              }
 392          }
 393      }
 394  
 395      /**
 396       * Returns the minimum number of points this grade is graded with.
 397       *
 398       * @since  Moodle 2.8.7, 2.9.1
 399       * @return float The minimum number of points
 400       */
 401      public function get_grade_min() {
 402          list($min, $max) = $this->get_grade_min_and_max();
 403  
 404          return $min;
 405      }
 406  
 407      /**
 408       * Returns the maximum number of points this grade is graded with respect to.
 409       *
 410       * @since  Moodle 2.8.7, 2.9.1
 411       * @return float The maximum number of points
 412       */
 413      public function get_grade_max() {
 414          list($min, $max) = $this->get_grade_min_and_max();
 415  
 416          return $max;
 417      }
 418  
 419      /**
 420       * Returns timestamp when last graded, null if no grade present
 421       *
 422       * @return int
 423       */
 424      public function get_dategraded() {
 425          //TODO: HACK - create new fields (MDL-31379)
 426          if (is_null($this->finalgrade) and is_null($this->feedback)) {
 427              return null; // no grade == no date
 428          } else if ($this->overridden) {
 429              return $this->overridden;
 430          } else {
 431              return $this->timemodified;
 432          }
 433      }
 434  
 435      /**
 436       * Set the overridden status of grade
 437       *
 438       * @param bool $state requested overridden state
 439       * @param bool $refresh refresh grades from external activities if needed
 440       * @return bool true is db state changed
 441       */
 442      public function set_overridden($state, $refresh = true) {
 443          if (empty($this->overridden) and $state) {
 444              $this->overridden = time();
 445              $this->update();
 446              return true;
 447  
 448          } else if (!empty($this->overridden) and !$state) {
 449              $this->overridden = 0;
 450              $this->update();
 451  
 452              if ($refresh) {
 453                  //refresh when unlocking
 454                  $this->grade_item->refresh_grades($this->userid);
 455              }
 456  
 457              return true;
 458          }
 459          return false;
 460      }
 461  
 462      /**
 463       * Checks if grade excluded from aggregation functions
 464       *
 465       * @return bool True if grade is excluded from aggregation
 466       */
 467      public function is_excluded() {
 468          return !empty($this->excluded);
 469      }
 470  
 471      /**
 472       * Set the excluded status of grade
 473       *
 474       * @param bool $state requested excluded state
 475       * @return bool True is database state changed
 476       */
 477      public function set_excluded($state) {
 478          if (empty($this->excluded) and $state) {
 479              $this->excluded = time();
 480              $this->update();
 481              return true;
 482  
 483          } else if (!empty($this->excluded) and !$state) {
 484              $this->excluded = 0;
 485              $this->update();
 486              return true;
 487          }
 488          return false;
 489      }
 490  
 491      /**
 492       * Lock/unlock this grade.
 493       *
 494       * @param int $lockedstate 0, 1 or a timestamp int(10) after which date the item will be locked.
 495       * @param bool $cascade Ignored param
 496       * @param bool $refresh Refresh grades when unlocking
 497       * @return bool True if successful, false if can not set new lock state for grade
 498       */
 499      public function set_locked($lockedstate, $cascade=false, $refresh=true) {
 500          $this->load_grade_item();
 501  
 502          if ($lockedstate) {
 503              if ($this->grade_item->needsupdate) {
 504                  //can not lock grade if final not calculated!
 505                  return false;
 506              }
 507  
 508              $this->locked = time();
 509              $this->update();
 510  
 511              return true;
 512  
 513          } else {
 514              if (!empty($this->locked) and $this->locktime < time()) {
 515                  //we have to reset locktime or else it would lock up again
 516                  $this->locktime = 0;
 517              }
 518  
 519              // remove the locked flag
 520              $this->locked = 0;
 521              $this->update();
 522  
 523              if ($refresh and !$this->is_overridden()) {
 524                  //refresh when unlocking and not overridden
 525                  $this->grade_item->refresh_grades($this->userid);
 526              }
 527  
 528              return true;
 529          }
 530      }
 531  
 532      /**
 533       * Lock the grade if needed. Make sure this is called only when final grades are valid
 534       *
 535       * @param array $items array of all grade item ids
 536       * @return void
 537       */
 538      public static function check_locktime_all($items) {
 539          global $CFG, $DB;
 540  
 541          $now = time(); // no rounding needed, this is not supposed to be called every 10 seconds
 542          list($usql, $params) = $DB->get_in_or_equal($items);
 543          $params[] = $now;
 544          $rs = $DB->get_recordset_select('grade_grades', "itemid $usql AND locked = 0 AND locktime > 0 AND locktime < ?", $params);
 545          foreach ($rs as $grade) {
 546              $grade_grade = new grade_grade($grade, false);
 547              $grade_grade->locked = time();
 548              $grade_grade->update('locktime');
 549          }
 550          $rs->close();
 551      }
 552  
 553      /**
 554       * Set the locktime for this grade.
 555       *
 556       * @param int $locktime timestamp for lock to activate
 557       * @return void
 558       */
 559      public function set_locktime($locktime) {
 560          $this->locktime = $locktime;
 561          $this->update();
 562      }
 563  
 564      /**
 565       * Get the locktime for this grade.
 566       *
 567       * @return int $locktime timestamp for lock to activate
 568       */
 569      public function get_locktime() {
 570          $this->load_grade_item();
 571  
 572          $item_locktime = $this->grade_item->get_locktime();
 573  
 574          if (empty($this->locktime) or ($item_locktime and $item_locktime < $this->locktime)) {
 575              return $item_locktime;
 576  
 577          } else {
 578              return $this->locktime;
 579          }
 580      }
 581  
 582      /**
 583       * Check grade hidden status. Uses data from both grade item and grade.
 584       *
 585       * @return bool true if hidden, false if not
 586       */
 587      public function is_hidden() {
 588          $this->load_grade_item();
 589          if (empty($this->grade_item)) {
 590              return $this->hidden == 1 or ($this->hidden != 0 and $this->hidden > time());
 591          } else {
 592              return $this->hidden == 1 or ($this->hidden != 0 and $this->hidden > time()) or $this->grade_item->is_hidden();
 593          }
 594      }
 595  
 596      /**
 597       * Check grade hidden status. Uses data from both grade item and grade.
 598       *
 599       * @return bool true if hiddenuntil, false if not
 600       */
 601      public function is_hiddenuntil() {
 602          $this->load_grade_item();
 603  
 604          if ($this->hidden == 1 or $this->grade_item->hidden == 1) {
 605              return false; //always hidden
 606          }
 607  
 608          if ($this->hidden > 1 or $this->grade_item->hidden > 1) {
 609              return true;
 610          }
 611  
 612          return false;
 613      }
 614  
 615      /**
 616       * Check grade hidden status. Uses data from both grade item and grade.
 617       *
 618       * @return int 0 means visible, 1 hidden always, timestamp hidden until
 619       */
 620      public function get_hidden() {
 621          $this->load_grade_item();
 622  
 623          $item_hidden = $this->grade_item->get_hidden();
 624  
 625          if ($item_hidden == 1) {
 626              return 1;
 627  
 628          } else if ($item_hidden == 0) {
 629              return $this->hidden;
 630  
 631          } else {
 632              if ($this->hidden == 0) {
 633                  return $item_hidden;
 634              } else if ($this->hidden == 1) {
 635                  return 1;
 636              } else if ($this->hidden > $item_hidden) {
 637                  return $this->hidden;
 638              } else {
 639                  return $item_hidden;
 640              }
 641          }
 642      }
 643  
 644      /**
 645       * Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.
 646       *
 647       * @param int $hidden new hidden status
 648       * @param bool $cascade ignored
 649       */
 650      public function set_hidden($hidden, $cascade=false) {
 651         $this->hidden = $hidden;
 652         $this->update();
 653      }
 654  
 655      /**
 656       * Finds and returns a grade_grade instance based on params.
 657       *
 658       * @param array $params associative arrays varname=>value
 659       * @return grade_grade Returns a grade_grade instance or false if none found
 660       */
 661      public static function fetch($params) {
 662          return grade_object::fetch_helper('grade_grades', 'grade_grade', $params);
 663      }
 664  
 665      /**
 666       * Finds and returns all grade_grade instances based on params.
 667       *
 668       * @param array $params associative arrays varname=>value
 669       * @return array array of grade_grade instances or false if none found.
 670       */
 671      public static function fetch_all($params) {
 672          return grade_object::fetch_all_helper('grade_grades', 'grade_grade', $params);
 673      }
 674  
 675      /**
 676       * Given a float value situated between a source minimum and a source maximum, converts it to the
 677       * corresponding value situated between a target minimum and a target maximum. Thanks to Darlene
 678       * for the formula :-)
 679       *
 680       * @param float $rawgrade
 681       * @param float $source_min
 682       * @param float $source_max
 683       * @param float $target_min
 684       * @param float $target_max
 685       * @return float Converted value
 686       */
 687      public static function standardise_score($rawgrade, $source_min, $source_max, $target_min, $target_max) {
 688          if (is_null($rawgrade)) {
 689            return null;
 690          }
 691  
 692          if ($source_max == $source_min or $target_min == $target_max) {
 693              // prevent division by 0
 694              return $target_max;
 695          }
 696  
 697          $factor = ($rawgrade - $source_min) / ($source_max - $source_min);
 698          $diff = $target_max - $target_min;
 699          $standardised_value = $factor * $diff + $target_min;
 700          return $standardised_value;
 701      }
 702  
 703      /**
 704       * Given an array like this:
 705       * $a = array(1=>array(2, 3),
 706       *            2=>array(4),
 707       *            3=>array(1),
 708       *            4=>array())
 709       * this function fully resolves the dependencies so each value will be an array of
 710       * the all items this item depends on and their dependencies (and their dependencies...).
 711       * It should not explode if there are circular dependencies.
 712       * The dependency depth array will list the number of branches in the tree above each leaf.
 713       *
 714       * @param array $dependson Array to flatten
 715       * @param array $dependencydepth Array of itemids => depth. Initially these should be all set to 1.
 716       * @return array Flattened array
 717       */
 718      protected static function flatten_dependencies_array(&$dependson, &$dependencydepth) {
 719          // Flatten the nested dependencies - this will handle recursion bombs because it removes duplicates.
 720          $somethingchanged = true;
 721          // First of all, delete any incorrect (not array or individual null) dependency, they aren't welcome.
 722          // TODO: Maybe we should report about this happening, it shouldn't if all dependencies are correct and consistent.
 723          foreach ($dependson as $itemid => $depends) {
 724              $depends = is_array($depends) ? $depends : []; // Only arrays are accepted.
 725              $dependson[$itemid] = array_filter($depends, function($val) { // Only not-null values are accepted.
 726                  return !is_null($val);
 727              });
 728          }
 729          while ($somethingchanged) {
 730              $somethingchanged = false;
 731  
 732              foreach ($dependson as $itemid => $depends) {
 733                  // Make a copy so we can tell if it changed.
 734                  $before = $dependson[$itemid];
 735                  foreach ($depends as $subitemid => $subdepends) {
 736                      $dependson[$itemid] = array_unique(array_merge($depends, $dependson[$subdepends] ?? []));
 737                      sort($dependson[$itemid], SORT_NUMERIC);
 738                  }
 739                  if ($before != $dependson[$itemid]) {
 740                      $somethingchanged = true;
 741                      if (!isset($dependencydepth[$itemid])) {
 742                          $dependencydepth[$itemid] = 1;
 743                      } else {
 744                          $dependencydepth[$itemid]++;
 745                      }
 746                  }
 747              }
 748          }
 749      }
 750  
 751      /**
 752       * Return array of grade item ids that are either hidden or indirectly depend
 753       * on hidden grades, excluded grades are not returned.
 754       * THIS IS A REALLY BIG HACK! to be replaced by conditional aggregation of hidden grades in 2.0
 755       *
 756       * @param array $grade_grades all course grades of one user, & used for better internal caching
 757       * @param array $grade_items array of grade items, & used for better internal caching
 758       * @return array This is an array of following arrays:
 759       *      unknown => list of item ids that may be affected by hiding (with the ITEM ID as both the key and the value) - for BC with old gradereport plugins
 760       *      unknowngrades => list of item ids that may be affected by hiding (with the calculated grade as the value)
 761       *      altered => list of item ids that are definitely affected by hiding (with the calculated grade as the value)
 762       *      alteredgrademax => for each item in altered or unknown, the new value of the grademax
 763       *      alteredgrademin => for each item in altered or unknown, the new value of the grademin
 764       *      alteredgradestatus => for each item with a modified status - the value of the new status
 765       *      alteredgradeweight => for each item with a modified weight - the value of the new weight
 766       */
 767      public static function get_hiding_affected(&$grade_grades, &$grade_items) {
 768          global $CFG;
 769  
 770          if (count($grade_grades) !== count($grade_items)) {
 771              print_error('invalidarraysize', 'debug', '', 'grade_grade::get_hiding_affected()!');
 772          }
 773  
 774          $dependson = array();
 775          $todo = array();
 776          $unknown = array();  // can not find altered
 777          $altered = array();  // altered grades
 778          $alteredgrademax = array();  // Altered grade max values.
 779          $alteredgrademin = array();  // Altered grade min values.
 780          $alteredaggregationstatus = array();  // Altered aggregation status.
 781          $alteredaggregationweight = array();  // Altered aggregation weight.
 782          $dependencydepth = array();
 783  
 784          $hiddenfound = false;
 785          foreach($grade_grades as $itemid=>$unused) {
 786              $grade_grade =& $grade_grades[$itemid];
 787              // We need the immediate dependencies of all every grade_item so we can calculate nested dependencies.
 788              $dependson[$grade_grade->itemid] = $grade_items[$grade_grade->itemid]->depends_on();
 789              if ($grade_grade->is_excluded()) {
 790                  //nothing to do, aggregation is ok
 791                  continue;
 792              } else if ($grade_grade->is_hidden()) {
 793                  $hiddenfound = true;
 794                  $altered[$grade_grade->itemid] = null;
 795                  $alteredaggregationstatus[$grade_grade->itemid] = 'dropped';
 796                  $alteredaggregationweight[$grade_grade->itemid] = 0;
 797              } else if ($grade_grade->is_overridden()) {
 798                  // No need to recalculate overridden grades.
 799                  continue;
 800              } else {
 801                  if (!empty($dependson[$grade_grade->itemid])) {
 802                      $dependencydepth[$grade_grade->itemid] = 1;
 803                      $todo[] = $grade_grade->itemid;
 804                  }
 805              }
 806          }
 807  
 808          // Flatten the dependency tree and count number of branches to each leaf.
 809          self::flatten_dependencies_array($dependson, $dependencydepth);
 810  
 811          if (!$hiddenfound) {
 812              return array('unknown' => array(),
 813                           'unknowngrades' => array(),
 814                           'altered' => array(),
 815                           'alteredgrademax' => array(),
 816                           'alteredgrademin' => array(),
 817                           'alteredaggregationstatus' => array(),
 818                           'alteredaggregationweight' => array());
 819          }
 820          // This line ensures that $dependencydepth has the same number of items as $todo.
 821          $dependencydepth = array_intersect_key($dependencydepth, array_flip($todo));
 822          // We need to resort the todo list by the dependency depth. This guarantees we process the leaves, then the branches.
 823          array_multisort($dependencydepth, $todo);
 824  
 825          $max = count($todo);
 826          $hidden_precursors = null;
 827          for($i=0; $i<$max; $i++) {
 828              $found = false;
 829              foreach($todo as $key=>$do) {
 830                  $hidden_precursors = array_intersect($dependson[$do], array_keys($unknown));
 831                  if ($hidden_precursors) {
 832                      // this item depends on hidden grade indirectly
 833                      $unknown[$do] = $grade_grades[$do]->finalgrade;
 834                      unset($todo[$key]);
 835                      $found = true;
 836                      continue;
 837  
 838                  } else if (!array_intersect($dependson[$do], $todo)) {
 839                      $hidden_precursors = array_intersect($dependson[$do], array_keys($altered));
 840                      // If the dependency is a sum aggregation, we need to process it as if it had hidden items.
 841                      // The reason for this, is that the code will recalculate the maxgrade by removing ungraded
 842                      // items and accounting for 'drop x grades' and then stored back in our virtual grade_items.
 843                      // This recalculation is necessary because there will be a call to:
 844                      //              $grade_category->aggregate_values_and_adjust_bounds
 845                      // for the top level grade that will depend on knowing what that caclulated grademax is
 846                      // and it finds that value by checking the virtual grade_items.
 847                      $issumaggregate = false;
 848                      if ($grade_items[$do]->itemtype == 'category') {
 849                          $issumaggregate = $grade_items[$do]->load_item_category()->aggregation == GRADE_AGGREGATE_SUM;
 850                      }
 851                      if (!$hidden_precursors && !$issumaggregate) {
 852                          unset($todo[$key]);
 853                          $found = true;
 854                          continue;
 855  
 856                      } else {
 857                          // depends on altered grades - we should try to recalculate if possible
 858                          if ($grade_items[$do]->is_calculated() or
 859                              (!$grade_items[$do]->is_category_item() and !$grade_items[$do]->is_course_item()) or
 860                              ($grade_items[$do]->is_category_item() and $grade_items[$do]->is_locked())
 861                          ) {
 862                              // This is a grade item that is not a category or course and has been affected by grade hiding.
 863                              // Or a grade item that is a category and it is locked.
 864                              // I guess this means it is a calculation that needs to be recalculated.
 865                              $unknown[$do] = $grade_grades[$do]->finalgrade;
 866                              unset($todo[$key]);
 867                              $found = true;
 868                              continue;
 869  
 870                          } else {
 871                              // This is a grade category (or course).
 872                              $grade_category = $grade_items[$do]->load_item_category();
 873  
 874                              // Build a new list of the grades in this category.
 875                              $values = array();
 876                              $immediatedepends = $grade_items[$do]->depends_on();
 877                              foreach ($immediatedepends as $itemid) {
 878                                  if (array_key_exists($itemid, $altered)) {
 879                                      //nulling an altered precursor
 880                                      $values[$itemid] = $altered[$itemid];
 881                                      if (is_null($values[$itemid])) {
 882                                          // This means this was a hidden grade item removed from the result.
 883                                          unset($values[$itemid]);
 884                                      }
 885                                  } elseif (empty($values[$itemid])) {
 886                                      $values[$itemid] = $grade_grades[$itemid]->finalgrade;
 887                                  }
 888                              }
 889  
 890                              foreach ($values as $itemid=>$value) {
 891                                  if ($grade_grades[$itemid]->is_excluded()) {
 892                                      unset($values[$itemid]);
 893                                      $alteredaggregationstatus[$itemid] = 'excluded';
 894                                      $alteredaggregationweight[$itemid] = null;
 895                                      continue;
 896                                  }
 897                                  // The grade min/max may have been altered by hiding.
 898                                  $grademin = $grade_items[$itemid]->grademin;
 899                                  if (isset($alteredgrademin[$itemid])) {
 900                                      $grademin = $alteredgrademin[$itemid];
 901                                  }
 902                                  $grademax = $grade_items[$itemid]->grademax;
 903                                  if (isset($alteredgrademax[$itemid])) {
 904                                      $grademax = $alteredgrademax[$itemid];
 905                                  }
 906                                  $values[$itemid] = grade_grade::standardise_score($value, $grademin, $grademax, 0, 1);
 907                              }
 908  
 909                              if ($grade_category->aggregateonlygraded) {
 910                                  foreach ($values as $itemid=>$value) {
 911                                      if (is_null($value)) {
 912                                          unset($values[$itemid]);
 913                                          $alteredaggregationstatus[$itemid] = 'novalue';
 914                                          $alteredaggregationweight[$itemid] = null;
 915                                      }
 916                                  }
 917                              } else {
 918                                  foreach ($values as $itemid=>$value) {
 919                                      if (is_null($value)) {
 920                                          $values[$itemid] = 0;
 921                                      }
 922                                  }
 923                              }
 924  
 925                              // limit and sort
 926                              $allvalues = $values;
 927                              $grade_category->apply_limit_rules($values, $grade_items);
 928  
 929                              $moredropped = array_diff($allvalues, $values);
 930                              foreach ($moredropped as $drop => $unused) {
 931                                  $alteredaggregationstatus[$drop] = 'dropped';
 932                                  $alteredaggregationweight[$drop] = null;
 933                              }
 934  
 935                              foreach ($values as $itemid => $val) {
 936                                  if ($grade_category->is_extracredit_used() && ($grade_items[$itemid]->aggregationcoef > 0)) {
 937                                      $alteredaggregationstatus[$itemid] = 'extra';
 938                                  }
 939                              }
 940  
 941                              asort($values, SORT_NUMERIC);
 942  
 943                              // let's see we have still enough grades to do any statistics
 944                              if (count($values) == 0) {
 945                                  // not enough attempts yet
 946                                  $altered[$do] = null;
 947                                  unset($todo[$key]);
 948                                  $found = true;
 949                                  continue;
 950                              }
 951  
 952                              $usedweights = array();
 953                              $adjustedgrade = $grade_category->aggregate_values_and_adjust_bounds($values, $grade_items, $usedweights);
 954  
 955                              // recalculate the rawgrade back to requested range
 956                              $finalgrade = grade_grade::standardise_score($adjustedgrade['grade'],
 957                                                                           0,
 958                                                                           1,
 959                                                                           $adjustedgrade['grademin'],
 960                                                                           $adjustedgrade['grademax']);
 961  
 962                              foreach ($usedweights as $itemid => $weight) {
 963                                  if (!isset($alteredaggregationstatus[$itemid])) {
 964                                      $alteredaggregationstatus[$itemid] = 'used';
 965                                  }
 966                                  $alteredaggregationweight[$itemid] = $weight;
 967                              }
 968  
 969                              $finalgrade = $grade_items[$do]->bounded_grade($finalgrade);
 970                              $alteredgrademin[$do] = $adjustedgrade['grademin'];
 971                              $alteredgrademax[$do] = $adjustedgrade['grademax'];
 972                              // We need to muck with the "in-memory" grade_items records so
 973                              // that subsequent calculations will use the adjusted grademin and grademax.
 974                              $grade_items[$do]->grademin = $adjustedgrade['grademin'];
 975                              $grade_items[$do]->grademax = $adjustedgrade['grademax'];
 976  
 977                              $altered[$do] = $finalgrade;
 978                              unset($todo[$key]);
 979                              $found = true;
 980                              continue;
 981                          }
 982                      }
 983                  }
 984              }
 985              if (!$found) {
 986                  break;
 987              }
 988          }
 989  
 990          return array('unknown' => array_combine(array_keys($unknown), array_keys($unknown)), // Left for BC in case some gradereport plugins expect it.
 991                       'unknowngrades' => $unknown,
 992                       'altered' => $altered,
 993                       'alteredgrademax' => $alteredgrademax,
 994                       'alteredgrademin' => $alteredgrademin,
 995                       'alteredaggregationstatus' => $alteredaggregationstatus,
 996                       'alteredaggregationweight' => $alteredaggregationweight);
 997      }
 998  
 999      /**
1000       * Returns true if the grade's value is superior or equal to the grade item's gradepass value, false otherwise.
1001       *
1002       * @param grade_item $grade_item An optional grade_item of which gradepass value we can use, saves having to load the grade_grade's grade_item
1003       * @return bool
1004       */
1005      public function is_passed($grade_item = null) {
1006          if (empty($grade_item)) {
1007              if (!isset($this->grade_item)) {
1008                  $this->load_grade_item();
1009              }
1010          } else {
1011              $this->grade_item = $grade_item;
1012              $this->itemid = $grade_item->id;
1013          }
1014  
1015          // Return null if finalgrade is null
1016          if (is_null($this->finalgrade)) {
1017              return null;
1018          }
1019  
1020          // Return null if gradepass == grademin, gradepass is null, or grade item is a scale and gradepass is 0.
1021          if (is_null($this->grade_item->gradepass)) {
1022              return null;
1023          } else if ($this->grade_item->gradepass == $this->grade_item->grademin) {
1024              return null;
1025          } else if ($this->grade_item->gradetype == GRADE_TYPE_SCALE && !grade_floats_different($this->grade_item->gradepass, 0.0)) {
1026              return null;
1027          }
1028  
1029          return $this->finalgrade >= $this->grade_item->gradepass;
1030      }
1031  
1032      /**
1033       * Insert the grade_grade instance into the database.
1034       *
1035       * @param string $source From where was the object inserted (mod/forum, manual, etc.)
1036       * @return int The new grade_grade ID if successful, false otherwise
1037       */
1038      public function insert($source=null) {
1039          // TODO: dategraded hack - do not update times, they are used for submission and grading (MDL-31379)
1040          //$this->timecreated = $this->timemodified = time();
1041          return parent::insert($source);
1042      }
1043  
1044      /**
1045       * In addition to update() as defined in grade_object rounds the float numbers using php function,
1046       * the reason is we need to compare the db value with computed number to skip updates if possible.
1047       *
1048       * @param string $source from where was the object inserted (mod/forum, manual, etc.)
1049       * @return bool success
1050       */
1051      public function update($source=null) {
1052          $this->rawgrade = grade_floatval($this->rawgrade);
1053          $this->finalgrade = grade_floatval($this->finalgrade);
1054          $this->rawgrademin = grade_floatval($this->rawgrademin);
1055          $this->rawgrademax = grade_floatval($this->rawgrademax);
1056          return parent::update($source);
1057      }
1058  
1059  
1060      /**
1061       * Handles adding feedback files in the gradebook.
1062       *
1063       * @param int|null $historyid
1064       */
1065      protected function add_feedback_files(int $historyid = null) {
1066          global $CFG;
1067  
1068          // We only support feedback files for modules atm.
1069          if ($this->grade_item && $this->grade_item->is_external_item()) {
1070              $context = $this->get_context();
1071              $this->copy_feedback_files($context, GRADE_FEEDBACK_FILEAREA, $this->id);
1072  
1073              if (empty($CFG->disablegradehistory) && $historyid) {
1074                  $this->copy_feedback_files($context, GRADE_HISTORY_FEEDBACK_FILEAREA, $historyid);
1075              }
1076          }
1077  
1078          return $this->id;
1079      }
1080  
1081      /**
1082       * Handles updating feedback files in the gradebook.
1083       *
1084       * @param int|null $historyid
1085       */
1086      protected function update_feedback_files(int $historyid = null) {
1087          global $CFG;
1088  
1089          // We only support feedback files for modules atm.
1090          if ($this->grade_item && $this->grade_item->is_external_item()) {
1091              $context = $this->get_context();
1092  
1093              $fs = new file_storage();
1094              $fs->delete_area_files($context->id, GRADE_FILE_COMPONENT, GRADE_FEEDBACK_FILEAREA, $this->id);
1095  
1096              $this->copy_feedback_files($context, GRADE_FEEDBACK_FILEAREA, $this->id);
1097  
1098              if (empty($CFG->disablegradehistory) && $historyid) {
1099                  $this->copy_feedback_files($context, GRADE_HISTORY_FEEDBACK_FILEAREA, $historyid);
1100              }
1101          }
1102  
1103          return true;
1104      }
1105  
1106      /**
1107       * Handles deleting feedback files in the gradebook.
1108       */
1109      protected function delete_feedback_files() {
1110          // We only support feedback files for modules atm.
1111          if ($this->grade_item && $this->grade_item->is_external_item()) {
1112              $context = $this->get_context();
1113  
1114              $fs = new file_storage();
1115              $fs->delete_area_files($context->id, GRADE_FILE_COMPONENT, GRADE_FEEDBACK_FILEAREA, $this->id);
1116  
1117              // Grade history only gets deleted when we delete the whole grade item.
1118          }
1119  
1120          return true;
1121      }
1122  
1123      /**
1124       * Deletes the grade_grade instance from the database.
1125       *
1126       * @param string $source The location the deletion occurred (mod/forum, manual, etc.).
1127       * @return bool Returns true if the deletion was successful, false otherwise.
1128       */
1129      public function delete($source = null) {
1130          global $DB;
1131  
1132          $transaction = $DB->start_delegated_transaction();
1133          $success = parent::delete($source);
1134  
1135          // If the grade was deleted successfully trigger a grade_deleted event.
1136          if ($success && !empty($this->grade_item)) {
1137              \core\event\grade_deleted::create_from_grade($this)->trigger();
1138          }
1139  
1140          $transaction->allow_commit();
1141          return $success;
1142      }
1143  
1144      /**
1145       * Used to notify the completion system (if necessary) that a user's grade
1146       * has changed, and clear up a possible score cache.
1147       *
1148       * @param bool $deleted True if grade was actually deleted
1149       */
1150      protected function notify_changed($deleted) {
1151          global $CFG;
1152  
1153          // Condition code may cache the grades for conditional availability of
1154          // modules or sections. (This code should use a hook for communication
1155          // with plugin, but hooks are not implemented at time of writing.)
1156          if (!empty($CFG->enableavailability) && class_exists('\availability_grade\callbacks')) {
1157              \availability_grade\callbacks::grade_changed($this->userid);
1158          }
1159  
1160          require_once($CFG->libdir.'/completionlib.php');
1161  
1162          // Bail out immediately if completion is not enabled for site (saves loading
1163          // grade item & requiring the restore stuff).
1164          if (!completion_info::is_enabled_for_site()) {
1165              return;
1166          }
1167  
1168          // Ignore during restore, as completion data will be updated anyway and
1169          // doing it now will result in incorrect dates (it will say they got the
1170          // grade completion now, instead of the correct time).
1171          if (class_exists('restore_controller', false) && restore_controller::is_executing()) {
1172              return;
1173          }
1174  
1175          // Load information about grade item, exit if the grade item is missing.
1176          if (!$this->load_grade_item()) {
1177              return;
1178          }
1179  
1180          // Only course-modules have completion data
1181          if ($this->grade_item->itemtype!='mod') {
1182              return;
1183          }
1184  
1185          // Use $COURSE if available otherwise get it via item fields
1186          $course = get_course($this->grade_item->courseid, false);
1187  
1188          // Bail out if completion is not enabled for course
1189          $completion = new completion_info($course);
1190          if (!$completion->is_enabled()) {
1191              return;
1192          }
1193  
1194          // Get course-module
1195          $cm = get_coursemodule_from_instance($this->grade_item->itemmodule,
1196                $this->grade_item->iteminstance, $this->grade_item->courseid);
1197          // If the course-module doesn't exist, display a warning...
1198          if (!$cm) {
1199              // ...unless the grade is being deleted in which case it's likely
1200              // that the course-module was just deleted too, so that's okay.
1201              if (!$deleted) {
1202                  debugging("Couldn't find course-module for module '" .
1203                          $this->grade_item->itemmodule . "', instance '" .
1204                          $this->grade_item->iteminstance . "', course '" .
1205                          $this->grade_item->courseid . "'");
1206              }
1207              return;
1208          }
1209  
1210          // Pass information on to completion system
1211          $completion->inform_grade_changed($cm, $this->grade_item, $this, $deleted);
1212      }
1213  
1214      /**
1215       * Get some useful information about how this grade_grade is reflected in the aggregation
1216       * for the grade_category. For example this could be an extra credit item, and it could be
1217       * dropped because it's in the X lowest or highest.
1218       *
1219       * @return array(status, weight) - A keyword and a numerical weight that represents how this grade was included in the aggregation.
1220       */
1221      function get_aggregation_hint() {
1222          return array('status' => $this->get_aggregationstatus(),
1223                       'weight' => $this->get_aggregationweight());
1224      }
1225  
1226      /**
1227       * Handles copying feedback files to a specified gradebook file area.
1228       *
1229       * @param context $context
1230       * @param string $filearea
1231       * @param int $itemid
1232       */
1233      private function copy_feedback_files(context $context, string $filearea, int $itemid) {
1234          if ($this->feedbackfiles) {
1235              $filestocopycontextid = $this->feedbackfiles['contextid'];
1236              $filestocopycomponent = $this->feedbackfiles['component'];
1237              $filestocopyfilearea = $this->feedbackfiles['filearea'];
1238              $filestocopyitemid = $this->feedbackfiles['itemid'];
1239  
1240              $fs = new file_storage();
1241              if ($filestocopy = $fs->get_area_files($filestocopycontextid, $filestocopycomponent, $filestocopyfilearea,
1242                      $filestocopyitemid)) {
1243                  foreach ($filestocopy as $filetocopy) {
1244                      $destination = [
1245                          'contextid' => $context->id,
1246                          'component' => GRADE_FILE_COMPONENT,
1247                          'filearea' => $filearea,
1248                          'itemid' => $itemid
1249                      ];
1250                      $fs->create_file_from_storedfile($destination, $filetocopy);
1251                  }
1252              }
1253          }
1254      }
1255  
1256      /**
1257       * Determine the correct context for this grade_grade.
1258       *
1259       * @return context
1260       */
1261      public function get_context() {
1262          $this->load_grade_item();
1263          return $this->grade_item->get_context();
1264      }
1265  }