grade/querylib.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/>.
  16
  17 /**
  18  * Functions used to retrieve grades objects
  19  *
  20  * @package   core_grades
  21  * @category  grade
  22  * @copyright 2008 Petr Skoda and Nicolas Connault
  23  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 /**
  27  * Returns the aggregated or calculated course grade(s) for a single course for one or more users
  28  *
  29  * @param int $courseid The ID of course
  30  * @param int|array $userid_or_ids Optional ID of the graded user or array of user IDs; if userid not used, returns only information about grade_item
  31  * @return stdClass Returns an object containing information about course grade item. scaleid, name, grade
  32  *         and locked status etc and user course grades: $item->grades[$userid] => $usercoursegrade
  33  */
  34 function grade_get_course_grades($courseid, $userid_or_ids=null) {
  35
  36     $grade_item = grade_item::fetch_course_item($courseid);
  37
  38     if ($grade_item->needsupdate) {
  39         grade_regrade_final_grades($courseid);
  40     }
  41
  42     $item = new stdClass();
  43     $item->scaleid    = $grade_item->scaleid;
  44     $item->name       = $grade_item->get_name();
  45     $item->grademin   = $grade_item->grademin;
  46     $item->grademax   = $grade_item->grademax;
  47     $item->gradepass  = $grade_item->gradepass;
  48     $item->locked     = $grade_item->is_locked();
  49     $item->hidden     = $grade_item->is_hidden();
  50     $item->grades     = array();
  51
  52     switch ($grade_item->gradetype) {
  53         case GRADE_TYPE_NONE:
  54             continue;
  55
  56         case GRADE_TYPE_VALUE:
  57             $item->scaleid = 0;
  58             break;
  59
  60         case GRADE_TYPE_TEXT:
  61             $item->scaleid   = 0;
  62             $item->grademin   = 0;
  63             $item->grademax   = 0;
  64             $item->gradepass  = 0;
  65             break;
  66     }
  67
  68     if (empty($userid_or_ids)) {
  69         $userids = array();
  70
  71     } else if (is_array($userid_or_ids)) {
  72         $userids = $userid_or_ids;
  73
  74     } else {
  75         $userids = array($userid_or_ids);
  76     }
  77
  78     if ($userids) {
  79         $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
  80         foreach ($userids as $userid) {
  81             $grade_grades[$userid]->grade_item =& $grade_item;
  82
  83             $grade = new stdClass();
  84             $grade->grade          = $grade_grades[$userid]->finalgrade;
  85             $grade->locked         = $grade_grades[$userid]->is_locked();
  86             $grade->hidden         = $grade_grades[$userid]->is_hidden();
  87             $grade->overridden     = $grade_grades[$userid]->overridden;
  88             $grade->feedback       = $grade_grades[$userid]->feedback;
  89             $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
  90             $grade->usermodified   = $grade_grades[$userid]->usermodified;
  91             $grade->dategraded     = $grade_grades[$userid]->get_dategraded();
  92             $grade->datesubmitted  = $grade_grades[$userid]->get_datesubmitted();
  93
  94             // create text representation of grade
  95             if ($grade_item->needsupdate) {
  96                 $grade->grade          = false;
  97                 $grade->str_grade      = get_string('error');
  98                 $grade->str_long_grade = $grade->str_grade;
  99
 100             } else if (is_null($grade->grade)) {
 101                 $grade->str_grade      = '-';
 102                 $grade->str_long_grade = $grade->str_grade;
 103
 104             } else {
 105                 $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
 106                 if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
 107                     $grade->str_long_grade = $grade->str_grade;
 108                 } else {
 109                     $a = new stdClass();
 110                     $a->grade = $grade->str_grade;
 111                     $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
 112                     $grade->str_long_grade = get_string('gradelong', 'grades', $a);
 113                 }
 114             }
 115
 116             // create html representation of feedback
 117             if (is_null($grade->feedback)) {
 118                 $grade->str_feedback = '';
 119             } else {
 120                 $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 121             }
 122
 123             $item->grades[$userid] = $grade;
 124         }
 125     }
 126
 127     return $item;
 128 }
 129
 130 /**
 131  * Returns the aggregated or calculated course grade for a single user for one or more courses
 132  *
 133  * @param int $userid The ID of the single user
 134  * @param int|array $courseid_or_ids Optional ID of course or array of IDs, empty means all of the user's courses
 135  * @return mixed grade info or grades array including item info, false if error
 136  */
 137 function grade_get_course_grade($userid, $courseid_or_ids=null) {
 138
 139     if (!is_array($courseid_or_ids)) {
 140         if (empty($courseid_or_ids)) {
 141             if (!$courses = enrol_get_users_courses($userid)) {
 142                 return false;
 143             }
 144             $courseids = array_keys($courses);
 145             return grade_get_course_grade($userid, $courseids);
 146         }
 147         if (!is_numeric($courseid_or_ids)) {
 148             return false;
 149         }
 150         if (!$grades = grade_get_course_grade($userid, array($courseid_or_ids))) {
 151             return false;
 152         } else {
 153             // only one grade - not array
 154             $grade = reset($grades);
 155             return $grade;
 156         }
 157     }
 158
 159     foreach ($courseid_or_ids as $courseid) {
 160         $grade_item = grade_item::fetch_course_item($courseid);
 161         $course_items[$grade_item->courseid] = $grade_item;
 162     }
 163
 164     $grades = array();
 165     foreach ($course_items as $grade_item) {
 166         if ($grade_item->needsupdate) {
 167             grade_regrade_final_grades($courseid);
 168         }
 169
 170         $item = new stdClass();
 171         $item->scaleid    = $grade_item->scaleid;
 172         $item->name       = $grade_item->get_name();
 173         $item->grademin   = $grade_item->grademin;
 174         $item->grademax   = $grade_item->grademax;
 175         $item->gradepass  = $grade_item->gradepass;
 176         $item->locked     = $grade_item->is_locked();
 177         $item->hidden     = $grade_item->is_hidden();
 178
 179         switch ($grade_item->gradetype) {
 180             case GRADE_TYPE_NONE:
 181                 continue;
 182
 183             case GRADE_TYPE_VALUE:
 184                 $item->scaleid = 0;
 185                 break;
 186
 187             case GRADE_TYPE_TEXT:
 188                 $item->scaleid   = 0;
 189                 $item->grademin   = 0;
 190                 $item->grademax   = 0;
 191                 $item->gradepass  = 0;
 192                 break;
 193         }
 194         $grade_grade = new grade_grade(array('userid'=>$userid, 'itemid'=>$grade_item->id));
 195         $grade_grade->grade_item =& $grade_item;
 196
 197         $grade = new stdClass();
 198         $grade->grade          = $grade_grade->finalgrade;
 199         $grade->locked         = $grade_grade->is_locked();
 200         $grade->hidden         = $grade_grade->is_hidden();
 201         $grade->overridden     = $grade_grade->overridden;
 202         $grade->feedback       = $grade_grade->feedback;
 203         $grade->feedbackformat = $grade_grade->feedbackformat;
 204         $grade->usermodified   = $grade_grade->usermodified;
 205         $grade->dategraded     = $grade_grade->get_dategraded();
 206         $grade->item           = $item;
 207
 208         // create text representation of grade
 209         if ($grade_item->needsupdate) {
 210             $grade->grade          = false;
 211             $grade->str_grade      = get_string('error');
 212             $grade->str_long_grade = $grade->str_grade;
 213
 214         } else if (is_null($grade->grade)) {
 215             $grade->str_grade      = '-';
 216             $grade->str_long_grade = $grade->str_grade;
 217
 218         } else {
 219             $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
 220             if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
 221                 $grade->str_long_grade = $grade->str_grade;
 222             } else {
 223                 $a = new stdClass();
 224                 $a->grade = $grade->str_grade;
 225                 $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
 226                 $grade->str_long_grade = get_string('gradelong', 'grades', $a);
 227             }
 228         }
 229
 230         // create html representation of feedback
 231         if (is_null($grade->feedback)) {
 232             $grade->str_feedback = '';
 233         } else {
 234             $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 235         }
 236
 237         $grades[$grade_item->courseid] = $grade;
 238     }
 239
 240     return $grades;
 241 }
 242
 243 /**
 244  * Returns all grade items (including outcomes) or main item for a given activity identified by $cm object.
 245  *
 246  * @param cm_info $cm A course module object (preferably with modname property)
 247  * @param bool $only_main_item Limit the search to the primary grade item for the activity, 'itemnumber'==0
 248  * @return mixed An array of grade item instances, one grade item if $only_main_item == true, false if error or not found
 249  */
 250 function grade_get_grade_items_for_activity($cm, $only_main_item=false) {
 251     global $CFG, $DB;
 252
 253     if (!isset($cm->modname)) {
 254         $params = array($cm->id);
 255         $cm = $DB->get_record_sql("SELECT cm.*, md.name as modname
 256                                     FROM {course_modules} cm,
 257                                          {modules} md
 258                                    WHERE cm.id = ? AND md.id = cm.module", $params);
 259     }
 260
 261
 262     if (empty($cm) or empty($cm->instance) or empty($cm->course)) {
 263         debugging("Incorrect cm parameter in grade_get_grade_items_for_activity()!");
 264         return false;
 265     }
 266
 267     if ($only_main_item) {
 268         return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course, 'itemnumber'=>0));
 269     } else {
 270         return grade_item::fetch_all(array('itemtype'=>'mod', 'itemmodule'=>$cm->modname, 'iteminstance'=>$cm->instance, 'courseid'=>$cm->course));
 271     }
 272 }
 273
 274 /**
 275  * Returns whether or not a user received grades in main grade item for given activity
 276  *
 277  * @param cm_info $cm The activity context module
 278  * @param int $userid The user ID
 279  * @return bool True if graded, false if user not graded yet
 280  */
 281 function grade_is_user_graded_in_activity($cm, $userid) {
 282
 283     $grade_items = grade_get_grade_items_for_activity($cm, true);
 284     if (empty($grade_items)) {
 285         return false;
 286     }
 287
 288     $grade_item = reset($grade_items);
 289
 290     if ($grade_item->gradetype == GRADE_TYPE_NONE) {
 291         return false;
 292     }
 293
 294     if ($grade_item->needsupdate) {
 295         // activity items should never fail to regrade
 296         grade_regrade_final_grades($grade_item->courseid);
 297     }
 298
 299     if (!$grade = $grade_item->get_final($userid)) {
 300         return false;
 301     }
 302
 303     if (is_null($grade->finalgrade)) {
 304         return false;
 305     }
 306
 307     return true;
 308 }
 309
 310 /**
 311  * Returns an array of activities (defined as $cm objects) which are gradeable from gradebook, outcomes are ignored.
 312  *
 313  * @param int $courseid If provided then restrict to one course.
 314  * @param string $modulename If defined (could be 'forum', 'assignment' etc) then only that type are returned.
 315  * @return array $cm objects
 316  */
 317 function grade_get_gradable_activities($courseid, $modulename='') {
 318     global $CFG, $DB;
 319
 320     if (empty($modulename)) {
 321         if (!$modules = $DB->get_records('modules', array('visible' => '1'))) {
 322             return false;
 323         }
 324         $result = array();
 325         foreach ($modules as $module) {
 326             if ($cms = grade_get_gradable_activities($courseid, $module->name)) {
 327                 $result =  $result + $cms;
 328             }
 329         }
 330         if (empty($result)) {
 331             return false;
 332         } else {
 333             return $result;
 334         }
 335     }
 336
 337     $params = array($courseid, $modulename, GRADE_TYPE_NONE, $modulename);
 338     $sql = "SELECT cm.*, m.name, md.name as modname
 339               FROM {grade_items} gi, {course_modules} cm, {modules} md, {{$modulename}} m
 340              WHERE gi.courseid = ? AND
 341                    gi.itemtype = 'mod' AND
 342                    gi.itemmodule = ? AND
 343                    gi.itemnumber = 0 AND
 344                    gi.gradetype != ? AND
 345                    gi.iteminstance = cm.instance AND
 346                    cm.instance = m.id AND
 347                    md.name = ? AND
 348                    md.id = cm.module";
 349
 350     return $DB->get_records_sql($sql, $params);
 351 }
 352