Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/grade/ -> grade_grade.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]
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(null, true); 446 return true; 447 448 } else if (!empty($this->overridden) and !$state) { 449 $this->overridden = 0; 450 $this->update(null, true); 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 throw new \moodle_exception('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 * In addition to update() as defined in grade_object rounds the float numbers using php function, 1034 * the reason is we need to compare the db value with computed number to skip updates if possible. 1035 * 1036 * @param string $source from where was the object inserted (mod/forum, manual, etc.) 1037 * @param bool $isbulkupdate If bulk grade update is happening. 1038 * @return bool success 1039 */ 1040 public function update($source=null, $isbulkupdate = false) { 1041 $this->rawgrade = grade_floatval($this->rawgrade); 1042 $this->finalgrade = grade_floatval($this->finalgrade); 1043 $this->rawgrademin = grade_floatval($this->rawgrademin); 1044 $this->rawgrademax = grade_floatval($this->rawgrademax); 1045 return parent::update($source, $isbulkupdate); 1046 } 1047 1048 1049 /** 1050 * Handles adding feedback files in the gradebook. 1051 * 1052 * @param int|null $historyid 1053 */ 1054 protected function add_feedback_files(int $historyid = null) { 1055 global $CFG; 1056 1057 // We only support feedback files for modules atm. 1058 if ($this->grade_item && $this->grade_item->is_external_item()) { 1059 $context = $this->get_context(); 1060 $this->copy_feedback_files($context, GRADE_FEEDBACK_FILEAREA, $this->id); 1061 1062 if (empty($CFG->disablegradehistory) && $historyid) { 1063 $this->copy_feedback_files($context, GRADE_HISTORY_FEEDBACK_FILEAREA, $historyid); 1064 } 1065 } 1066 1067 return $this->id; 1068 } 1069 1070 /** 1071 * Handles updating feedback files in the gradebook. 1072 * 1073 * @param int|null $historyid 1074 */ 1075 protected function update_feedback_files(int $historyid = null) { 1076 global $CFG; 1077 1078 // We only support feedback files for modules atm. 1079 if ($this->grade_item && $this->grade_item->is_external_item()) { 1080 $context = $this->get_context(); 1081 1082 $fs = new file_storage(); 1083 $fs->delete_area_files($context->id, GRADE_FILE_COMPONENT, GRADE_FEEDBACK_FILEAREA, $this->id); 1084 1085 $this->copy_feedback_files($context, GRADE_FEEDBACK_FILEAREA, $this->id); 1086 1087 if (empty($CFG->disablegradehistory) && $historyid) { 1088 $this->copy_feedback_files($context, GRADE_HISTORY_FEEDBACK_FILEAREA, $historyid); 1089 } 1090 } 1091 1092 return true; 1093 } 1094 1095 /** 1096 * Handles deleting feedback files in the gradebook. 1097 */ 1098 protected function delete_feedback_files() { 1099 // We only support feedback files for modules atm. 1100 if ($this->grade_item && $this->grade_item->is_external_item()) { 1101 $context = $this->get_context(); 1102 1103 $fs = new file_storage(); 1104 $fs->delete_area_files($context->id, GRADE_FILE_COMPONENT, GRADE_FEEDBACK_FILEAREA, $this->id); 1105 1106 // Grade history only gets deleted when we delete the whole grade item. 1107 } 1108 1109 return true; 1110 } 1111 1112 /** 1113 * Deletes the grade_grade instance from the database. 1114 * 1115 * @param string $source The location the deletion occurred (mod/forum, manual, etc.). 1116 * @return bool Returns true if the deletion was successful, false otherwise. 1117 */ 1118 public function delete($source = null) { 1119 global $DB; 1120 1121 $transaction = $DB->start_delegated_transaction(); 1122 $success = parent::delete($source); 1123 1124 // If the grade was deleted successfully trigger a grade_deleted event. 1125 if ($success && !empty($this->grade_item)) { 1126 \core\event\grade_deleted::create_from_grade($this)->trigger(); 1127 } 1128 1129 $transaction->allow_commit(); 1130 return $success; 1131 } 1132 1133 /** 1134 * Used to notify the completion system (if necessary) that a user's grade 1135 * has changed, and clear up a possible score cache. 1136 * 1137 * @param bool $deleted True if grade was actually deleted 1138 * @param bool $isbulkupdate If bulk grade update is happening. 1139 */ 1140 protected function notify_changed($deleted, $isbulkupdate = false) { 1141 global $CFG; 1142 1143 // Condition code may cache the grades for conditional availability of 1144 // modules or sections. (This code should use a hook for communication 1145 // with plugin, but hooks are not implemented at time of writing.) 1146 if (!empty($CFG->enableavailability) && class_exists('\availability_grade\callbacks')) { 1147 \availability_grade\callbacks::grade_changed($this->userid); 1148 } 1149 1150 require_once($CFG->libdir.'/completionlib.php'); 1151 1152 // Bail out immediately if completion is not enabled for site (saves loading 1153 // grade item & requiring the restore stuff). 1154 if (!completion_info::is_enabled_for_site()) { 1155 return; 1156 } 1157 1158 // Ignore during restore, as completion data will be updated anyway and 1159 // doing it now will result in incorrect dates (it will say they got the 1160 // grade completion now, instead of the correct time). 1161 if (class_exists('restore_controller', false) && restore_controller::is_executing()) { 1162 return; 1163 } 1164 1165 // Load information about grade item, exit if the grade item is missing. 1166 if (!$this->load_grade_item()) { 1167 return; 1168 } 1169 1170 // Only course-modules have completion data 1171 if ($this->grade_item->itemtype!='mod') { 1172 return; 1173 } 1174 1175 // Use $COURSE if available otherwise get it via item fields 1176 $course = get_course($this->grade_item->courseid, false); 1177 1178 // Bail out if completion is not enabled for course 1179 $completion = new completion_info($course); 1180 if (!$completion->is_enabled()) { 1181 return; 1182 } 1183 1184 // Get course-module 1185 $cm = get_coursemodule_from_instance($this->grade_item->itemmodule, 1186 $this->grade_item->iteminstance, $this->grade_item->courseid); 1187 // If the course-module doesn't exist, display a warning... 1188 if (!$cm) { 1189 // ...unless the grade is being deleted in which case it's likely 1190 // that the course-module was just deleted too, so that's okay. 1191 if (!$deleted) { 1192 debugging("Couldn't find course-module for module '" . 1193 $this->grade_item->itemmodule . "', instance '" . 1194 $this->grade_item->iteminstance . "', course '" . 1195 $this->grade_item->courseid . "'"); 1196 } 1197 return; 1198 } 1199 1200 // Pass information on to completion system 1201 $completion->inform_grade_changed($cm, $this->grade_item, $this, $deleted, $isbulkupdate); 1202 } 1203 1204 /** 1205 * Get some useful information about how this grade_grade is reflected in the aggregation 1206 * for the grade_category. For example this could be an extra credit item, and it could be 1207 * dropped because it's in the X lowest or highest. 1208 * 1209 * @return array(status, weight) - A keyword and a numerical weight that represents how this grade was included in the aggregation. 1210 */ 1211 function get_aggregation_hint() { 1212 return array('status' => $this->get_aggregationstatus(), 1213 'weight' => $this->get_aggregationweight()); 1214 } 1215 1216 /** 1217 * Handles copying feedback files to a specified gradebook file area. 1218 * 1219 * @param context $context 1220 * @param string $filearea 1221 * @param int $itemid 1222 */ 1223 private function copy_feedback_files(context $context, string $filearea, int $itemid) { 1224 if ($this->feedbackfiles) { 1225 $filestocopycontextid = $this->feedbackfiles['contextid']; 1226 $filestocopycomponent = $this->feedbackfiles['component']; 1227 $filestocopyfilearea = $this->feedbackfiles['filearea']; 1228 $filestocopyitemid = $this->feedbackfiles['itemid']; 1229 1230 $fs = new file_storage(); 1231 if ($filestocopy = $fs->get_area_files($filestocopycontextid, $filestocopycomponent, $filestocopyfilearea, 1232 $filestocopyitemid)) { 1233 foreach ($filestocopy as $filetocopy) { 1234 $destination = [ 1235 'contextid' => $context->id, 1236 'component' => GRADE_FILE_COMPONENT, 1237 'filearea' => $filearea, 1238 'itemid' => $itemid 1239 ]; 1240 $fs->create_file_from_storedfile($destination, $filetocopy); 1241 } 1242 } 1243 } 1244 } 1245 1246 /** 1247 * Determine the correct context for this grade_grade. 1248 * 1249 * @return context 1250 */ 1251 public function get_context() { 1252 $this->load_grade_item(); 1253 return $this->grade_item->get_context(); 1254 } 1255 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
