Merge branch 'MDL-70114-310' of git://github.com/bmbrands/moodle into MOODLE_310_STABLE
[moodle.git] / grade / report / lib.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  * File containing the grade_report class
19  *
20  * @package   core_grades
21  * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 require_once($CFG->libdir.'/gradelib.php');
27 /**
28  * An abstract class containing variables and methods used by all or most reports.
29  * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
30  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
31  */
32 abstract class grade_report {
33     /**
34      * The courseid.
35      * @var int $courseid
36      */
37     public $courseid;
39     /**
40      * The course.
41      * @var object $course
42      */
43     public $course;
45     /** Grade plugin return tracking object.
46      * @var object $gpr
47      */
48     public $gpr;
50     /**
51      * The context.
52      *
53      * @var context $context
54      */
55     public $context;
57     /**
58      * The grade_tree object.
59      * @var grade_tree $gtree
60      */
61     public $gtree;
63     /**
64      * User preferences related to this report.
65      * @var array $prefs
66      */
67     public $prefs = array();
69     /**
70      * The roles for this report.
71      * @var string $gradebookroles
72      */
73     public $gradebookroles;
75     /**
76      * base url for sorting by first/last name.
77      * @var string $baseurl
78      */
79     public $baseurl;
81     /**
82      * base url for paging.
83      * @var string $pbarurl
84      */
85     public $pbarurl;
87     /**
88      * Current page (for paging).
89      * @var int $page
90      */
91     public $page;
93     /**
94      * Array of cached language strings (using get_string() all the time takes a long time!).
95      * @var array $lang_strings
96      */
97     public $lang_strings = array();
99     // GROUP VARIABLES (including SQL)
101     /**
102      * The current group being displayed.
103      * @var int $currentgroup
104      */
105     public $currentgroup;
107     /**
108      * The current groupname being displayed.
109      * @var string $currentgroupname
110      */
111     public $currentgroupname;
113     /**
114      * Current course group mode
115      * @var int $groupmode
116      */
117     public $groupmode;
119     /**
120      * A HTML select element used to select the current group.
121      * @var string $group_selector
122      */
123     public $group_selector;
125     /**
126      * An SQL fragment used to add linking information to the group tables.
127      * @var string $groupsql
128      */
129     protected $groupsql;
131     /**
132      * An SQL constraint to append to the queries used by this object to build the report.
133      * @var string $groupwheresql
134      */
135     protected $groupwheresql;
137     /**
138      * The ordered params for $groupwheresql
139      * @var array $groupwheresql_params
140      */
141     protected $groupwheresql_params = array();
143     // USER VARIABLES (including SQL).
145     /**
146      * An SQL constraint to append to the queries used by this object to build the report.
147      * @var string $userwheresql
148      */
149     protected $userwheresql;
151     /**
152      * The ordered params for $userwheresql
153      * @var array $userwheresql_params
154      */
155     protected $userwheresql_params = array();
157     /**
158      * Constructor. Sets local copies of user preferences and initialises grade_tree.
159      * @param int $courseid
160      * @param object $gpr grade plugin return tracking object
161      * @param string $context
162      * @param int $page The current page being viewed (when report is paged)
163      */
164     public function __construct($courseid, $gpr, $context, $page=null) {
165         global $CFG, $COURSE, $DB;
167         if (empty($CFG->gradebookroles)) {
168             print_error('norolesdefined', 'grades');
169         }
171         $this->courseid  = $courseid;
172         if ($this->courseid == $COURSE->id) {
173             $this->course = $COURSE;
174         } else {
175             $this->course = $DB->get_record('course', array('id' => $this->courseid));
176         }
178         $this->gpr       = $gpr;
179         $this->context   = $context;
180         $this->page      = $page;
182         // roles to be displayed in the gradebook
183         $this->gradebookroles = $CFG->gradebookroles;
185         // Set up link to preferences page
186         $this->preferences_page = $CFG->wwwroot.'/grade/report/grader/preferences.php?id='.$courseid;
188         // init gtree in child class
189     }
191     /**
192      * Given the name of a user preference (without grade_report_ prefix), locally saves then returns
193      * the value of that preference. If the preference has already been fetched before,
194      * the saved value is returned. If the preference is not set at the User level, the $CFG equivalent
195      * is given (site default).
196      * Can be called statically, but then doesn't benefit from caching
197      * @param string $pref The name of the preference (do not include the grade_report_ prefix)
198      * @param int $objectid An optional itemid or categoryid to check for a more fine-grained preference
199      * @return mixed The value of the preference
200      */
201     public function get_pref($pref, $objectid=null) {
202         global $CFG;
203         $fullprefname = 'grade_report_' . $pref;
204         $shortprefname = 'grade_' . $pref;
206         $retval = null;
208         if (!isset($this) OR get_class($this) != 'grade_report') {
209             if (!empty($objectid)) {
210                 $retval = get_user_preferences($fullprefname . $objectid, self::get_pref($pref));
211             } else if (isset($CFG->$fullprefname)) {
212                 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
213             } else if (isset($CFG->$shortprefname)) {
214                 $retval = get_user_preferences($fullprefname, $CFG->$shortprefname);
215             } else {
216                 $retval = null;
217             }
218         } else {
219             if (empty($this->prefs[$pref.$objectid])) {
221                 if (!empty($objectid)) {
222                     $retval = get_user_preferences($fullprefname . $objectid);
223                     if (empty($retval)) {
224                         // No item pref found, we are returning the global preference
225                         $retval = $this->get_pref($pref);
226                         $objectid = null;
227                     }
228                 } else {
229                     $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
230                 }
231                 $this->prefs[$pref.$objectid] = $retval;
232             } else {
233                 $retval = $this->prefs[$pref.$objectid];
234             }
235         }
237         return $retval;
238     }
240     /**
241      * Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value,
242      * the preference will be removed in favour of a higher-level preference.
243      * @param string $pref The name of the preference.
244      * @param mixed $pref_value The value of the preference.
245      * @param int $itemid An optional itemid to which the preference will be assigned
246      * @return bool Success or failure.
247      */
248     public function set_pref($pref, $pref_value='default', $itemid=null) {
249         $fullprefname = 'grade_report_' . $pref;
250         if ($pref_value == 'default') {
251             return unset_user_preference($fullprefname.$itemid);
252         } else {
253             return set_user_preference($fullprefname.$itemid, $pref_value);
254         }
255     }
257     /**
258      * Handles form data sent by this report for this report. Abstract method to implement in all children.
259      * @abstract
260      * @param array $data
261      * @return mixed True or array of errors
262      */
263     abstract public function process_data($data);
265     /**
266      * Processes a single action against a category, grade_item or grade.
267      * @param string $target Sortorder
268      * @param string $action Which action to take (edit, delete etc...)
269      * @return
270      */
271     abstract public function process_action($target, $action);
273     /**
274      * First checks the cached language strings, then returns match if found, or uses get_string()
275      * to get it from the DB, caches it then returns it.
276      * @param string $strcode
277      * @param string $section Optional language section
278      * @return string
279      */
280     public function get_lang_string($strcode, $section=null) {
281         if (empty($this->lang_strings[$strcode])) {
282             $this->lang_strings[$strcode] = get_string($strcode, $section);
283         }
284         return $this->lang_strings[$strcode];
285     }
287     /**
288      * Fetches and returns a count of all the users that will be shown on this page.
289      * @param boolean $groups include groups limit
290      * @param boolean $users include users limit - default false, used for searching purposes
291      * @return int Count of users
292      */
293     public function get_numusers($groups = true, $users = false) {
294         global $CFG, $DB;
295         $userwheresql = "";
296         $groupsql      = "";
297         $groupwheresql = "";
299         // Limit to users with a gradeable role.
300         list($gradebookrolessql, $gradebookrolesparams) = $DB->get_in_or_equal(explode(',', $this->gradebookroles), SQL_PARAMS_NAMED, 'grbr0');
302         // Limit to users with an active enrollment.
303         list($enrolledsql, $enrolledparams) = get_enrolled_sql($this->context);
305         // We want to query both the current context and parent contexts.
306         list($relatedctxsql, $relatedctxparams) = $DB->get_in_or_equal($this->context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'relatedctx');
308         $params = array_merge($gradebookrolesparams, $enrolledparams, $relatedctxparams);
310         if ($users) {
311             $userwheresql = $this->userwheresql;
312             $params       = array_merge($params, $this->userwheresql_params);
313         }
315         if ($groups) {
316             $groupsql      = $this->groupsql;
317             $groupwheresql = $this->groupwheresql;
318             $params        = array_merge($params, $this->groupwheresql_params);
319         }
321         $sql = "SELECT DISTINCT u.id
322                        FROM {user} u
323                        JOIN ($enrolledsql) je
324                             ON je.id = u.id
325                        JOIN {role_assignments} ra
326                             ON u.id = ra.userid
327                        $groupsql
328                       WHERE ra.roleid $gradebookrolessql
329                             AND u.deleted = 0
330                             $userwheresql
331                             $groupwheresql
332                             AND ra.contextid $relatedctxsql";
333         $selectedusers = $DB->get_records_sql($sql, $params);
335         $count = 0;
336         // Check if user's enrolment is active and should be displayed.
337         if (!empty($selectedusers)) {
338             $coursecontext = $this->context->get_course_context(true);
340             $defaultgradeshowactiveenrol = !empty($CFG->grade_report_showonlyactiveenrol);
341             $showonlyactiveenrol = get_user_preferences('grade_report_showonlyactiveenrol', $defaultgradeshowactiveenrol);
342             $showonlyactiveenrol = $showonlyactiveenrol || !has_capability('moodle/course:viewsuspendedusers', $coursecontext);
344             if ($showonlyactiveenrol) {
345                 $useractiveenrolments = get_enrolled_users($coursecontext, '', 0, 'u.id',  null, 0, 0, true);
346             }
348             foreach ($selectedusers as $id => $value) {
349                 if (!$showonlyactiveenrol || ($showonlyactiveenrol && array_key_exists($id, $useractiveenrolments))) {
350                     $count++;
351                 }
352             }
353         }
354         return $count;
355     }
357     /**
358      * Shows support for being used as a 'Grades' report.
359      */
360     public static function supports_mygrades() {
361         return false;
362     }
364     /**
365      * Sets up this object's group variables, mainly to restrict the selection of users to display.
366      */
367     protected function setup_groups() {
368         // find out current groups mode
369         if ($this->groupmode = groups_get_course_groupmode($this->course)) {
370             if (empty($this->gpr->groupid)) {
371                 $this->currentgroup = groups_get_course_group($this->course, true);
372             } else {
373                 $this->currentgroup = $this->gpr->groupid;
374             }
375             $this->group_selector = groups_print_course_menu($this->course, $this->pbarurl, true);
377             if ($this->groupmode == SEPARATEGROUPS and !$this->currentgroup and !has_capability('moodle/site:accessallgroups', $this->context)) {
378                 $this->currentgroup = -2; // means can not access any groups at all
379             }
380             if ($this->currentgroup) {
381                 if ($group = groups_get_group($this->currentgroup)) {
382                     $this->currentgroupname = $group->name;
383                 }
384                 $this->groupsql             = " JOIN {groups_members} gm ON gm.userid = u.id ";
385                 $this->groupwheresql        = " AND gm.groupid = :gr_grpid ";
386                 $this->groupwheresql_params = array('gr_grpid'=>$this->currentgroup);
387             }
388         }
389     }
391     /**
392      * Sets up this report's user criteria to restrict the selection of users to display.
393      */
394     public function setup_users() {
395         global $SESSION, $DB;
397         $this->userwheresql = "";
398         $this->userwheresql_params = array();
399         if (isset($SESSION->gradereport['filterfirstname']) && !empty($SESSION->gradereport['filterfirstname'])) {
400             $this->userwheresql .= ' AND '.$DB->sql_like('u.firstname', ':firstname', false, false);
401             $this->userwheresql_params['firstname'] = $SESSION->gradereport['filterfirstname'].'%';
402         }
403         if (isset($SESSION->gradereport['filtersurname']) && !empty($SESSION->gradereport['filtersurname'])) {
404             $this->userwheresql .= ' AND '.$DB->sql_like('u.lastname', ':lastname', false, false);
405             $this->userwheresql_params['lastname'] = $SESSION->gradereport['filtersurname'].'%';
406         }
407     }
409     /**
410      * Returns an arrow icon inside an <a> tag, for the purpose of sorting a column.
411      * @param string $direction
412      * @param moodle_url $sortlink
413      */
414     protected function get_sort_arrow($direction='move', $sortlink=null) {
415         global $OUTPUT;
416         $pix = array('up' => 't/sort_desc', 'down' => 't/sort_asc', 'move' => 't/sort');
417         $matrix = array('up' => 'desc', 'down' => 'asc', 'move' => 'desc');
418         $strsort = $this->get_lang_string('sort' . $matrix[$direction]);
420         $arrow = $OUTPUT->pix_icon($pix[$direction], '', '', ['class' => 'sorticon']);
421         return html_writer::link($sortlink, $arrow, ['title' => $strsort, 'aria-label' => $strsort]);
422     }
424     /**
425      * Optionally blank out course/category totals if they contain any hidden items
426      * @param string $courseid the course id
427      * @param string $course_item an instance of grade_item
428      * @param string $finalgrade the grade for the course_item
429      * @return array[] containing values for 'grade', 'grademax', 'grademin', 'aggregationstatus' and 'aggregationweight'
430      */
431     protected function blank_hidden_total_and_adjust_bounds($courseid, $course_item, $finalgrade) {
432         global $CFG, $DB;
433         static $hiding_affected = null;//array of items in this course affected by hiding
435         // If we're dealing with multiple users we need to know when we've moved on to a new user.
436         static $previous_userid = null;
438         // If we're dealing with multiple courses we need to know when we've moved on to a new course.
439         static $previous_courseid = null;
441         $coursegradegrade = grade_grade::fetch(array('userid'=>$this->user->id, 'itemid'=>$course_item->id));
442         $grademin = $course_item->grademin;
443         $grademax = $course_item->grademax;
444         if ($coursegradegrade) {
445             $grademin = $coursegradegrade->get_grade_min();
446             $grademax = $coursegradegrade->get_grade_max();
447         } else {
448             $coursegradegrade = new grade_grade(array('userid'=>$this->user->id, 'itemid'=>$course_item->id), false);
449         }
450         $hint = $coursegradegrade->get_aggregation_hint();
451         $aggregationstatus = $hint['status'];
452         $aggregationweight = $hint['weight'];
454         if (!is_array($this->showtotalsifcontainhidden)) {
455             debugging('showtotalsifcontainhidden should be an array', DEBUG_DEVELOPER);
456             $this->showtotalsifcontainhidden = array($courseid => $this->showtotalsifcontainhidden);
457         }
459         if ($this->showtotalsifcontainhidden[$courseid] == GRADE_REPORT_SHOW_REAL_TOTAL_IF_CONTAINS_HIDDEN) {
460             return array('grade' => $finalgrade,
461                          'grademin' => $grademin,
462                          'grademax' => $grademax,
463                          'aggregationstatus' => $aggregationstatus,
464                          'aggregationweight' => $aggregationweight);
465         }
467         // If we've moved on to another course or user, reload the grades.
468         if ($previous_userid != $this->user->id || $previous_courseid != $courseid) {
469             $hiding_affected = null;
470             $previous_userid = $this->user->id;
471             $previous_courseid = $courseid;
472         }
474         if (!$hiding_affected) {
475             $items = grade_item::fetch_all(array('courseid'=>$courseid));
476             $grades = array();
477             $sql = "SELECT g.*
478                       FROM {grade_grades} g
479                       JOIN {grade_items} gi ON gi.id = g.itemid
480                      WHERE g.userid = {$this->user->id} AND gi.courseid = {$courseid}";
481             if ($gradesrecords = $DB->get_records_sql($sql)) {
482                 foreach ($gradesrecords as $grade) {
483                     $grades[$grade->itemid] = new grade_grade($grade, false);
484                 }
485                 unset($gradesrecords);
486             }
487             foreach ($items as $itemid => $unused) {
488                 if (!isset($grades[$itemid])) {
489                     $grade_grade = new grade_grade();
490                     $grade_grade->userid = $this->user->id;
491                     $grade_grade->itemid = $items[$itemid]->id;
492                     $grades[$itemid] = $grade_grade;
493                 }
494                 $grades[$itemid]->grade_item =& $items[$itemid];
495             }
496             $hiding_affected = grade_grade::get_hiding_affected($grades, $items);
497         }
499         //if the item definitely depends on a hidden item
500         if (array_key_exists($course_item->id, $hiding_affected['altered']) ||
501                 array_key_exists($course_item->id, $hiding_affected['alteredgrademin']) ||
502                 array_key_exists($course_item->id, $hiding_affected['alteredgrademax']) ||
503                 array_key_exists($course_item->id, $hiding_affected['alteredaggregationstatus']) ||
504                 array_key_exists($course_item->id, $hiding_affected['alteredaggregationweight'])) {
505             if (!$this->showtotalsifcontainhidden[$courseid] && array_key_exists($course_item->id, $hiding_affected['altered'])) {
506                 // Hide the grade, but only when it has changed.
507                 $finalgrade = null;
508             } else {
509                 //use reprocessed marks that exclude hidden items
510                 if (array_key_exists($course_item->id, $hiding_affected['altered'])) {
511                     $finalgrade = $hiding_affected['altered'][$course_item->id];
512                 }
513                 if (array_key_exists($course_item->id, $hiding_affected['alteredgrademin'])) {
514                     $grademin = $hiding_affected['alteredgrademin'][$course_item->id];
515                 }
516                 if (array_key_exists($course_item->id, $hiding_affected['alteredgrademax'])) {
517                     $grademax = $hiding_affected['alteredgrademax'][$course_item->id];
518                 }
519                 if (array_key_exists($course_item->id, $hiding_affected['alteredaggregationstatus'])) {
520                     $aggregationstatus = $hiding_affected['alteredaggregationstatus'][$course_item->id];
521                 }
522                 if (array_key_exists($course_item->id, $hiding_affected['alteredaggregationweight'])) {
523                     $aggregationweight = $hiding_affected['alteredaggregationweight'][$course_item->id];
524                 }
526                 if (!$this->showtotalsifcontainhidden[$courseid]) {
527                     // If the course total is hidden we must hide the weight otherwise
528                     // it can be used to compute the course total.
529                     $aggregationstatus = 'unknown';
530                     $aggregationweight = null;
531                 }
532             }
533         } else if (array_key_exists($course_item->id, $hiding_affected['unknowngrades'])) {
534             //not sure whether or not this item depends on a hidden item
535             if (!$this->showtotalsifcontainhidden[$courseid]) {
536                 //hide the grade
537                 $finalgrade = null;
538             } else {
539                 //use reprocessed marks that exclude hidden items
540                 $finalgrade = $hiding_affected['unknowngrades'][$course_item->id];
542                 if (array_key_exists($course_item->id, $hiding_affected['alteredgrademin'])) {
543                     $grademin = $hiding_affected['alteredgrademin'][$course_item->id];
544                 }
545                 if (array_key_exists($course_item->id, $hiding_affected['alteredgrademax'])) {
546                     $grademax = $hiding_affected['alteredgrademax'][$course_item->id];
547                 }
548                 if (array_key_exists($course_item->id, $hiding_affected['alteredaggregationstatus'])) {
549                     $aggregationstatus = $hiding_affected['alteredaggregationstatus'][$course_item->id];
550                 }
551                 if (array_key_exists($course_item->id, $hiding_affected['alteredaggregationweight'])) {
552                     $aggregationweight = $hiding_affected['alteredaggregationweight'][$course_item->id];
553                 }
554             }
555         }
557         return array('grade' => $finalgrade, 'grademin' => $grademin, 'grademax' => $grademax, 'aggregationstatus'=>$aggregationstatus, 'aggregationweight'=>$aggregationweight);
558     }
560     /**
561      * Optionally blank out course/category totals if they contain any hidden items
562      * @deprecated since Moodle 2.8 - Call blank_hidden_total_and_adjust_bounds instead.
563      * @param string $courseid the course id
564      * @param string $course_item an instance of grade_item
565      * @param string $finalgrade the grade for the course_item
566      * @return string The new final grade
567      */
568     protected function blank_hidden_total($courseid, $course_item, $finalgrade) {
569         // Note it is flawed to call this function directly because
570         // the aggregated grade does not make sense without the updated min and max information.
572         debugging('grade_report::blank_hidden_total() is deprecated.
573                    Call grade_report::blank_hidden_total_and_adjust_bounds instead.', DEBUG_DEVELOPER);
574         $result = $this->blank_hidden_total_and_adjust_bounds($courseid, $course_item, $finalgrade);
575         return $result['grade'];
576     }