2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Definition of a class to represent an individual user's grade
20 * @package core_grades
22 * @copyright 2006 Nicolas Connault
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 defined('MOODLE_INTERNAL') ||
die();
28 require_once('grade_object.php');
31 * grade_grades is an object mapped to DB table {prefix}grade_grades
33 * @package core_grades
35 * @copyright 2006 Nicolas Connault
36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 class grade_grade
extends grade_object
{
44 public $table = 'grade_grades';
47 * Array of required table fields, must start with 'id'.
48 * @var array $required_fields
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');
56 * Array of optional fields with default values (these should match db defaults)
57 * @var array $optional_fields
59 public $optional_fields = array('feedback'=>null, 'feedbackformat'=>0, 'information'=>null, 'informationformat'=>0);
62 * The id of the grade_item this grade belongs to.
68 * The grade_item object referenced by $this->itemid.
69 * @var grade_item $grade_item
74 * The id of the user this grade belongs to.
80 * The grade value of this raw grade, if such was provided by the module.
81 * @var float $rawgrade
86 * The maximum allowable grade when this grade was created.
87 * @var float $rawgrademax
89 public $rawgrademax = 100;
92 * The minimum allowable grade when this grade was created.
93 * @var float $rawgrademin
95 public $rawgrademin = 0;
98 * id of the scale, if this grade is based on a scale.
99 * @var int $rawscaleid
104 * The userid of the person who last modified this grade.
105 * @var int $usermodified
107 public $usermodified;
110 * The final value of this grade.
111 * @var float $finalgrade
116 * 0 if visible, 1 always hidden or date not visible until
122 * 0 not locked, date when the item was locked
128 * 0 no automatic locking, date when to lock the grade automatically
129 * @var float $locktime
131 public $locktime = 0;
135 * @var bool $exported
137 public $exported = 0;
141 * @var bool $overridden
143 public $overridden = 0;
146 * Grade excluded from aggregation functions
147 * @var bool $excluded
149 public $excluded = 0;
152 * TODO: HACK: create a new field datesubmitted - the date of submission if any (MDL-31377)
153 * @var bool $timecreated
155 public $timecreated = null;
158 * TODO: HACK: create a new field dategraded - the date of grading (MDL-31378)
159 * @var bool $timemodified
161 public $timemodified = null;
164 * Aggregation status flag. Can be one of 'unknown', 'dropped', 'novalue' or 'used'.
165 * @var string $aggregationstatus
167 public $aggregationstatus = 'unknown';
170 * Aggregation weight is the specific weight used in the aggregation calculation for this grade.
171 * @var float $aggregationweight
173 public $aggregationweight = null;
176 * Feedback files to copy.
182 * 'component' => 'mod_xyz',
183 * 'filearea' => 'mod_xyz_feedback',
189 public $feedbackfiles = [];
192 * Returns array of grades for given grade_item+users
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
199 public static function fetch_users_grades($grade_item, $userids, $include_missing=true) {
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
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);
213 list($user_ids_cvs, $params) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED
, 'uid0');
214 $params['giid'] = $grade_item->id
;
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);
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;
236 * Loads the grade_item object referenced by $this->itemid and saves it as $this->grade_item for easy access
238 * @return grade_item The grade_item instance referenced by $this->itemid
240 public function load_grade_item() {
241 if (empty($this->itemid
)) {
242 debugging('Missing itemid');
243 $this->grade_item
= null;
247 if (empty($this->grade_item
)) {
248 $this->grade_item
= grade_item
::fetch(array('id'=>$this->itemid
));
250 } else if ($this->grade_item
->id
!= $this->itemid
) {
251 debugging('Itemid mismatch');
252 $this->grade_item
= grade_item
::fetch(array('id'=>$this->itemid
));
255 if (empty($this->grade_item
)) {
256 debugging("Missing grade item id $this->itemid", DEBUG_DEVELOPER
);
259 return $this->grade_item
;
263 * Is grading object editable?
267 public function is_editable() {
268 if ($this->is_locked()) {
272 $grade_item = $this->load_grade_item();
274 if ($grade_item->gradetype
== GRADE_TYPE_NONE
) {
278 if ($grade_item->is_course_item() or $grade_item->is_category_item()) {
279 return (bool)get_config('moodle', 'grade_overridecat');
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.
290 * @return bool True if locked, false if not
292 public function is_locked() {
293 $this->load_grade_item();
294 if (empty($this->grade_item
)) {
295 return !empty($this->locked
);
297 return !empty($this->locked
) or $this->grade_item
->is_locked();
302 * Checks if grade overridden
304 * @return bool True if grade is overriden
306 public function is_overridden() {
307 return !empty($this->overridden
);
311 * Returns timestamp of submission related to this grade, null if not submitted.
313 * @return int Timestamp
315 public function get_datesubmitted() {
316 //TODO: HACK - create new fields (MDL-31379)
317 return $this->timecreated
;
321 * Returns the weight this grade contributed to the aggregated grade
325 public function get_aggregationweight() {
326 return $this->aggregationweight
;
330 * Set aggregationweight.
332 * @param float $aggregationweight
335 public function set_aggregationweight($aggregationweight) {
336 $this->aggregationweight
= $aggregationweight;
341 * Returns the info on how this value was used in the aggregated grade
343 * @return string One of 'dropped', 'excluded', 'novalue', 'used' or 'extra'
345 public function get_aggregationstatus() {
346 return $this->aggregationstatus
;
350 * Set aggregationstatus flag
352 * @param string $aggregationstatus
355 public function set_aggregationstatus($aggregationstatus) {
356 $this->aggregationstatus
= $aggregationstatus;
361 * Returns the minimum and maximum number of points this grade is graded with respect to.
363 * @since Moodle 2.8.7, 2.9.1
364 * @return array A list containing, in order, the minimum and maximum number of points.
366 protected function get_grade_min_and_max() {
368 $this->load_grade_item();
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
);
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
);
382 return array($this->grade_item
->grademin
, $this->grade_item
->grademax
);
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
);
390 return array($this->grade_item
->grademin
, $this->grade_item
->grademax
);
396 * Returns the minimum number of points this grade is graded with.
398 * @since Moodle 2.8.7, 2.9.1
399 * @return float The minimum number of points
401 public function get_grade_min() {
402 list($min, $max) = $this->get_grade_min_and_max();
408 * Returns the maximum number of points this grade is graded with respect to.
410 * @since Moodle 2.8.7, 2.9.1
411 * @return float The maximum number of points
413 public function get_grade_max() {
414 list($min, $max) = $this->get_grade_min_and_max();
420 * Returns timestamp when last graded, null if no grade present
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
;
431 return $this->timemodified
;
436 * Set the overridden status of grade
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
442 public function set_overridden($state, $refresh = true) {
443 if (empty($this->overridden
) and $state) {
444 $this->overridden
= time();
445 $this->update(null, true);
448 } else if (!empty($this->overridden
) and !$state) {
449 $this->overridden
= 0;
450 $this->update(null, true);
453 //refresh when unlocking
454 $this->grade_item
->refresh_grades($this->userid
);
463 * Checks if grade excluded from aggregation functions
465 * @return bool True if grade is excluded from aggregation
467 public function is_excluded() {
468 return !empty($this->excluded
);
472 * Set the excluded status of grade
474 * @param bool $state requested excluded state
475 * @return bool True is database state changed
477 public function set_excluded($state) {
478 if (empty($this->excluded
) and $state) {
479 $this->excluded
= time();
483 } else if (!empty($this->excluded
) and !$state) {
492 * Lock/unlock this grade.
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
499 public function set_locked($lockedstate, $cascade=false, $refresh=true) {
500 $this->load_grade_item();
503 if ($this->grade_item
->needsupdate
) {
504 //can not lock grade if final not calculated!
508 $this->locked
= time();
514 if (!empty($this->locked
) and $this->locktime
< time()) {
515 //we have to reset locktime or else it would lock up again
519 // remove the locked flag
523 if ($refresh and !$this->is_overridden()) {
524 //refresh when unlocking and not overridden
525 $this->grade_item
->refresh_grades($this->userid
);
533 * Lock the grade if needed. Make sure this is called only when final grades are valid
535 * @param array $items array of all grade item ids
538 public static function check_locktime_all($items) {
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);
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');
554 * Set the locktime for this grade.
556 * @param int $locktime timestamp for lock to activate
559 public function set_locktime($locktime) {
560 $this->locktime
= $locktime;
565 * Get the locktime for this grade.
567 * @return int $locktime timestamp for lock to activate
569 public function get_locktime() {
570 $this->load_grade_item();
572 $item_locktime = $this->grade_item
->get_locktime();
574 if (empty($this->locktime
) or ($item_locktime and $item_locktime < $this->locktime
)) {
575 return $item_locktime;
578 return $this->locktime
;
583 * Check grade hidden status. Uses data from both grade item and grade.
585 * @return bool true if hidden, false if not
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());
592 return $this->hidden
== 1 or ($this->hidden
!= 0 and $this->hidden
> time()) or $this->grade_item
->is_hidden();
597 * Check grade hidden status. Uses data from both grade item and grade.
599 * @return bool true if hiddenuntil, false if not
601 public function is_hiddenuntil() {
602 $this->load_grade_item();
604 if ($this->hidden
== 1 or $this->grade_item
->hidden
== 1) {
605 return false; //always hidden
608 if ($this->hidden
> 1 or $this->grade_item
->hidden
> 1) {
616 * Check grade hidden status. Uses data from both grade item and grade.
618 * @return int 0 means visible, 1 hidden always, timestamp hidden until
620 public function get_hidden() {
621 $this->load_grade_item();
623 $item_hidden = $this->grade_item
->get_hidden();
625 if ($item_hidden == 1) {
628 } else if ($item_hidden == 0) {
629 return $this->hidden
;
632 if ($this->hidden
== 0) {
634 } else if ($this->hidden
== 1) {
636 } else if ($this->hidden
> $item_hidden) {
637 return $this->hidden
;
645 * Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.
647 * @param int $hidden new hidden status
648 * @param bool $cascade ignored
650 public function set_hidden($hidden, $cascade=false) {
651 $this->hidden
= $hidden;
656 * Finds and returns a grade_grade instance based on params.
658 * @param array $params associative arrays varname=>value
659 * @return grade_grade Returns a grade_grade instance or false if none found
661 public static function fetch($params) {
662 return grade_object
::fetch_helper('grade_grades', 'grade_grade', $params);
666 * Finds and returns all grade_grade instances based on params.
668 * @param array $params associative arrays varname=>value
669 * @return array array of grade_grade instances or false if none found.
671 public static function fetch_all($params) {
672 return grade_object
::fetch_all_helper('grade_grades', 'grade_grade', $params);
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 :-)
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
687 public static function standardise_score($rawgrade, $source_min, $source_max, $target_min, $target_max) {
688 if (is_null($rawgrade)) {
692 if ($source_max == $source_min or $target_min == $target_max) {
693 // prevent division by 0
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;
704 * Given an array like this:
705 * $a = array(1=>array(2, 3),
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.
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
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);
729 while ($somethingchanged) {
730 $somethingchanged = false;
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
);
739 if ($before != $dependson[$itemid]) {
740 $somethingchanged = true;
741 if (!isset($dependencydepth[$itemid])) {
742 $dependencydepth[$itemid] = 1;
744 $dependencydepth[$itemid]++
;
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
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
767 public static function get_hiding_affected(&$grade_grades, &$grade_items) {
770 if (count($grade_grades) !== count($grade_items)) {
771 throw new \
moodle_exception('invalidarraysize', 'debug', '', 'grade_grade::get_hiding_affected()!');
774 $dependson = 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();
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
792 } else if ($grade_grade->is_hidden()) {
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.
801 if (!empty($dependson[$grade_grade->itemid
])) {
802 $dependencydepth[$grade_grade->itemid
] = 1;
803 $todo[] = $grade_grade->itemid
;
808 // Flatten the dependency tree and count number of branches to each leaf.
809 self
::flatten_dependencies_array($dependson, $dependencydepth);
812 return array('unknown' => array(),
813 'unknowngrades' => array(),
814 'altered' => array(),
815 'alteredgrademax' => array(),
816 'alteredgrademin' => array(),
817 'alteredaggregationstatus' => array(),
818 'alteredaggregationweight' => array());
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);
826 $hidden_precursors = null;
827 for($i=0; $i<$max; $i++
) {
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
;
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
;
851 if (!$hidden_precursors && !$issumaggregate) {
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())
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
;
871 // This is a grade category (or course).
872 $grade_category = $grade_items[$do]->load_item_category();
874 // Build a new list of the grades in this category.
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]);
885 } elseif (empty($values[$itemid])) {
886 $values[$itemid] = $grade_grades[$itemid]->finalgrade
;
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;
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];
902 $grademax = $grade_items[$itemid]->grademax
;
903 if (isset($alteredgrademax[$itemid])) {
904 $grademax = $alteredgrademax[$itemid];
906 $values[$itemid] = grade_grade
::standardise_score($value, $grademin, $grademax, 0, 1);
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;
918 foreach ($values as $itemid=>$value) {
919 if (is_null($value)) {
920 $values[$itemid] = 0;
926 $allvalues = $values;
927 $grade_category->apply_limit_rules($values, $grade_items);
929 $moredropped = array_diff($allvalues, $values);
930 foreach ($moredropped as $drop => $unused) {
931 $alteredaggregationstatus[$drop] = 'dropped';
932 $alteredaggregationweight[$drop] = null;
935 foreach ($values as $itemid => $val) {
936 if ($grade_category->is_extracredit_used() && ($grade_items[$itemid]->aggregationcoef
> 0)) {
937 $alteredaggregationstatus[$itemid] = 'extra';
941 asort($values, SORT_NUMERIC
);
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;
952 $usedweights = array();
953 $adjustedgrade = $grade_category->aggregate_values_and_adjust_bounds($values, $grade_items, $usedweights);
955 // recalculate the rawgrade back to requested range
956 $finalgrade = grade_grade
::standardise_score($adjustedgrade['grade'],
959 $adjustedgrade['grademin'],
960 $adjustedgrade['grademax']);
962 foreach ($usedweights as $itemid => $weight) {
963 if (!isset($alteredaggregationstatus[$itemid])) {
964 $alteredaggregationstatus[$itemid] = 'used';
966 $alteredaggregationweight[$itemid] = $weight;
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'];
977 $altered[$do] = $finalgrade;
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);
1000 * Returns true if the grade's value is superior or equal to the grade item's gradepass value, false otherwise.
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
1005 public function is_passed($grade_item = null) {
1006 if (empty($grade_item)) {
1007 if (!isset($this->grade_item
)) {
1008 $this->load_grade_item();
1011 $this->grade_item
= $grade_item;
1012 $this->itemid
= $grade_item->id
;
1015 // Return null if finalgrade is null
1016 if (is_null($this->finalgrade
)) {
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
)) {
1023 } else if ($this->grade_item
->gradepass
== $this->grade_item
->grademin
) {
1025 } else if ($this->grade_item
->gradetype
== GRADE_TYPE_SCALE
&& !grade_floats_different($this->grade_item
->gradepass
, 0.0)) {
1029 return $this->finalgrade
>= $this->grade_item
->gradepass
;
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.
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
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);
1050 * Handles adding feedback files in the gradebook.
1052 * @param int|null $historyid
1054 protected function add_feedback_files(int $historyid = null) {
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
);
1062 if (empty($CFG->disablegradehistory
) && $historyid) {
1063 $this->copy_feedback_files($context, GRADE_HISTORY_FEEDBACK_FILEAREA
, $historyid);
1071 * Handles updating feedback files in the gradebook.
1073 * @param int|null $historyid
1075 protected function update_feedback_files(int $historyid = null) {
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();
1082 $fs = new file_storage();
1083 $fs->delete_area_files($context->id
, GRADE_FILE_COMPONENT
, GRADE_FEEDBACK_FILEAREA
, $this->id
);
1085 $this->copy_feedback_files($context, GRADE_FEEDBACK_FILEAREA
, $this->id
);
1087 if (empty($CFG->disablegradehistory
) && $historyid) {
1088 $this->copy_feedback_files($context, GRADE_HISTORY_FEEDBACK_FILEAREA
, $historyid);
1096 * Handles deleting feedback files in the gradebook.
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();
1103 $fs = new file_storage();
1104 $fs->delete_area_files($context->id
, GRADE_FILE_COMPONENT
, GRADE_FEEDBACK_FILEAREA
, $this->id
);
1106 // Grade history only gets deleted when we delete the whole grade item.
1113 * Deletes the grade_grade instance from the database.
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.
1118 public function delete($source = null) {
1121 $transaction = $DB->start_delegated_transaction();
1122 $success = parent
::delete($source);
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();
1129 $transaction->allow_commit();
1134 * Used to notify the completion system (if necessary) that a user's grade
1135 * has changed, and clear up a possible score cache.
1137 * @param bool $deleted True if grade was actually deleted
1138 * @param bool $isbulkupdate If bulk grade update is happening.
1140 protected function notify_changed($deleted, $isbulkupdate = false) {
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
);
1150 require_once($CFG->libdir
.'/completionlib.php');
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()) {
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()) {
1165 // Load information about grade item, exit if the grade item is missing.
1166 if (!$this->load_grade_item()) {
1170 // Only course-modules have completion data
1171 if ($this->grade_item
->itemtype
!='mod') {
1175 // Use $COURSE if available otherwise get it via item fields
1176 $course = get_course($this->grade_item
->courseid
, false);
1178 // Bail out if completion is not enabled for course
1179 $completion = new completion_info($course);
1180 if (!$completion->is_enabled()) {
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...
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.
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
. "'");
1200 // Pass information on to completion system
1201 $completion->inform_grade_changed($cm, $this->grade_item
, $this, $deleted, $isbulkupdate);
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.
1209 * @return array(status, weight) - A keyword and a numerical weight that represents how this grade was included in the aggregation.
1211 function get_aggregation_hint() {
1212 return array('status' => $this->get_aggregationstatus(),
1213 'weight' => $this->get_aggregationweight());
1217 * Handles copying feedback files to a specified gradebook file area.
1219 * @param context $context
1220 * @param string $filearea
1221 * @param int $itemid
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'];
1230 $fs = new file_storage();
1231 if ($filestocopy = $fs->get_area_files($filestocopycontextid, $filestocopycomponent, $filestocopyfilearea,
1232 $filestocopyitemid)) {
1233 foreach ($filestocopy as $filetocopy) {
1235 'contextid' => $context->id
,
1236 'component' => GRADE_FILE_COMPONENT
,
1237 'filearea' => $filearea,
1240 $fs->create_file_from_storedfile($destination, $filetocopy);
1247 * Determine the correct context for this grade_grade.
1251 public function get_context() {
1252 $this->load_grade_item();
1253 return $this->grade_item
->get_context();