MDL-47637 core_grades: Outcomes must not be weighted when non aggregated
[moodle.git] / lib / grade / grade_category.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Definition of a class to represent a grade category
19  *
20  * @package   core_grades
21  * @copyright 2006 Nicolas Connault
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 defined('MOODLE_INTERNAL') || die();
27 require_once('grade_object.php');
29 /**
30  * grade_category is an object mapped to DB table {prefix}grade_categories
31  *
32  * @package   core_grades
33  * @category  grade
34  * @copyright 2007 Nicolas Connault
35  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
37 class grade_category extends grade_object {
38     /**
39      * The DB table.
40      * @var string $table
41      */
42     public $table = 'grade_categories';
44     /**
45      * Array of required table fields, must start with 'id'.
46      * @var array $required_fields
47      */
48     public $required_fields = array('id', 'courseid', 'parent', 'depth', 'path', 'fullname', 'aggregation',
49                                  'keephigh', 'droplow', 'aggregateonlygraded', 'aggregateoutcomes',
50                                  'timecreated', 'timemodified', 'hidden');
52     /**
53      * The course this category belongs to.
54      * @var int $courseid
55      */
56     public $courseid;
58     /**
59      * The category this category belongs to (optional).
60      * @var int $parent
61      */
62     public $parent;
64     /**
65      * The grade_category object referenced by $this->parent (PK).
66      * @var grade_category $parent_category
67      */
68     public $parent_category;
70     /**
71      * The number of parents this category has.
72      * @var int $depth
73      */
74     public $depth = 0;
76     /**
77      * Shows the hierarchical path for this category as /1/2/3/ (like course_categories), the last number being
78      * this category's autoincrement ID number.
79      * @var string $path
80      */
81     public $path;
83     /**
84      * The name of this category.
85      * @var string $fullname
86      */
87     public $fullname;
89     /**
90      * A constant pointing to one of the predefined aggregation strategies (none, mean, median, sum etc) .
91      * @var int $aggregation
92      */
93     public $aggregation = GRADE_AGGREGATE_SUM;
95     /**
96      * Keep only the X highest items.
97      * @var int $keephigh
98      */
99     public $keephigh = 0;
101     /**
102      * Drop the X lowest items.
103      * @var int $droplow
104      */
105     public $droplow = 0;
107     /**
108      * Aggregate only graded items
109      * @var int $aggregateonlygraded
110      */
111     public $aggregateonlygraded = 0;
113     /**
114      * Aggregate outcomes together with normal items
115      * @var int $aggregateoutcomes
116      */
117     public $aggregateoutcomes = 0;
119     /**
120      * Array of grade_items or grade_categories nested exactly 1 level below this category
121      * @var array $children
122      */
123     public $children;
125     /**
126      * A hierarchical array of all children below this category. This is stored separately from
127      * $children because it is more memory-intensive and may not be used as often.
128      * @var array $all_children
129      */
130     public $all_children;
132     /**
133      * An associated grade_item object, with itemtype=category, used to calculate and cache a set of grade values
134      * for this category.
135      * @var grade_item $grade_item
136      */
137     public $grade_item;
139     /**
140      * Temporary sortorder for speedup of children resorting
141      * @var int $sortorder
142      */
143     public $sortorder;
145     /**
146      * List of options which can be "forced" from site settings.
147      * @var array $forceable
148      */
149     public $forceable = array('aggregation', 'keephigh', 'droplow', 'aggregateonlygraded', 'aggregateoutcomes');
151     /**
152      * String representing the aggregation coefficient. Variable is used as cache.
153      * @var string $coefstring
154      */
155     public $coefstring = null;
157     /**
158      * Static variable storing the result from {@link self::can_apply_limit_rules}.
159      * @var bool
160      */
161     protected $canapplylimitrules;
163     /**
164      * Builds this category's path string based on its parents (if any) and its own id number.
165      * This is typically done just before inserting this object in the DB for the first time,
166      * or when a new parent is added or changed. It is a recursive function: once the calling
167      * object no longer has a parent, the path is complete.
168      *
169      * @param grade_category $grade_category A Grade_Category object
170      * @return string The category's path string
171      */
172     public static function build_path($grade_category) {
173         global $DB;
175         if (empty($grade_category->parent)) {
176             return '/'.$grade_category->id.'/';
178         } else {
179             $parent = $DB->get_record('grade_categories', array('id' => $grade_category->parent));
180             return grade_category::build_path($parent).$grade_category->id.'/';
181         }
182     }
184     /**
185      * Finds and returns a grade_category instance based on params.
186      *
187      * @param array $params associative arrays varname=>value
188      * @return grade_category The retrieved grade_category instance or false if none found.
189      */
190     public static function fetch($params) {
191         return grade_object::fetch_helper('grade_categories', 'grade_category', $params);
192     }
194     /**
195      * Finds and returns all grade_category instances based on params.
196      *
197      * @param array $params associative arrays varname=>value
198      * @return array array of grade_category insatnces or false if none found.
199      */
200     public static function fetch_all($params) {
201         return grade_object::fetch_all_helper('grade_categories', 'grade_category', $params);
202     }
204     /**
205      * In addition to update() as defined in grade_object, call force_regrading of parent categories, if applicable.
206      *
207      * @param string $source from where was the object updated (mod/forum, manual, etc.)
208      * @return bool success
209      */
210     public function update($source=null) {
211         // load the grade item or create a new one
212         $this->load_grade_item();
214         // force recalculation of path;
215         if (empty($this->path)) {
216             $this->path  = grade_category::build_path($this);
217             $this->depth = substr_count($this->path, '/') - 1;
218             $updatechildren = true;
220         } else {
221             $updatechildren = false;
222         }
224         $this->apply_forced_settings();
226         // these are exclusive
227         if ($this->droplow > 0) {
228             $this->keephigh = 0;
230         } else if ($this->keephigh > 0) {
231             $this->droplow = 0;
232         }
234         // Recalculate grades if needed
235         if ($this->qualifies_for_regrading()) {
236             $this->force_regrading();
237         }
239         $this->timemodified = time();
241         $result = parent::update($source);
243         // now update paths in all child categories
244         if ($result and $updatechildren) {
246             if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
248                 foreach ($children as $child) {
249                     $child->path  = null;
250                     $child->depth = 0;
251                     $child->update($source);
252                 }
253             }
254         }
256         return $result;
257     }
259     /**
260      * If parent::delete() is successful, send force_regrading message to parent category.
261      *
262      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
263      * @return bool success
264      */
265     public function delete($source=null) {
266         $grade_item = $this->load_grade_item();
268         if ($this->is_course_category()) {
270             if ($categories = grade_category::fetch_all(array('courseid'=>$this->courseid))) {
272                 foreach ($categories as $category) {
274                     if ($category->id == $this->id) {
275                         continue; // do not delete course category yet
276                     }
277                     $category->delete($source);
278                 }
279             }
281             if ($items = grade_item::fetch_all(array('courseid'=>$this->courseid))) {
283                 foreach ($items as $item) {
285                     if ($item->id == $grade_item->id) {
286                         continue; // do not delete course item yet
287                     }
288                     $item->delete($source);
289                 }
290             }
292         } else {
293             $this->force_regrading();
295             $parent = $this->load_parent_category();
297             // Update children's categoryid/parent field first
298             if ($children = grade_item::fetch_all(array('categoryid'=>$this->id))) {
299                 foreach ($children as $child) {
300                     $child->set_parent($parent->id);
301                 }
302             }
304             if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
305                 foreach ($children as $child) {
306                     $child->set_parent($parent->id);
307                 }
308             }
309         }
311         // first delete the attached grade item and grades
312         $grade_item->delete($source);
314         // delete category itself
315         return parent::delete($source);
316     }
318     /**
319      * In addition to the normal insert() defined in grade_object, this method sets the depth
320      * and path for this object, and update the record accordingly.
321      *
322      * We do this here instead of in the constructor as they both need to know the record's
323      * ID number, which only gets created at insertion time.
324      * This method also creates an associated grade_item if this wasn't done during construction.
325      *
326      * @param string $source from where was the object inserted (mod/forum, manual, etc.)
327      * @return int PK ID if successful, false otherwise
328      */
329     public function insert($source=null) {
331         if (empty($this->courseid)) {
332             print_error('cannotinsertgrade');
333         }
335         if (empty($this->parent)) {
336             $course_category = grade_category::fetch_course_category($this->courseid);
337             $this->parent = $course_category->id;
338         }
340         $this->path = null;
342         $this->timecreated = $this->timemodified = time();
344         if (!parent::insert($source)) {
345             debugging("Could not insert this category: " . print_r($this, true));
346             return false;
347         }
349         $this->force_regrading();
351         // build path and depth
352         $this->update($source);
354         return $this->id;
355     }
357     /**
358      * Internal function - used only from fetch_course_category()
359      * Normal insert() can not be used for course category
360      *
361      * @param int $courseid The course ID
362      * @return int The ID of the new course category
363      */
364     public function insert_course_category($courseid) {
365         $this->courseid    = $courseid;
366         $this->fullname    = '?';
367         $this->path        = null;
368         $this->parent      = null;
369         $this->aggregation = GRADE_AGGREGATE_WEIGHTED_MEAN2;
371         $this->apply_default_settings();
372         $this->apply_forced_settings();
374         $this->timecreated = $this->timemodified = time();
376         if (!parent::insert('system')) {
377             debugging("Could not insert this category: " . print_r($this, true));
378             return false;
379         }
381         // build path and depth
382         $this->update('system');
384         return $this->id;
385     }
387     /**
388      * Compares the values held by this object with those of the matching record in DB, and returns
389      * whether or not these differences are sufficient to justify an update of all parent objects.
390      * This assumes that this object has an ID number and a matching record in DB. If not, it will return false.
391      *
392      * @return bool
393      */
394     public function qualifies_for_regrading() {
395         if (empty($this->id)) {
396             debugging("Can not regrade non existing category");
397             return false;
398         }
400         $db_item = grade_category::fetch(array('id'=>$this->id));
402         $aggregationdiff = $db_item->aggregation         != $this->aggregation;
403         $keephighdiff    = $db_item->keephigh            != $this->keephigh;
404         $droplowdiff     = $db_item->droplow             != $this->droplow;
405         $aggonlygrddiff  = $db_item->aggregateonlygraded != $this->aggregateonlygraded;
406         $aggoutcomesdiff = $db_item->aggregateoutcomes   != $this->aggregateoutcomes;
408         return ($aggregationdiff || $keephighdiff || $droplowdiff || $aggonlygrddiff || $aggoutcomesdiff);
409     }
411     /**
412      * Marks this grade categories' associated grade item as needing regrading
413      */
414     public function force_regrading() {
415         $grade_item = $this->load_grade_item();
416         $grade_item->force_regrading();
417     }
419     /**
420      * Something that should be called before we start regrading the whole course.
421      *
422      * @return void
423      */
424     public function pre_regrade_final_grades() {
425         $this->auto_update_weights();
426         $this->auto_update_max();
427     }
429     /**
430      * Generates and saves final grades in associated category grade item.
431      * These immediate children must already have their own final grades.
432      * The category's aggregation method is used to generate final grades.
433      *
434      * Please note that category grade is either calculated or aggregated, not both at the same time.
435      *
436      * This method must be used ONLY from grade_item::regrade_final_grades(),
437      * because the calculation must be done in correct order!
438      *
439      * Steps to follow:
440      *  1. Get final grades from immediate children
441      *  3. Aggregate these grades
442      *  4. Save them in final grades of associated category grade item
443      *
444      * @param int $userid The user ID if final grade generation should be limited to a single user
445      * @return bool
446      */
447     public function generate_grades($userid=null) {
448         global $CFG, $DB;
450         $this->load_grade_item();
452         if ($this->grade_item->is_locked()) {
453             return true; // no need to recalculate locked items
454         }
456         // find grade items of immediate children (category or grade items) and force site settings
457         $depends_on = $this->grade_item->depends_on();
459         if (empty($depends_on)) {
460             $items = false;
462         } else {
463             list($usql, $params) = $DB->get_in_or_equal($depends_on);
464             $sql = "SELECT *
465                       FROM {grade_items}
466                      WHERE id $usql";
467             $items = $DB->get_records_sql($sql, $params);
468         }
470         $grade_inst = new grade_grade();
471         $fields = 'g.'.implode(',g.', $grade_inst->required_fields);
473         // where to look for final grades - include grade of this item too, we will store the results there
474         $gis = array_merge($depends_on, array($this->grade_item->id));
475         list($usql, $params) = $DB->get_in_or_equal($gis);
477         if ($userid) {
478             $usersql = "AND g.userid=?";
479             $params[] = $userid;
481         } else {
482             $usersql = "";
483         }
485         $sql = "SELECT $fields
486                   FROM {grade_grades} g, {grade_items} gi
487                  WHERE gi.id = g.itemid AND gi.id $usql $usersql
488               ORDER BY g.userid";
490         // group the results by userid and aggregate the grades for this user
491         $rs = $DB->get_recordset_sql($sql, $params);
492         if ($rs->valid()) {
493             $prevuser = 0;
494             $grade_values = array();
495             $excluded     = array();
496             $oldgrade     = null;
497             $grademaxoverrides = array();
498             $grademinoverrides = array();
500             foreach ($rs as $used) {
502                 if ($used->userid != $prevuser) {
503                     $this->aggregate_grades($prevuser,
504                                             $items,
505                                             $grade_values,
506                                             $oldgrade,
507                                             $excluded,
508                                             $grademinoverrides,
509                                             $grademaxoverrides);
510                     $prevuser = $used->userid;
511                     $grade_values = array();
512                     $excluded     = array();
513                     $oldgrade     = null;
514                     $grademaxoverrides = array();
515                     $grademinoverrides = array();
516                 }
517                 $grade_values[$used->itemid] = $used->finalgrade;
518                 $grademaxoverrides[$used->itemid] = $used->rawgrademax;
519                 $grademinoverrides[$used->itemid] = $used->rawgrademin;
521                 if ($used->excluded) {
522                     $excluded[] = $used->itemid;
523                 }
525                 if ($this->grade_item->id == $used->itemid) {
526                     $oldgrade = $used;
527                 }
528             }
529             $this->aggregate_grades($prevuser,
530                                     $items,
531                                     $grade_values,
532                                     $oldgrade,
533                                     $excluded,
534                                     $grademinoverrides,
535                                     $grademaxoverrides);//the last one
536         }
537         $rs->close();
539         return true;
540     }
542     /**
543      * Internal function for grade category grade aggregation
544      *
545      * @param int    $userid The User ID
546      * @param array  $items Grade items
547      * @param array  $grade_values Array of grade values
548      * @param object $oldgrade Old grade
549      * @param array  $excluded Excluded
550      * @param array  $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid)
551      * @param array  $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid)
552      */
553     private function aggregate_grades($userid,
554                                       $items,
555                                       $grade_values,
556                                       $oldgrade,
557                                       $excluded,
558                                       $grademinoverrides,
559                                       $grademaxoverrides) {
560         global $CFG, $DB;
562         // Remember these so we can set flags on them to describe how they were used in the aggregation.
563         $novalue = array();
564         $dropped = array();
565         $extracredit = array();
566         $usedweights = array();
568         if (empty($userid)) {
569             //ignore first call
570             return;
571         }
573         if ($oldgrade) {
574             $oldfinalgrade = $oldgrade->finalgrade;
575             $grade = new grade_grade($oldgrade, false);
576             $grade->grade_item =& $this->grade_item;
578         } else {
579             // insert final grade - it will be needed later anyway
580             $grade = new grade_grade(array('itemid'=>$this->grade_item->id, 'userid'=>$userid), false);
581             $grade->grade_item =& $this->grade_item;
582             $grade->insert('system');
583             $oldfinalgrade = null;
584         }
586         // no need to recalculate locked or overridden grades
587         if ($grade->is_locked() or $grade->is_overridden()) {
588             return;
589         }
591         // can not use own final category grade in calculation
592         unset($grade_values[$this->grade_item->id]);
594         // Make sure a grade_grade exists for every grade_item.
595         // We need to do this so we can set the aggregationstatus
596         // with a set_field call instead of checking if each one exists and creating/updating.
597         if (!empty($items)) {
598             list($ggsql, $params) = $DB->get_in_or_equal(array_keys($items), SQL_PARAMS_NAMED, 'g');
601             $params['userid'] = $userid;
602             $sql = "SELECT itemid
603                       FROM {grade_grades}
604                      WHERE itemid $ggsql AND userid = :userid";
605             $existingitems = $DB->get_records_sql($sql, $params);
607             $notexisting = array_diff(array_keys($items), array_keys($existingitems));
608             foreach ($notexisting as $itemid) {
609                 $gradeitem = $items[$itemid];
610                 $gradegrade = new grade_grade(array('itemid' => $itemid,
611                                                     'userid' => $userid,
612                                                     'rawgrademin' => $gradeitem->grademin,
613                                                     'rawgrademax' => $gradeitem->grademax), false);
614                 $gradegrade->grade_item = $gradeitem;
615                 $gradegrade->insert('system');
616             }
617         }
619         // if no grades calculation possible or grading not allowed clear final grade
620         if (empty($grade_values) or empty($items) or ($this->grade_item->gradetype != GRADE_TYPE_VALUE and $this->grade_item->gradetype != GRADE_TYPE_SCALE)) {
621             $grade->finalgrade = null;
623             if (!is_null($oldfinalgrade)) {
624                 $grade->timemodified = time();
625                 $success = $grade->update('aggregation');
627                 // If successful trigger a user_graded event.
628                 if ($success) {
629                     \core\event\user_graded::create_from_grade($grade)->trigger();
630                 }
631             }
632             $dropped = $grade_values;
633             $this->set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit);
634             return;
635         }
637         // Normalize the grades first - all will have value 0...1
638         // ungraded items are not used in aggregation.
639         foreach ($grade_values as $itemid=>$v) {
640             if (is_null($v)) {
641                 // If null, it means no grade.
642                 if ($this->aggregateonlygraded) {
643                     unset($grade_values[$itemid]);
644                     // Mark this item as "excluded empty" because it has no grade.
645                     $novalue[$itemid] = 0;
646                     continue;
647                 }
648             }
649             if (in_array($itemid, $excluded)) {
650                 unset($grade_values[$itemid]);
651                 $dropped[$itemid] = 0;
652                 continue;
653             }
654             // Check for user specific grade min/max overrides.
655             $usergrademin = $items[$itemid]->grademin;
656             $usergrademax = $items[$itemid]->grademax;
657             if (isset($grademinoverrides[$itemid])) {
658                 $usergrademin = $grademinoverrides[$itemid];
659             }
660             if (isset($grademaxoverrides[$itemid])) {
661                 $usergrademax = $grademaxoverrides[$itemid];
662             }
663             if ($this->aggregation == GRADE_AGGREGATE_SUM) {
664                 // Assume that the grademin is 0 when standardising the score, to preserve negative grades.
665                 $grade_values[$itemid] = grade_grade::standardise_score($v, 0, $usergrademax, 0, 1);
666             } else {
667                 $grade_values[$itemid] = grade_grade::standardise_score($v, $usergrademin, $usergrademax, 0, 1);
668             }
670         }
672         // For items with no value, and not excluded - either set their grade to 0 or exclude them.
673         foreach ($items as $itemid=>$value) {
674             if (!isset($grade_values[$itemid]) and !in_array($itemid, $excluded)) {
675                 if (!$this->aggregateonlygraded) {
676                     $grade_values[$itemid] = 0;
677                 } else {
678                     // We are specifically marking these items as "excluded empty".
679                     $novalue[$itemid] = 0;
680                 }
681             }
682         }
684         // limit and sort
685         $allvalues = $grade_values;
686         if ($this->can_apply_limit_rules()) {
687             $this->apply_limit_rules($grade_values, $items);
688         }
690         $moredropped = array_diff($allvalues, $grade_values);
691         foreach ($moredropped as $drop => $unused) {
692             $dropped[$drop] = 0;
693         }
695         foreach ($grade_values as $itemid => $val) {
696             if (self::is_extracredit_used() && ($items[$itemid]->aggregationcoef > 0)) {
697                 $extracredit[$itemid] = 0;
698             }
699         }
701         asort($grade_values, SORT_NUMERIC);
703         // let's see we have still enough grades to do any statistics
704         if (count($grade_values) == 0) {
705             // not enough attempts yet
706             $grade->finalgrade = null;
708             if (!is_null($oldfinalgrade)) {
709                 $grade->timemodified = time();
710                 $success = $grade->update('aggregation');
712                 // If successful trigger a user_graded event.
713                 if ($success) {
714                     \core\event\user_graded::create_from_grade($grade)->trigger();
715                 }
716             }
717             $this->set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit);
718             return;
719         }
721         // do the maths
722         $result = $this->aggregate_values_and_adjust_bounds($grade_values,
723                                                             $items,
724                                                             $usedweights,
725                                                             $grademinoverrides,
726                                                             $grademaxoverrides);
727         $agg_grade = $result['grade'];
729         // Set the actual grademin and max to bind the grade properly.
730         $this->grade_item->grademin = $result['grademin'];
731         $this->grade_item->grademax = $result['grademax'];
733         if ($this->aggregation == GRADE_AGGREGATE_SUM) {
734             // The natural aggregation always displays the range as coming from 0 for categories.
735             // However, when we bind the grade we allow for negative values.
736             $result['grademin'] = 0;
737         }
739         // Recalculate the grade back to requested range.
740         $finalgrade = grade_grade::standardise_score($agg_grade, 0, 1, $result['grademin'], $result['grademax']);
741         $grade->finalgrade = $this->grade_item->bounded_grade($finalgrade);
743         $oldrawgrademin = $grade->rawgrademin;
744         $oldrawgrademax = $grade->rawgrademax;
745         $grade->rawgrademin = $result['grademin'];
746         $grade->rawgrademax = $result['grademax'];
748         // Update in db if changed.
749         if (grade_floats_different($grade->finalgrade, $oldfinalgrade) ||
750                 grade_floats_different($grade->rawgrademax, $oldrawgrademax) ||
751                 grade_floats_different($grade->rawgrademin, $oldrawgrademin)) {
752             $grade->timemodified = time();
753             $success = $grade->update('aggregation');
755             // If successful trigger a user_graded event.
756             if ($success) {
757                 \core\event\user_graded::create_from_grade($grade)->trigger();
758             }
759         }
761         $this->set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit);
763         return;
764     }
766     /**
767      * Set the flags on the grade_grade items to indicate how individual grades are used
768      * in the aggregation.
769      *
770      * @param int $userid The user we have aggregated the grades for.
771      * @param array $usedweights An array with keys for each of the grade_item columns included in the aggregation. The value are the relative weight.
772      * @param array $novalue An array with keys for each of the grade_item columns skipped because
773      *                       they had no value in the aggregation.
774      * @param array $dropped An array with keys for each of the grade_item columns dropped
775      *                       because of any drop lowest/highest settings in the aggregation.
776      * @param array $extracredit An array with keys for each of the grade_item columns
777      *                       considered extra credit by the aggregation.
778      */
779     private function set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit) {
780         global $DB;
782         // Included.
783         if (!empty($usedweights)) {
784             // The usedweights items are updated individually to record the weights.
785             foreach ($usedweights as $gradeitemid => $contribution) {
786                 $DB->set_field_select('grade_grades',
787                                       'aggregationweight',
788                                       $contribution,
789                                       "itemid = :itemid AND userid = :userid",
790                                       array('itemid'=>$gradeitemid, 'userid'=>$userid));
791             }
793             // Now set the status flag for all these weights.
794             list($itemsql, $itemlist) = $DB->get_in_or_equal(array_keys($usedweights), SQL_PARAMS_NAMED, 'g');
795             $itemlist['userid'] = $userid;
797             $DB->set_field_select('grade_grades',
798                                   'aggregationstatus',
799                                   'used',
800                                   "itemid $itemsql AND userid = :userid",
801                                   $itemlist);
802         }
804         // No value.
805         if (!empty($novalue)) {
806             list($itemsql, $itemlist) = $DB->get_in_or_equal(array_keys($novalue), SQL_PARAMS_NAMED, 'g');
808             $itemlist['userid'] = $userid;
810             $DB->set_field_select('grade_grades',
811                                   'aggregationstatus',
812                                   'novalue',
813                                   "itemid $itemsql AND userid = :userid",
814                                   $itemlist);
815         }
817         // Dropped.
818         if (!empty($dropped)) {
819             list($itemsql, $itemlist) = $DB->get_in_or_equal(array_keys($dropped), SQL_PARAMS_NAMED, 'g');
821             $itemlist['userid'] = $userid;
823             $DB->set_field_select('grade_grades',
824                                   'aggregationstatus',
825                                   'dropped',
826                                   "itemid $itemsql AND userid = :userid",
827                                   $itemlist);
828         }
829         // Extra credit.
830         if (!empty($extracredit)) {
831             list($itemsql, $itemlist) = $DB->get_in_or_equal(array_keys($extracredit), SQL_PARAMS_NAMED, 'g');
833             $itemlist['userid'] = $userid;
835             $DB->set_field_select('grade_grades',
836                                   'aggregationstatus',
837                                   'extra',
838                                   "itemid $itemsql AND userid = :userid",
839                                   $itemlist);
840         }
841     }
843     /**
844      * Internal function that calculates the aggregated grade and new min/max for this grade category
845      *
846      * Must be public as it is used by grade_grade::get_hiding_affected()
847      *
848      * @param array $grade_values An array of values to be aggregated
849      * @param array $items The array of grade_items
850      * @since Moodle 2.6.5, 2.7.2
851      * @param array & $weights If provided, will be filled with the normalized weights
852      *                         for each grade_item as used in the aggregation.
853      *                         Some rules for the weights are:
854      *                         1. The weights must add up to 1 (unless there are extra credit)
855      *                         2. The contributed points column must add up to the course
856      *                         final grade and this column is calculated from these weights.
857      * @param array  $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid)
858      * @param array  $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid)
859      * @return array containing values for:
860      *                'grade' => the new calculated grade
861      *                'grademin' => the new calculated min grade for the category
862      *                'grademax' => the new calculated max grade for the category
863      */
864     public function aggregate_values_and_adjust_bounds($grade_values,
865                                                        $items,
866                                                        & $weights = null,
867                                                        $grademinoverrides = array(),
868                                                        $grademaxoverrides = array()) {
869         $category_item = $this->get_grade_item();
870         $grademin = $category_item->grademin;
871         $grademax = $category_item->grademax;
873         switch ($this->aggregation) {
875             case GRADE_AGGREGATE_MEDIAN: // Middle point value in the set: ignores frequencies
876                 $num = count($grade_values);
877                 $grades = array_values($grade_values);
879                 // The median gets 100% - others get 0.
880                 if ($weights !== null && $num > 0) {
881                     $count = 0;
882                     foreach ($grade_values as $itemid=>$grade_value) {
883                         if (($num % 2 == 0) && ($count == intval($num/2)-1 || $count == intval($num/2))) {
884                             $weights[$itemid] = 0.5;
885                         } else if (($num % 2 != 0) && ($count == intval(($num/2)-0.5))) {
886                             $weights[$itemid] = 1.0;
887                         } else {
888                             $weights[$itemid] = 0;
889                         }
890                         $count++;
891                     }
892                 }
893                 if ($num % 2 == 0) {
894                     $agg_grade = ($grades[intval($num/2)-1] + $grades[intval($num/2)]) / 2;
895                 } else {
896                     $agg_grade = $grades[intval(($num/2)-0.5)];
897                 }
899                 break;
901             case GRADE_AGGREGATE_MIN:
902                 $agg_grade = reset($grade_values);
903                 // Record the weights as used.
904                 if ($weights !== null) {
905                     foreach ($grade_values as $itemid=>$grade_value) {
906                         $weights[$itemid] = 0;
907                     }
908                 }
909                 // Set the first item to 1.
910                 $itemids = array_keys($grade_values);
911                 $weights[reset($itemids)] = 1;
912                 break;
914             case GRADE_AGGREGATE_MAX:
915                 // Record the weights as used.
916                 if ($weights !== null) {
917                     foreach ($grade_values as $itemid=>$grade_value) {
918                         $weights[$itemid] = 0;
919                     }
920                 }
921                 // Set the last item to 1.
922                 $itemids = array_keys($grade_values);
923                 $weights[end($itemids)] = 1;
924                 $agg_grade = end($grade_values);
925                 break;
927             case GRADE_AGGREGATE_MODE:       // the most common value
928                 // array_count_values only counts INT and STRING, so if grades are floats we must convert them to string
929                 $converted_grade_values = array();
931                 foreach ($grade_values as $k => $gv) {
933                     if (!is_int($gv) && !is_string($gv)) {
934                         $converted_grade_values[$k] = (string) $gv;
936                     } else {
937                         $converted_grade_values[$k] = $gv;
938                     }
939                     if ($weights !== null) {
940                         $weights[$k] = 0;
941                     }
942                 }
944                 $freq = array_count_values($converted_grade_values);
945                 arsort($freq);                      // sort by frequency keeping keys
946                 $top = reset($freq);               // highest frequency count
947                 $modes = array_keys($freq, $top);  // search for all modes (have the same highest count)
948                 rsort($modes, SORT_NUMERIC);       // get highest mode
949                 $agg_grade = reset($modes);
950                 // Record the weights as used.
951                 if ($weights !== null && $top > 0) {
952                     foreach ($grade_values as $k => $gv) {
953                         if ($gv == $agg_grade) {
954                             $weights[$k] = 1.0 / $top;
955                         }
956                     }
957                 }
958                 break;
960             case GRADE_AGGREGATE_WEIGHTED_MEAN: // Weighted average of all existing final grades, weight specified in coef
961                 $weightsum = 0;
962                 $sum       = 0;
964                 foreach ($grade_values as $itemid=>$grade_value) {
965                     if ($weights !== null) {
966                         $weights[$itemid] = $items[$itemid]->aggregationcoef;
967                     }
968                     if ($items[$itemid]->aggregationcoef <= 0) {
969                         continue;
970                     }
971                     $weightsum += $items[$itemid]->aggregationcoef;
972                     $sum       += $items[$itemid]->aggregationcoef * $grade_value;
973                 }
974                 if ($weightsum == 0) {
975                     $agg_grade = null;
977                 } else {
978                     $agg_grade = $sum / $weightsum;
979                     if ($weights !== null) {
980                         // Normalise the weights.
981                         foreach ($weights as $itemid => $weight) {
982                             $weights[$itemid] = $weight / $weightsum;
983                         }
984                     }
986                 }
987                 break;
989             case GRADE_AGGREGATE_WEIGHTED_MEAN2:
990                 // Weighted average of all existing final grades with optional extra credit flag,
991                 // weight is the range of grade (usually grademax)
992                 $this->load_grade_item();
993                 $weightsum = 0;
994                 $sum       = null;
996                 foreach ($grade_values as $itemid=>$grade_value) {
997                     if ($items[$itemid]->aggregationcoef > 0) {
998                         continue;
999                     }
1001                     $weight = $items[$itemid]->grademax - $items[$itemid]->grademin;
1002                     if ($weight <= 0) {
1003                         continue;
1004                     }
1006                     $weightsum += $weight;
1007                     $sum += $weight * $grade_value;
1008                 }
1010                 // Handle the extra credit items separately to calculate their weight accurately.
1011                 foreach ($grade_values as $itemid => $grade_value) {
1012                     if ($items[$itemid]->aggregationcoef <= 0) {
1013                         continue;
1014                     }
1016                     $weight = $items[$itemid]->grademax - $items[$itemid]->grademin;
1017                     if ($weight <= 0) {
1018                         $weights[$itemid] = 0;
1019                         continue;
1020                     }
1022                     $oldsum = $sum;
1023                     $weightedgrade = $weight * $grade_value;
1024                     $sum += $weightedgrade;
1026                     if ($weights !== null) {
1027                         if ($weightsum <= 0) {
1028                             $weights[$itemid] = 0;
1029                             continue;
1030                         }
1032                         $oldgrade = $oldsum / $weightsum;
1033                         $grade = $sum / $weightsum;
1034                         $normoldgrade = grade_grade::standardise_score($oldgrade, 0, 1, $grademin, $grademax);
1035                         $normgrade = grade_grade::standardise_score($grade, 0, 1, $grademin, $grademax);
1036                         $boundedoldgrade = $this->grade_item->bounded_grade($normoldgrade);
1037                         $boundedgrade = $this->grade_item->bounded_grade($normgrade);
1039                         if ($boundedgrade - $boundedoldgrade <= 0) {
1040                             // Nothing new was added to the grade.
1041                             $weights[$itemid] = 0;
1042                         } else if ($boundedgrade < $normgrade) {
1043                             // The grade has been bounded, the extra credit item needs to have a different weight.
1044                             $gradediff = $boundedgrade - $normoldgrade;
1045                             $gradediffnorm = grade_grade::standardise_score($gradediff, $grademin, $grademax, 0, 1);
1046                             $weights[$itemid] = $gradediffnorm / $grade_value;
1047                         } else {
1048                             // Default weighting.
1049                             $weights[$itemid] = $weight / $weightsum;
1050                         }
1051                     }
1052                 }
1054                 if ($weightsum == 0) {
1055                     $agg_grade = $sum; // only extra credits
1057                 } else {
1058                     $agg_grade = $sum / $weightsum;
1059                 }
1061                 // Record the weights as used.
1062                 if ($weights !== null) {
1063                     foreach ($grade_values as $itemid=>$grade_value) {
1064                         if ($items[$itemid]->aggregationcoef > 0) {
1065                             // Ignore extra credit items, the weights have already been computed.
1066                             continue;
1067                         }
1068                         if ($weightsum > 0) {
1069                             $weight = $items[$itemid]->grademax - $items[$itemid]->grademin;
1070                             $weights[$itemid] = $weight / $weightsum;
1071                         } else {
1072                             $weights[$itemid] = 0;
1073                         }
1074                     }
1075                 }
1076                 break;
1078             case GRADE_AGGREGATE_EXTRACREDIT_MEAN: // special average
1079                 $this->load_grade_item();
1080                 $num = 0;
1081                 $sum = null;
1083                 foreach ($grade_values as $itemid=>$grade_value) {
1084                     if ($items[$itemid]->aggregationcoef == 0) {
1085                         $num += 1;
1086                         $sum += $grade_value;
1087                         if ($weights !== null) {
1088                             $weights[$itemid] = 1;
1089                         }
1090                     }
1091                 }
1093                 // Treating the extra credit items separately to get a chance to calculate their effective weights.
1094                 foreach ($grade_values as $itemid=>$grade_value) {
1095                     if ($items[$itemid]->aggregationcoef > 0) {
1096                         $oldsum = $sum;
1097                         $sum += $items[$itemid]->aggregationcoef * $grade_value;
1099                         if ($weights !== null) {
1100                             if ($num <= 0) {
1101                                 // The category only contains extra credit items, not setting the weight.
1102                                 continue;
1103                             }
1105                             $oldgrade = $oldsum / $num;
1106                             $grade = $sum / $num;
1107                             $normoldgrade = grade_grade::standardise_score($oldgrade, 0, 1, $grademin, $grademax);
1108                             $normgrade = grade_grade::standardise_score($grade, 0, 1, $grademin, $grademax);
1109                             $boundedoldgrade = $this->grade_item->bounded_grade($normoldgrade);
1110                             $boundedgrade = $this->grade_item->bounded_grade($normgrade);
1112                             if ($boundedgrade - $boundedoldgrade <= 0) {
1113                                 // Nothing new was added to the grade.
1114                                 $weights[$itemid] = 0;
1115                             } else if ($boundedgrade < $normgrade) {
1116                                 // The grade has been bounded, the extra credit item needs to have a different weight.
1117                                 $gradediff = $boundedgrade - $normoldgrade;
1118                                 $gradediffnorm = grade_grade::standardise_score($gradediff, $grademin, $grademax, 0, 1);
1119                                 $weights[$itemid] = $gradediffnorm / $grade_value;
1120                             } else {
1121                                 // Default weighting.
1122                                 $weights[$itemid] = 1.0 / $num;
1123                             }
1124                         }
1125                     }
1126                 }
1128                 if ($weights !== null && $num > 0) {
1129                     foreach ($grade_values as $itemid=>$grade_value) {
1130                         if ($items[$itemid]->aggregationcoef > 0) {
1131                             // Extra credit weights were already calculated.
1132                             continue;
1133                         }
1134                         if ($weights[$itemid]) {
1135                             $weights[$itemid] = 1.0 / $num;
1136                         }
1137                     }
1138                 }
1140                 if ($num == 0) {
1141                     $agg_grade = $sum; // only extra credits or wrong coefs
1143                 } else {
1144                     $agg_grade = $sum / $num;
1145                 }
1147                 break;
1149             case GRADE_AGGREGATE_SUM:    // Add up all the items.
1150                 $this->load_grade_item();
1151                 $num = count($grade_values);
1152                 $sum = 0;
1153                 $sumweights = 0;
1154                 $grademin = 0;
1155                 $grademax = 0;
1156                 $extracredititems = array();
1157                 foreach ($grade_values as $itemid => $gradevalue) {
1158                     // We need to check if the grademax/min was adjusted per user because of excluded items.
1159                     $usergrademin = $items[$itemid]->grademin;
1160                     $usergrademax = $items[$itemid]->grademax;
1161                     if (isset($grademinoverrides[$itemid])) {
1162                         $usergrademin = $grademinoverrides[$itemid];
1163                     }
1164                     if (isset($grademaxoverrides[$itemid])) {
1165                         $usergrademax = $grademaxoverrides[$itemid];
1166                     }
1168                     // Keep track of the extra credit items, we will need them later on.
1169                     if ($items[$itemid]->aggregationcoef > 0) {
1170                         $extracredititems[$itemid] = $items[$itemid];
1171                     }
1173                     // Ignore extra credit and items with a weight of 0.
1174                     if (!isset($extracredititems[$itemid]) && $items[$itemid]->aggregationcoef2 > 0) {
1175                         $grademin += $usergrademin;
1176                         $grademax += $usergrademax;
1177                         $sumweights += $items[$itemid]->aggregationcoef2;
1178                     }
1179                 }
1180                 $userweights = array();
1181                 $totaloverriddenweight = 0;
1182                 $totaloverriddengrademax = 0;
1183                 // We first need to rescale all manually assigned weights down by the
1184                 // percentage of weights missing from the category.
1185                 foreach ($grade_values as $itemid => $gradevalue) {
1186                     if ($items[$itemid]->weightoverride) {
1187                         if ($items[$itemid]->aggregationcoef2 <= 0) {
1188                             // Records the weight of 0 and continue.
1189                             $userweights[$itemid] = 0;
1190                             continue;
1191                         }
1192                         $userweights[$itemid] = $items[$itemid]->aggregationcoef2 / $sumweights;
1193                         $totaloverriddenweight += $userweights[$itemid];
1194                         $usergrademax = $items[$itemid]->grademax;
1195                         if (isset($grademaxoverrides[$itemid])) {
1196                             $usergrademax = $grademaxoverrides[$itemid];
1197                         }
1198                         $totaloverriddengrademax += $usergrademax;
1199                     }
1200                 }
1201                 $nonoverriddenpoints = $grademax - $totaloverriddengrademax;
1203                 // Then we need to recalculate the automatic weights.
1204                 foreach ($grade_values as $itemid => $gradevalue) {
1205                     if (!$items[$itemid]->weightoverride) {
1206                         $usergrademax = $items[$itemid]->grademax;
1207                         if (isset($grademaxoverrides[$itemid])) {
1208                             $usergrademax = $grademaxoverrides[$itemid];
1209                         }
1210                         if ($nonoverriddenpoints > 0) {
1211                             $userweights[$itemid] = ($usergrademax/$nonoverriddenpoints) * (1 - $totaloverriddenweight);
1212                         } else {
1213                             $userweights[$itemid] = 0;
1214                             if ($items[$itemid]->aggregationcoef2 > 0) {
1215                                 // Items with a weight of 0 should not count for the grade max,
1216                                 // though this only applies if the weight was changed to 0.
1217                                 $grademax -= $usergrademax;
1218                             }
1219                         }
1220                     }
1221                 }
1223                 // We can use our freshly corrected weights below.
1224                 foreach ($grade_values as $itemid => $gradevalue) {
1225                     if (isset($extracredititems[$itemid])) {
1226                         // We skip the extra credit items first.
1227                         continue;
1228                     }
1229                     $sum += $gradevalue * $userweights[$itemid] * $grademax;
1230                     if ($weights !== null) {
1231                         $weights[$itemid] = $userweights[$itemid];
1232                     }
1233                 }
1235                 // No we proceed with the extra credit items. They might have a different final
1236                 // weight in case the final grade was bounded. So we need to treat them different.
1237                 // Also, as we need to use the bounded_grade() method, we have to inject the
1238                 // right values there, and restore them afterwards.
1239                 $oldgrademax = $this->grade_item->grademax;
1240                 $oldgrademin = $this->grade_item->grademin;
1241                 foreach ($grade_values as $itemid => $gradevalue) {
1242                     if (!isset($extracredititems[$itemid])) {
1243                         continue;
1244                     }
1245                     $oldsum = $sum;
1246                     $weightedgrade = $gradevalue * $userweights[$itemid] * $grademax;
1247                     $sum += $weightedgrade;
1249                     // Only go through this when we need to record the weights.
1250                     if ($weights !== null) {
1251                         if ($grademax <= 0) {
1252                             // There are only extra credit items in this category,
1253                             // all the weights should be accurate (and be 0).
1254                             $weights[$itemid] = $userweights[$itemid];
1255                             continue;
1256                         }
1258                         $oldfinalgrade = $this->grade_item->bounded_grade($oldsum);
1259                         $newfinalgrade = $this->grade_item->bounded_grade($sum);
1260                         $finalgradediff = $newfinalgrade - $oldfinalgrade;
1261                         if ($finalgradediff <= 0) {
1262                             // This item did not contribute to the category total at all.
1263                             $weights[$itemid] = 0;
1264                         } else if ($finalgradediff < $weightedgrade) {
1265                             // The weight needs to be adjusted because only a portion of the
1266                             // extra credit item contributed to the category total.
1267                             $weights[$itemid] = $finalgradediff / ($gradevalue * $grademax);
1268                         } else {
1269                             // The weight was accurate.
1270                             $weights[$itemid] = $userweights[$itemid];
1271                         }
1272                     }
1273                 }
1274                 $this->grade_item->grademax = $oldgrademax;
1275                 $this->grade_item->grademin = $oldgrademin;
1277                 if ($grademax > 0) {
1278                     $agg_grade = $sum / $grademax; // Re-normalize score.
1279                 } else {
1280                     // Every item in the category is extra credit.
1281                     $agg_grade = $sum;
1282                     $grademax = $sum;
1283                 }
1285                 break;
1287             case GRADE_AGGREGATE_MEAN:    // Arithmetic average of all grade items (if ungraded aggregated, NULL counted as minimum)
1288             default:
1289                 $num = count($grade_values);
1290                 $sum = array_sum($grade_values);
1291                 $agg_grade = $sum / $num;
1292                 // Record the weights evenly.
1293                 if ($weights !== null && $num > 0) {
1294                     foreach ($grade_values as $itemid=>$grade_value) {
1295                         $weights[$itemid] = 1.0 / $num;
1296                     }
1297                 }
1298                 break;
1299         }
1301         return array('grade' => $agg_grade, 'grademin' => $grademin, 'grademax' => $grademax);
1302     }
1304     /**
1305      * Internal function that calculates the aggregated grade for this grade category
1306      *
1307      * Must be public as it is used by grade_grade::get_hiding_affected()
1308      *
1309      * @deprecated since Moodle 2.8
1310      * @param array $grade_values An array of values to be aggregated
1311      * @param array $items The array of grade_items
1312      * @return float The aggregate grade for this grade category
1313      */
1314     public function aggregate_values($grade_values, $items) {
1315         debugging('grade_category::aggregate_values() is deprecated.
1316                    Call grade_category::aggregate_values_and_adjust_bounds() instead.', DEBUG_DEVELOPER);
1317         $result = $this->aggregate_values_and_adjust_bounds($grade_values, $items);
1318         return $result['grade'];
1319     }
1321     /**
1322      * Some aggregation types may need to update their max grade.
1323      *
1324      * This must be executed after updating the weights as it relies on them.
1325      *
1326      * @return void
1327      */
1328     private function auto_update_max() {
1329         global $DB;
1330         if ($this->aggregation != GRADE_AGGREGATE_SUM) {
1331             // not needed at all
1332             return;
1333         }
1335         // Find grade items of immediate children (category or grade items) and force site settings.
1336         $this->load_grade_item();
1337         $depends_on = $this->grade_item->depends_on();
1339         $items = false;
1340         if (!empty($depends_on)) {
1341             list($usql, $params) = $DB->get_in_or_equal($depends_on);
1342             $sql = "SELECT *
1343                       FROM {grade_items}
1344                      WHERE id $usql";
1345             $items = $DB->get_records_sql($sql, $params);
1346         }
1348         if (!$items) {
1350             if ($this->grade_item->grademax != 0 or $this->grade_item->gradetype != GRADE_TYPE_VALUE) {
1351                 $this->grade_item->grademax  = 0;
1352                 $this->grade_item->grademin  = 0;
1353                 $this->grade_item->gradetype = GRADE_TYPE_VALUE;
1354                 $this->grade_item->update('aggregation');
1355             }
1356             return;
1357         }
1359         //find max grade possible
1360         $maxes = array();
1362         foreach ($items as $item) {
1364             if ($item->aggregationcoef > 0) {
1365                 // extra credit from this activity - does not affect total
1366                 continue;
1367             } else if ($item->aggregationcoef2 <= 0) {
1368                 // Items with a weight of 0 do not affect the total.
1369                 continue;
1370             }
1372             if ($item->gradetype == GRADE_TYPE_VALUE) {
1373                 $maxes[$item->id] = $item->grademax;
1375             } else if ($item->gradetype == GRADE_TYPE_SCALE) {
1376                 $maxes[$item->id] = $item->grademax; // 0 = nograde, 1 = first scale item, 2 = second scale item
1377             }
1378         }
1380         if ($this->can_apply_limit_rules()) {
1381             // Apply droplow and keephigh.
1382             $this->apply_limit_rules($maxes, $items);
1383         }
1384         $max = array_sum($maxes);
1386         // update db if anything changed
1387         if ($this->grade_item->grademax != $max or $this->grade_item->grademin != 0 or $this->grade_item->gradetype != GRADE_TYPE_VALUE) {
1388             $this->grade_item->grademax  = $max;
1389             $this->grade_item->grademin  = 0;
1390             $this->grade_item->gradetype = GRADE_TYPE_VALUE;
1391             $this->grade_item->update('aggregation');
1392         }
1393     }
1395     /**
1396      * Recalculate the weights of the grade items in this category.
1397      *
1398      * The category total is not updated here, a further call to
1399      * {@link self::auto_update_max()} is required.
1400      *
1401      * @return void
1402      */
1403     private function auto_update_weights() {
1404         if ($this->aggregation != GRADE_AGGREGATE_SUM) {
1405             // This is only required if we are using natural weights.
1406             return;
1407         }
1408         $children = $this->get_children();
1410         $gradeitem = null;
1412         // Calculate the sum of the grademax's of all the items within this category.
1413         $totalnonoverriddengrademax = 0;
1414         $totalgrademax = 0;
1416         // Out of 1, how much weight has been manually overriden by a user?
1417         $totaloverriddenweight  = 0;
1418         $totaloverriddengrademax  = 0;
1420         // Has every assessment in this category been overridden?
1421         $automaticgradeitemspresent = false;
1422         // Does the grade item require normalising?
1423         $requiresnormalising = false;
1425         // This array keeps track of the id and weight of every grade item that has been overridden.
1426         $overridearray = array();
1427         foreach ($children as $sortorder => $child) {
1428             $gradeitem = null;
1430             if ($child['type'] == 'item') {
1431                 $gradeitem = $child['object'];
1432             } else if ($child['type'] == 'category') {
1433                 $gradeitem = $child['object']->load_grade_item();
1434             }
1436             if ($gradeitem->gradetype == GRADE_TYPE_NONE || $gradeitem->gradetype == GRADE_TYPE_TEXT) {
1437                 // Text items and none items do not have a weight.
1438                 continue;
1439             } else if (!$this->aggregateoutcomes && $gradeitem->is_outcome_item()) {
1440                 // We will not aggregate outcome items, so we can ignore them.
1441                 continue;
1442             }
1444             // Record the ID and the weight for this grade item.
1445             $overridearray[$gradeitem->id] = array();
1446             $overridearray[$gradeitem->id]['extracredit'] = intval($gradeitem->aggregationcoef);
1447             $overridearray[$gradeitem->id]['weight'] = $gradeitem->aggregationcoef2;
1448             $overridearray[$gradeitem->id]['weightoverride'] = intval($gradeitem->weightoverride);
1449             // If this item has had its weight overridden then set the flag to true, but
1450             // only if all previous items were also overridden. Note that extra credit items
1451             // are counted as overridden grade items.
1452             if (!$gradeitem->weightoverride && $gradeitem->aggregationcoef == 0) {
1453                 $automaticgradeitemspresent = true;
1454             }
1456             if ($gradeitem->aggregationcoef > 0) {
1457                 // An extra credit grade item doesn't contribute to $totaloverriddengrademax.
1458                 continue;
1459             } else if ($gradeitem->weightoverride > 0 && $gradeitem->aggregationcoef2 <= 0) {
1460                 // An overriden item that defines a weight of 0 does not contribute to $totaloverriddengrademax.
1461                 continue;
1462             }
1464             $totalgrademax += $gradeitem->grademax;
1465             if ($gradeitem->weightoverride > 0) {
1466                 $totaloverriddenweight += $gradeitem->aggregationcoef2;
1467                 $totaloverriddengrademax += $gradeitem->grademax;
1468             }
1469         }
1471         // Initialise this variable (used to keep track of the weight override total).
1472         $normalisetotal = 0;
1473         // Keep a record of how much the override total is to see if it is above 100. It it is then we need to set the
1474         // other weights to zero and normalise the others.
1475         $overriddentotal = 0;
1476         // If the overridden weight total is higher than 1 then set the other untouched weights to zero.
1477         $setotherweightstozero = false;
1478         // Total up all of the weights.
1479         foreach ($overridearray as $gradeitemdetail) {
1480             // If the grade item has extra credit, then don't add it to the normalisetotal.
1481             if (!$gradeitemdetail['extracredit']) {
1482                 $normalisetotal += $gradeitemdetail['weight'];
1483             }
1484             if ($gradeitemdetail['weightoverride'] && !$gradeitemdetail['extracredit']) {
1485                 // Add overriden weights up to see if they are greater than 1.
1486                 $overriddentotal += $gradeitemdetail['weight'];
1487             }
1488         }
1489         if ($overriddentotal > 1) {
1490             // Make sure that this catergory of weights gets normalised.
1491             $requiresnormalising = true;
1492             // The normalised weights are only the overridden weights, so we just use the total of those.
1493             $normalisetotal = $overriddentotal;
1494         }
1496         $totalnonoverriddengrademax = $totalgrademax - $totaloverriddengrademax;
1498         reset($children);
1499         foreach ($children as $sortorder => $child) {
1500             $gradeitem = null;
1502             if ($child['type'] == 'item') {
1503                 $gradeitem = $child['object'];
1504             } else if ($child['type'] == 'category') {
1505                 $gradeitem = $child['object']->load_grade_item();
1506             }
1508             if ($gradeitem->gradetype == GRADE_TYPE_NONE || $gradeitem->gradetype == GRADE_TYPE_TEXT) {
1509                 // Text items and none items do not have a weight, no need to set their weight to
1510                 // zero as they must never be used during aggregation.
1511                 continue;
1512             } else if (!$this->aggregateoutcomes && $gradeitem->is_outcome_item()) {
1513                 // We will not aggregate outcome items, so we can ignore updating their weights.
1514                 continue;
1515             }
1517             if (!$gradeitem->weightoverride) {
1518                 // Calculations with a grade maximum of zero will cause problems. Just set the weight to zero.
1519                 if ($totaloverriddenweight >= 1 || $totalnonoverriddengrademax == 0 || $gradeitem->grademax == 0) {
1520                     // There is no more weight to distribute.
1521                     $gradeitem->aggregationcoef2 = 0;
1522                 } else {
1523                     // Calculate this item's weight as a percentage of the non-overridden total grade maxes
1524                     // then convert it to a proportion of the available non-overriden weight.
1525                     $gradeitem->aggregationcoef2 = ($gradeitem->grademax/$totalnonoverriddengrademax) *
1526                             (1 - $totaloverriddenweight);
1527                 }
1528                 $gradeitem->update();
1529             } else if ((!$automaticgradeitemspresent && $normalisetotal != 1) || ($requiresnormalising)
1530                     || $overridearray[$gradeitem->id]['weight'] < 0) {
1531                 // Just divide the overriden weight for this item against the total weight override of all
1532                 // items in this category.
1533                 if ($normalisetotal == 0 || $overridearray[$gradeitem->id]['weight'] < 0) {
1534                     // If the normalised total equals zero, or the weight value is less than zero,
1535                     // set the weight for the grade item to zero.
1536                     $gradeitem->aggregationcoef2 = 0;
1537                 } else {
1538                     $gradeitem->aggregationcoef2 = $overridearray[$gradeitem->id]['weight'] / $normalisetotal;
1539                 }
1540                 // Update the grade item to reflect these changes.
1541                 $gradeitem->update();
1542             }
1543         }
1544     }
1546     /**
1547      * Given an array of grade values (numerical indices) applies droplow or keephigh rules to limit the final array.
1548      *
1549      * @param array $grade_values itemid=>$grade_value float
1550      * @param array $items grade item objects
1551      * @return array Limited grades.
1552      */
1553     public function apply_limit_rules(&$grade_values, $items) {
1554         $extraused = $this->is_extracredit_used();
1556         if (!empty($this->droplow)) {
1557             asort($grade_values, SORT_NUMERIC);
1558             $dropped = 0;
1560             // If we have fewer grade items available to drop than $this->droplow, use this flag to escape the loop
1561             // May occur because of "extra credit" or if droplow is higher than the number of grade items
1562             $droppedsomething = true;
1564             while ($dropped < $this->droplow && $droppedsomething) {
1565                 $droppedsomething = false;
1567                 $grade_keys = array_keys($grade_values);
1568                 $gradekeycount = count($grade_keys);
1570                 if ($gradekeycount === 0) {
1571                     //We've dropped all grade items
1572                     break;
1573                 }
1575                 $originalindex = $founditemid = $foundmax = null;
1577                 // Find the first remaining grade item that is available to be dropped
1578                 foreach ($grade_keys as $gradekeyindex=>$gradekey) {
1579                     if (!$extraused || $items[$gradekey]->aggregationcoef <= 0) {
1580                         // Found a non-extra credit grade item that is eligible to be dropped
1581                         $originalindex = $gradekeyindex;
1582                         $founditemid = $grade_keys[$originalindex];
1583                         $foundmax = $items[$founditemid]->grademax;
1584                         break;
1585                     }
1586                 }
1588                 if (empty($founditemid)) {
1589                     // No grade items available to drop
1590                     break;
1591                 }
1593                 // Now iterate over the remaining grade items
1594                 // We're looking for other grade items with the same grade value but a higher grademax
1595                 $i = 1;
1596                 while ($originalindex + $i < $gradekeycount) {
1598                     $possibleitemid = $grade_keys[$originalindex+$i];
1599                     $i++;
1601                     if ($grade_values[$founditemid] != $grade_values[$possibleitemid]) {
1602                         // The next grade item has a different grade value. Stop looking.
1603                         break;
1604                     }
1606                     if ($extraused && $items[$possibleitemid]->aggregationcoef > 0) {
1607                         // Don't drop extra credit grade items. Continue the search.
1608                         continue;
1609                     }
1611                     if ($foundmax < $items[$possibleitemid]->grademax) {
1612                         // Found a grade item with the same grade value and a higher grademax
1613                         $foundmax = $items[$possibleitemid]->grademax;
1614                         $founditemid = $possibleitemid;
1615                         // Continue searching to see if there is an even higher grademax
1616                     }
1617                 }
1619                 // Now drop whatever grade item we have found
1620                 unset($grade_values[$founditemid]);
1621                 $dropped++;
1622                 $droppedsomething = true;
1623             }
1625         } else if (!empty($this->keephigh)) {
1626             arsort($grade_values, SORT_NUMERIC);
1627             $kept = 0;
1629             foreach ($grade_values as $itemid=>$value) {
1631                 if ($extraused and $items[$itemid]->aggregationcoef > 0) {
1632                     // we keep all extra credits
1634                 } else if ($kept < $this->keephigh) {
1635                     $kept++;
1637                 } else {
1638                     unset($grade_values[$itemid]);
1639                 }
1640             }
1641         }
1642     }
1644     /**
1645      * Returns whether or not we can apply the limit rules.
1646      *
1647      * There are cases where drop lowest or keep highest should not be used
1648      * at all. This method will determine whether or not this logic can be
1649      * applied considering the current setup of the category.
1650      *
1651      * @return bool
1652      */
1653     public function can_apply_limit_rules() {
1654         if ($this->canapplylimitrules !== null) {
1655             return $this->canapplylimitrules;
1656         }
1658         // Set it to be supported by default.
1659         $this->canapplylimitrules = true;
1661         // Natural aggregation.
1662         if ($this->aggregation == GRADE_AGGREGATE_SUM) {
1663             $canapply = true;
1665             // Check until one child breaks the rules.
1666             $gradeitems = $this->get_children();
1667             $validitems = 0;
1668             $lastweight = null;
1669             $lastmaxgrade = null;
1670             foreach ($gradeitems as $gradeitem) {
1671                 $gi = $gradeitem['object'];
1673                 if ($gradeitem['type'] == 'category') {
1674                     // Sub categories are not allowed because they can have dynamic weights/maxgrades.
1675                     $canapply = false;
1676                     break;
1677                 }
1679                 if ($gi->aggregationcoef > 0) {
1680                     // Extra credit items are not allowed.
1681                     $canapply = false;
1682                     break;
1683                 }
1685                 if ($lastweight !== null && $lastweight != $gi->aggregationcoef2) {
1686                     // One of the weight differs from another item.
1687                     $canapply = false;
1688                     break;
1689                 }
1691                 if ($lastmaxgrade !== null && $lastmaxgrade != $gi->grademax) {
1692                     // One of the max grade differ from another item. This is not allowed for now
1693                     // because we could be end up with different max grade between users for this category.
1694                     $canapply = false;
1695                     break;
1696                 }
1698                 $lastweight = $gi->aggregationcoef2;
1699                 $lastmaxgrade = $gi->grademax;
1700             }
1702             $this->canapplylimitrules = $canapply;
1703         }
1705         return $this->canapplylimitrules;
1706     }
1708     /**
1709      * Returns true if category uses extra credit of any kind
1710      *
1711      * @return bool True if extra credit used
1712      */
1713     public function is_extracredit_used() {
1714         return self::aggregation_uses_extracredit($this->aggregation);
1715     }
1717     /**
1718      * Returns true if aggregation passed is using extracredit.
1719      *
1720      * @param int $aggregation Aggregation const.
1721      * @return bool True if extra credit used
1722      */
1723     public static function aggregation_uses_extracredit($aggregation) {
1724         return ($aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN2
1725              or $aggregation == GRADE_AGGREGATE_EXTRACREDIT_MEAN
1726              or $aggregation == GRADE_AGGREGATE_SUM);
1727     }
1729     /**
1730      * Returns true if category uses special aggregation coefficient
1731      *
1732      * @return bool True if an aggregation coefficient is being used
1733      */
1734     public function is_aggregationcoef_used() {
1735         return self::aggregation_uses_aggregationcoef($this->aggregation);
1737     }
1739     /**
1740      * Returns true if aggregation uses aggregationcoef
1741      *
1742      * @param int $aggregation Aggregation const.
1743      * @return bool True if an aggregation coefficient is being used
1744      */
1745     public static function aggregation_uses_aggregationcoef($aggregation) {
1746         return ($aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN
1747              or $aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN2
1748              or $aggregation == GRADE_AGGREGATE_EXTRACREDIT_MEAN
1749              or $aggregation == GRADE_AGGREGATE_SUM);
1751     }
1753     /**
1754      * Recursive function to find which weight/extra credit field to use in the grade item form.
1755      *
1756      * @param string $first Whether or not this is the first item in the recursion
1757      * @return string
1758      */
1759     public function get_coefstring($first=true) {
1760         if (!is_null($this->coefstring)) {
1761             return $this->coefstring;
1762         }
1764         $overriding_coefstring = null;
1766         // Stop recursing upwards if this category has no parent
1767         if (!$first) {
1769             if ($parent_category = $this->load_parent_category()) {
1770                 return $parent_category->get_coefstring(false);
1772             } else {
1773                 return null;
1774             }
1776         } else if ($first) {
1778             if ($parent_category = $this->load_parent_category()) {
1779                 $overriding_coefstring = $parent_category->get_coefstring(false);
1780             }
1781         }
1783         // If an overriding coefstring has trickled down from one of the parent categories, return it. Otherwise, return self.
1784         if (!is_null($overriding_coefstring)) {
1785             return $overriding_coefstring;
1786         }
1788         // No parent category is overriding this category's aggregation, return its string
1789         if ($this->aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN) {
1790             $this->coefstring = 'aggregationcoefweight';
1792         } else if ($this->aggregation == GRADE_AGGREGATE_WEIGHTED_MEAN2) {
1793             $this->coefstring = 'aggregationcoefextrasum';
1795         } else if ($this->aggregation == GRADE_AGGREGATE_EXTRACREDIT_MEAN) {
1796             $this->coefstring = 'aggregationcoefextraweight';
1798         } else if ($this->aggregation == GRADE_AGGREGATE_SUM) {
1799             $this->coefstring = 'aggregationcoefextraweightsum';
1801         } else {
1802             $this->coefstring = 'aggregationcoef';
1803         }
1804         return $this->coefstring;
1805     }
1807     /**
1808      * Returns tree with all grade_items and categories as elements
1809      *
1810      * @param int $courseid The course ID
1811      * @param bool $include_category_items as category children
1812      * @return array
1813      */
1814     public static function fetch_course_tree($courseid, $include_category_items=false) {
1815         $course_category = grade_category::fetch_course_category($courseid);
1816         $category_array = array('object'=>$course_category, 'type'=>'category', 'depth'=>1,
1817                                 'children'=>$course_category->get_children($include_category_items));
1819         $course_category->sortorder = $course_category->get_sortorder();
1820         $sortorder = $course_category->get_sortorder();
1821         return grade_category::_fetch_course_tree_recursion($category_array, $sortorder);
1822     }
1824     /**
1825      * An internal function that recursively sorts grade categories within a course
1826      *
1827      * @param array $category_array The seed of the recursion
1828      * @param int   $sortorder The current sortorder
1829      * @return array An array containing 'object', 'type', 'depth' and optionally 'children'
1830      */
1831     static private function _fetch_course_tree_recursion($category_array, &$sortorder) {
1832         // update the sortorder in db if needed
1833         //NOTE: This leads to us resetting sort orders every time the categories and items page is viewed :(
1834         //if ($category_array['object']->sortorder != $sortorder) {
1835             //$category_array['object']->set_sortorder($sortorder);
1836         //}
1838         if (isset($category_array['object']->gradetype) && $category_array['object']->gradetype==GRADE_TYPE_NONE) {
1839             return null;
1840         }
1842         // store the grade_item or grade_category instance with extra info
1843         $result = array('object'=>$category_array['object'], 'type'=>$category_array['type'], 'depth'=>$category_array['depth']);
1845         // reuse final grades if there
1846         if (array_key_exists('finalgrades', $category_array)) {
1847             $result['finalgrades'] = $category_array['finalgrades'];
1848         }
1850         // recursively resort children
1851         if (!empty($category_array['children'])) {
1852             $result['children'] = array();
1853             //process the category item first
1854             $child = null;
1856             foreach ($category_array['children'] as $oldorder=>$child_array) {
1858                 if ($child_array['type'] == 'courseitem' or $child_array['type'] == 'categoryitem') {
1859                     $child = grade_category::_fetch_course_tree_recursion($child_array, $sortorder);
1860                     if (!empty($child)) {
1861                         $result['children'][$sortorder] = $child;
1862                     }
1863                 }
1864             }
1866             foreach ($category_array['children'] as $oldorder=>$child_array) {
1868                 if ($child_array['type'] != 'courseitem' and $child_array['type'] != 'categoryitem') {
1869                     $child = grade_category::_fetch_course_tree_recursion($child_array, $sortorder);
1870                     if (!empty($child)) {
1871                         $result['children'][++$sortorder] = $child;
1872                     }
1873                 }
1874             }
1875         }
1877         return $result;
1878     }
1880     /**
1881      * Fetches and returns all the children categories and/or grade_items belonging to this category.
1882      * By default only returns the immediate children (depth=1), but deeper levels can be requested,
1883      * as well as all levels (0). The elements are indexed by sort order.
1884      *
1885      * @param bool $include_category_items Whether or not to include category grade_items in the children array
1886      * @return array Array of child objects (grade_category and grade_item).
1887      */
1888     public function get_children($include_category_items=false) {
1889         global $DB;
1891         // This function must be as fast as possible ;-)
1892         // fetch all course grade items and categories into memory - we do not expect hundreds of these in course
1893         // we have to limit the number of queries though, because it will be used often in grade reports
1895         $cats  = $DB->get_records('grade_categories', array('courseid' => $this->courseid));
1896         $items = $DB->get_records('grade_items', array('courseid' => $this->courseid));
1898         // init children array first
1899         foreach ($cats as $catid=>$cat) {
1900             $cats[$catid]->children = array();
1901         }
1903         //first attach items to cats and add category sortorder
1904         foreach ($items as $item) {
1906             if ($item->itemtype == 'course' or $item->itemtype == 'category') {
1907                 $cats[$item->iteminstance]->sortorder = $item->sortorder;
1909                 if (!$include_category_items) {
1910                     continue;
1911                 }
1912                 $categoryid = $item->iteminstance;
1914             } else {
1915                 $categoryid = $item->categoryid;
1916                 if (empty($categoryid)) {
1917                     debugging('Found a grade item that isnt in a category');
1918                 }
1919             }
1921             // prevent problems with duplicate sortorders in db
1922             $sortorder = $item->sortorder;
1924             while (array_key_exists($categoryid, $cats)
1925                 && array_key_exists($sortorder, $cats[$categoryid]->children)) {
1927                 $sortorder++;
1928             }
1930             $cats[$categoryid]->children[$sortorder] = $item;
1932         }
1934         // now find the requested category and connect categories as children
1935         $category = false;
1937         foreach ($cats as $catid=>$cat) {
1939             if (empty($cat->parent)) {
1941                 if ($cat->path !== '/'.$cat->id.'/') {
1942                     $grade_category = new grade_category($cat, false);
1943                     $grade_category->path  = '/'.$cat->id.'/';
1944                     $grade_category->depth = 1;
1945                     $grade_category->update('system');
1946                     return $this->get_children($include_category_items);
1947                 }
1949             } else {
1951                 if (empty($cat->path) or !preg_match('|/'.$cat->parent.'/'.$cat->id.'/$|', $cat->path)) {
1952                     //fix paths and depts
1953                     static $recursioncounter = 0; // prevents infinite recursion
1954                     $recursioncounter++;
1956                     if ($recursioncounter < 5) {
1957                         // fix paths and depths!
1958                         $grade_category = new grade_category($cat, false);
1959                         $grade_category->depth = 0;
1960                         $grade_category->path  = null;
1961                         $grade_category->update('system');
1962                         return $this->get_children($include_category_items);
1963                     }
1964                 }
1965                 // prevent problems with duplicate sortorders in db
1966                 $sortorder = $cat->sortorder;
1968                 while (array_key_exists($sortorder, $cats[$cat->parent]->children)) {
1969                     //debugging("$sortorder exists in cat loop");
1970                     $sortorder++;
1971                 }
1973                 $cats[$cat->parent]->children[$sortorder] = &$cats[$catid];
1974             }
1976             if ($catid == $this->id) {
1977                 $category = &$cats[$catid];
1978             }
1979         }
1981         unset($items); // not needed
1982         unset($cats); // not needed
1984         $children_array = grade_category::_get_children_recursion($category);
1986         ksort($children_array);
1988         return $children_array;
1990     }
1992     /**
1993      * Private method used to retrieve all children of this category recursively
1994      *
1995      * @param grade_category $category Source of current recursion
1996      * @return array An array of child grade categories
1997      */
1998     private static function _get_children_recursion($category) {
2000         $children_array = array();
2001         foreach ($category->children as $sortorder=>$child) {
2003             if (array_key_exists('itemtype', $child)) {
2004                 $grade_item = new grade_item($child, false);
2006                 if (in_array($grade_item->itemtype, array('course', 'category'))) {
2007                     $type  = $grade_item->itemtype.'item';
2008                     $depth = $category->depth;
2010                 } else {
2011                     $type  = 'item';
2012                     $depth = $category->depth; // we use this to set the same colour
2013                 }
2014                 $children_array[$sortorder] = array('object'=>$grade_item, 'type'=>$type, 'depth'=>$depth);
2016             } else {
2017                 $children = grade_category::_get_children_recursion($child);
2018                 $grade_category = new grade_category($child, false);
2020                 if (empty($children)) {
2021                     $children = array();
2022                 }
2023                 $children_array[$sortorder] = array('object'=>$grade_category, 'type'=>'category', 'depth'=>$grade_category->depth, 'children'=>$children);
2024             }
2025         }
2027         // sort the array
2028         ksort($children_array);
2030         return $children_array;
2031     }
2033     /**
2034      * Uses {@link get_grade_item()} to load or create a grade_item, then saves it as $this->grade_item.
2035      *
2036      * @return grade_item
2037      */
2038     public function load_grade_item() {
2039         if (empty($this->grade_item)) {
2040             $this->grade_item = $this->get_grade_item();
2041         }
2042         return $this->grade_item;
2043     }
2045     /**
2046      * Retrieves this grade categories' associated grade_item from the database
2047      *
2048      * If no grade_item exists yet, creates one.
2049      *
2050      * @return grade_item
2051      */
2052     public function get_grade_item() {
2053         if (empty($this->id)) {
2054             debugging("Attempt to obtain a grade_category's associated grade_item without the category's ID being set.");
2055             return false;
2056         }
2058         if (empty($this->parent)) {
2059             $params = array('courseid'=>$this->courseid, 'itemtype'=>'course', 'iteminstance'=>$this->id);
2061         } else {
2062             $params = array('courseid'=>$this->courseid, 'itemtype'=>'category', 'iteminstance'=>$this->id);
2063         }
2065         if (!$grade_items = grade_item::fetch_all($params)) {
2066             // create a new one
2067             $grade_item = new grade_item($params, false);
2068             $grade_item->gradetype = GRADE_TYPE_VALUE;
2069             $grade_item->insert('system');
2071         } else if (count($grade_items) == 1) {
2072             // found existing one
2073             $grade_item = reset($grade_items);
2075         } else {
2076             debugging("Found more than one grade_item attached to category id:".$this->id);
2077             // return first one
2078             $grade_item = reset($grade_items);
2079         }
2081         return $grade_item;
2082     }
2084     /**
2085      * Uses $this->parent to instantiate $this->parent_category based on the referenced record in the DB
2086      *
2087      * @return grade_category The parent category
2088      */
2089     public function load_parent_category() {
2090         if (empty($this->parent_category) && !empty($this->parent)) {
2091             $this->parent_category = $this->get_parent_category();
2092         }
2093         return $this->parent_category;
2094     }
2096     /**
2097      * Uses $this->parent to instantiate and return a grade_category object
2098      *
2099      * @return grade_category Returns the parent category or null if this category has no parent
2100      */
2101     public function get_parent_category() {
2102         if (!empty($this->parent)) {
2103             $parent_category = new grade_category(array('id' => $this->parent));
2104             return $parent_category;
2105         } else {
2106             return null;
2107         }
2108     }
2110     /**
2111      * Returns the most descriptive field for this grade category
2112      *
2113      * @return string name
2114      */
2115     public function get_name() {
2116         global $DB;
2117         // For a course category, we return the course name if the fullname is set to '?' in the DB (empty in the category edit form)
2118         if (empty($this->parent) && $this->fullname == '?') {
2119             $course = $DB->get_record('course', array('id'=> $this->courseid));
2120             return format_string($course->fullname);
2122         } else {
2123             return $this->fullname;
2124         }
2125     }
2127     /**
2128      * Describe the aggregation settings for this category so the reports make more sense.
2129      *
2130      * @return string description
2131      */
2132     public function get_description() {
2133         $allhelp = array();
2134         if ($this->aggregation != GRADE_AGGREGATE_SUM) {
2135             $aggrstrings = grade_helper::get_aggregation_strings();
2136             $allhelp[] = $aggrstrings[$this->aggregation];
2137         }
2139         if ($this->droplow && $this->can_apply_limit_rules()) {
2140             $allhelp[] = get_string('droplowestvalues', 'grades', $this->droplow);
2141         }
2142         if ($this->keephigh && $this->can_apply_limit_rules()) {
2143             $allhelp[] = get_string('keephighestvalues', 'grades', $this->keephigh);
2144         }
2145         if (!$this->aggregateonlygraded) {
2146             $allhelp[] = get_string('aggregatenotonlygraded', 'grades');
2147         }
2148         if ($allhelp) {
2149             return implode('. ', $allhelp) . '.';
2150         }
2151         return '';
2152     }
2154     /**
2155      * Sets this category's parent id
2156      *
2157      * @param int $parentid The ID of the category that is the new parent to $this
2158      * @param string $source From where was the object updated (mod/forum, manual, etc.)
2159      * @return bool success
2160      */
2161     public function set_parent($parentid, $source=null) {
2162         if ($this->parent == $parentid) {
2163             return true;
2164         }
2166         if ($parentid == $this->id) {
2167             print_error('cannotassignselfasparent');
2168         }
2170         if (empty($this->parent) and $this->is_course_category()) {
2171             print_error('cannothaveparentcate');
2172         }
2174         // find parent and check course id
2175         if (!$parent_category = grade_category::fetch(array('id'=>$parentid, 'courseid'=>$this->courseid))) {
2176             return false;
2177         }
2179         $this->force_regrading();
2181         // set new parent category
2182         $this->parent          = $parent_category->id;
2183         $this->parent_category =& $parent_category;
2184         $this->path            = null;       // remove old path and depth - will be recalculated in update()
2185         $this->depth           = 0;          // remove old path and depth - will be recalculated in update()
2186         $this->update($source);
2188         return $this->update($source);
2189     }
2191     /**
2192      * Returns the final grade values for this grade category.
2193      *
2194      * @param int $userid Optional user ID to retrieve a single user's final grade
2195      * @return mixed An array of all final_grades (stdClass objects) for this grade_item, or a single final_grade.
2196      */
2197     public function get_final($userid=null) {
2198         $this->load_grade_item();
2199         return $this->grade_item->get_final($userid);
2200     }
2202     /**
2203      * Returns the sortorder of the grade categories' associated grade_item
2204      *
2205      * This method is also available in grade_item for cases where the object type is not known.
2206      *
2207      * @return int Sort order
2208      */
2209     public function get_sortorder() {
2210         $this->load_grade_item();
2211         return $this->grade_item->get_sortorder();
2212     }
2214     /**
2215      * Returns the idnumber of the grade categories' associated grade_item.
2216      *
2217      * This method is also available in grade_item for cases where the object type is not known.
2218      *
2219      * @return string idnumber
2220      */
2221     public function get_idnumber() {
2222         $this->load_grade_item();
2223         return $this->grade_item->get_idnumber();
2224     }
2226     /**
2227      * Sets the sortorder variable for this category.
2228      *
2229      * This method is also available in grade_item, for cases where the object type is not know.
2230      *
2231      * @param int $sortorder The sortorder to assign to this category
2232      */
2233     public function set_sortorder($sortorder) {
2234         $this->load_grade_item();
2235         $this->grade_item->set_sortorder($sortorder);
2236     }
2238     /**
2239      * Move this category after the given sortorder
2240      *
2241      * Does not change the parent
2242      *
2243      * @param int $sortorder to place after.
2244      * @return void
2245      */
2246     public function move_after_sortorder($sortorder) {
2247         $this->load_grade_item();
2248         $this->grade_item->move_after_sortorder($sortorder);
2249     }
2251     /**
2252      * Return true if this is the top most category that represents the total course grade.
2253      *
2254      * @return bool
2255      */
2256     public function is_course_category() {
2257         $this->load_grade_item();
2258         return $this->grade_item->is_course_item();
2259     }
2261     /**
2262      * Return the course level grade_category object
2263      *
2264      * @param int $courseid The Course ID
2265      * @return grade_category Returns the course level grade_category instance
2266      */
2267     public static function fetch_course_category($courseid) {
2268         if (empty($courseid)) {
2269             debugging('Missing course id!');
2270             return false;
2271         }
2273         // course category has no parent
2274         if ($course_category = grade_category::fetch(array('courseid'=>$courseid, 'parent'=>null))) {
2275             return $course_category;
2276         }
2278         // create a new one
2279         $course_category = new grade_category();
2280         $course_category->insert_course_category($courseid);
2282         return $course_category;
2283     }
2285     /**
2286      * Is grading object editable?
2287      *
2288      * @return bool
2289      */
2290     public function is_editable() {
2291         return true;
2292     }
2294     /**
2295      * Returns the locked state/date of the grade categories' associated grade_item.
2296      *
2297      * This method is also available in grade_item, for cases where the object type is not known.
2298      *
2299      * @return bool
2300      */
2301     public function is_locked() {
2302         $this->load_grade_item();
2303         return $this->grade_item->is_locked();
2304     }
2306     /**
2307      * Sets the grade_item's locked variable and updates the grade_item.
2308      *
2309      * Calls set_locked() on the categories' grade_item
2310      *
2311      * @param int  $lockedstate 0, 1 or a timestamp int(10) after which date the item will be locked.
2312      * @param bool $cascade lock/unlock child objects too
2313      * @param bool $refresh refresh grades when unlocking
2314      * @return bool success if category locked (not all children mayb be locked though)
2315      */
2316     public function set_locked($lockedstate, $cascade=false, $refresh=true) {
2317         $this->load_grade_item();
2319         $result = $this->grade_item->set_locked($lockedstate, $cascade, true);
2321         if ($cascade) {
2322             //process all children - items and categories
2323             if ($children = grade_item::fetch_all(array('categoryid'=>$this->id))) {
2325                 foreach ($children as $child) {
2326                     $child->set_locked($lockedstate, true, false);
2328                     if (empty($lockedstate) and $refresh) {
2329                         //refresh when unlocking
2330                         $child->refresh_grades();
2331                     }
2332                 }
2333             }
2335             if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
2337                 foreach ($children as $child) {
2338                     $child->set_locked($lockedstate, true, true);
2339                 }
2340             }
2341         }
2343         return $result;
2344     }
2346     /**
2347      * Overrides grade_object::set_properties() to add special handling for changes to category aggregation types
2348      *
2349      * @param stdClass $instance the object to set the properties on
2350      * @param array|stdClass $params Either an associative array or an object containing property name, property value pairs
2351      */
2352     public static function set_properties(&$instance, $params) {
2353         global $DB;
2355         parent::set_properties($instance, $params);
2357         //if they've changed aggregation type we made need to do some fiddling to provide appropriate defaults
2358         if (!empty($params->aggregation)) {
2360             //weight and extra credit share a column :( Would like a default of 1 for weight and 0 for extra credit
2361             //Flip from the default of 0 to 1 (or vice versa) if ALL items in the category are still set to the old default.
2362             if (self::aggregation_uses_aggregationcoef($params->aggregation)) {
2363                 $sql = $defaultaggregationcoef = null;
2365                 if (!self::aggregation_uses_extracredit($params->aggregation)) {
2366                     //if all items in this category have aggregation coefficient of 0 we can change it to 1 ie evenly weighted
2367                     $sql = "select count(id) from {grade_items} where categoryid=:categoryid and aggregationcoef!=0";
2368                     $defaultaggregationcoef = 1;
2369                 } else {
2370                     //if all items in this category have aggregation coefficient of 1 we can change it to 0 ie no extra credit
2371                     $sql = "select count(id) from {grade_items} where categoryid=:categoryid and aggregationcoef!=1";
2372                     $defaultaggregationcoef = 0;
2373                 }
2375                 $params = array('categoryid'=>$instance->id);
2376                 $count = $DB->count_records_sql($sql, $params);
2377                 if ($count===0) { //category is either empty or all items are set to a default value so we can switch defaults
2378                     $params['aggregationcoef'] = $defaultaggregationcoef;
2379                     $DB->execute("update {grade_items} set aggregationcoef=:aggregationcoef where categoryid=:categoryid",$params);
2380                 }
2381             }
2382         }
2383     }
2385     /**
2386      * Sets the grade_item's hidden variable and updates the grade_item.
2387      *
2388      * Overrides grade_item::set_hidden() to add cascading of the hidden value to grade items in this grade category
2389      *
2390      * @param int $hidden 0 mean always visible, 1 means always hidden and a number > 1 is a timestamp to hide until
2391      * @param bool $cascade apply to child objects too
2392      */
2393     public function set_hidden($hidden, $cascade=false) {
2394         $this->load_grade_item();
2395         //this hides the associated grade item (the course total)
2396         $this->grade_item->set_hidden($hidden, $cascade);
2397         //this hides the category itself and everything it contains
2398         parent::set_hidden($hidden, $cascade);
2400         if ($cascade) {
2402             if ($children = grade_item::fetch_all(array('categoryid'=>$this->id))) {
2404                 foreach ($children as $child) {
2405                     if ($child->can_control_visibility()) {
2406                         $child->set_hidden($hidden, $cascade);
2407                     }
2408                 }
2409             }
2411             if ($children = grade_category::fetch_all(array('parent'=>$this->id))) {
2413                 foreach ($children as $child) {
2414                     $child->set_hidden($hidden, $cascade);
2415                 }
2416             }
2417         }
2419         //if marking category visible make sure parent category is visible MDL-21367
2420         if( !$hidden ) {
2421             $category_array = grade_category::fetch_all(array('id'=>$this->parent));
2422             if ($category_array && array_key_exists($this->parent, $category_array)) {
2423                 $category = $category_array[$this->parent];
2424                 //call set_hidden on the category regardless of whether it is hidden as its parent might be hidden
2425                 //if($category->is_hidden()) {
2426                     $category->set_hidden($hidden, false);
2427                 //}
2428             }
2429         }
2430     }
2432     /**
2433      * Applies default settings on this category
2434      *
2435      * @return bool True if anything changed
2436      */
2437     public function apply_default_settings() {
2438         global $CFG;
2440         foreach ($this->forceable as $property) {
2442             if (isset($CFG->{"grade_$property"})) {
2444                 if ($CFG->{"grade_$property"} == -1) {
2445                     continue; //temporary bc before version bump
2446                 }
2447                 $this->$property = $CFG->{"grade_$property"};
2448             }
2449         }
2450     }
2452     /**
2453      * Applies forced settings on this category
2454      *
2455      * @return bool True if anything changed
2456      */
2457     public function apply_forced_settings() {
2458         global $CFG;
2460         $updated = false;
2462         foreach ($this->forceable as $property) {
2464             if (isset($CFG->{"grade_$property"}) and isset($CFG->{"grade_{$property}_flag"}) and
2465                                                     ((int) $CFG->{"grade_{$property}_flag"} & 1)) {
2467                 if ($CFG->{"grade_$property"} == -1) {
2468                     continue; //temporary bc before version bump
2469                 }
2470                 $this->$property = $CFG->{"grade_$property"};
2471                 $updated = true;
2472             }
2473         }
2475         return $updated;
2476     }
2478     /**
2479      * Notification of change in forced category settings.
2480      *
2481      * Causes all course and category grade items to be marked as needing to be updated
2482      */
2483     public static function updated_forced_settings() {
2484         global $CFG, $DB;
2485         $params = array(1, 'course', 'category');
2486         $sql = "UPDATE {grade_items} SET needsupdate=? WHERE itemtype=? or itemtype=?";
2487         $DB->execute($sql, $params);
2488     }