lib/gradelib.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  * Library of functions for gradebook - both public and internal
  19  *
  20  * @package   core_grades
  21  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 global $CFG;
  28
  29 /** Include essential files */
  30 require_once($CFG->libdir . '/grade/constants.php');
  31
  32 require_once($CFG->libdir . '/grade/grade_category.php');
  33 require_once($CFG->libdir . '/grade/grade_item.php');
  34 require_once($CFG->libdir . '/grade/grade_grade.php');
  35 require_once($CFG->libdir . '/grade/grade_scale.php');
  36 require_once($CFG->libdir . '/grade/grade_outcome.php');
  37
  38 /////////////////////////////////////////////////////////////////////
  39 ///// Start of public API for communication with modules/blocks /////
  40 /////////////////////////////////////////////////////////////////////
  41
  42 /**
  43  * Submit new or update grade; update/create grade_item definition. Grade must have userid specified,
  44  * rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded'.
  45  * Missing property or key means does not change the existing value.
  46  *
  47  * Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',
  48  * 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted' and 'hidden'. 'reset' means delete all current grades including locked ones.
  49  *
  50  * Manual, course or category items can not be updated by this function.
  51  *
  52  * @category grade
  53  * @param string $source Source of the grade such as 'mod/assignment'
  54  * @param int    $courseid ID of course
  55  * @param string $itemtype Type of grade item. For example, mod or block
  56  * @param string $itemmodule More specific then $itemtype. For example, assignment or forum. May be NULL for some item types
  57  * @param int    $iteminstance Instance ID of graded item
  58  * @param int    $itemnumber Most probably 0. Modules can use other numbers when having more than one grade for each user
  59  * @param mixed  $grades Grade (object, array) or several grades (arrays of arrays or objects), NULL if updating grade_item definition only
  60  * @param mixed  $itemdetails Object or array describing the grading item, NULL if no change
  61  * @param bool   $isbulkupdate If bulk grade update is happening.
  62  * @return int Returns GRADE_UPDATE_OK, GRADE_UPDATE_FAILED, GRADE_UPDATE_MULTIPLE or GRADE_UPDATE_ITEM_LOCKED
  63  */
  64 function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades = null,
  65         $itemdetails = null, $isbulkupdate = false) {
  66     global $USER, $CFG, $DB;
  67
  68     // only following grade_item properties can be changed in this function
  69     $allowed = array('itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted', 'hidden');
  70     // list of 10,5 numeric fields
  71     $floats  = array('grademin', 'grademax', 'multfactor', 'plusfactor');
  72
  73     // grade item identification
  74     $params = compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber');
  75
  76     if (is_null($courseid) or is_null($itemtype)) {
  77         debugging('Missing courseid or itemtype');
  78         return GRADE_UPDATE_FAILED;
  79     }
  80
  81     if (!$gradeitems = grade_item::fetch_all($params)) {
  82         // create a new one
  83         $gradeitem = false;
  84     } else if (count($gradeitems) == 1) {
  85         $gradeitem = reset($gradeitems);
  86         unset($gradeitems); // Release memory.
  87     } else {
  88         debugging('Found more than one grade item');
  89         return GRADE_UPDATE_MULTIPLE;
  90     }
  91
  92     if (!empty($itemdetails['deleted'])) {
  93         if ($gradeitem) {
  94             if ($gradeitem->delete($source)) {
  95                 return GRADE_UPDATE_OK;
  96             } else {
  97                 return GRADE_UPDATE_FAILED;
  98             }
  99         }
 100         return GRADE_UPDATE_OK;
 101     }
 102
 103 /// Create or update the grade_item if needed
 104
 105     if (!$gradeitem) {
 106         if ($itemdetails) {
 107             $itemdetails = (array)$itemdetails;
 108
 109             // grademin and grademax ignored when scale specified
 110             if (array_key_exists('scaleid', $itemdetails)) {
 111                 if ($itemdetails['scaleid']) {
 112                     unset($itemdetails['grademin']);
 113                     unset($itemdetails['grademax']);
 114                 }
 115             }
 116
 117             foreach ($itemdetails as $k=>$v) {
 118                 if (!in_array($k, $allowed)) {
 119                     // ignore it
 120                     continue;
 121                 }
 122                 if ($k == 'gradetype' and $v == GRADE_TYPE_NONE) {
 123                     // no grade item needed!
 124                     return GRADE_UPDATE_OK;
 125                 }
 126                 $params[$k] = $v;
 127             }
 128         }
 129         $gradeitem = new grade_item($params);
 130         $gradeitem->insert(null, $isbulkupdate);
 131
 132     } else {
 133         if ($gradeitem->is_locked()) {
 134             // no notice() here, test returned value instead!
 135             return GRADE_UPDATE_ITEM_LOCKED;
 136         }
 137
 138         if ($itemdetails) {
 139             $itemdetails = (array)$itemdetails;
 140             $update = false;
 141             foreach ($itemdetails as $k=>$v) {
 142                 if (!in_array($k, $allowed)) {
 143                     // ignore it
 144                     continue;
 145                 }
 146                 if (in_array($k, $floats)) {
 147                     if (grade_floats_different($gradeitem->{$k}, $v)) {
 148                         $gradeitem->{$k} = $v;
 149                         $update = true;
 150                     }
 151
 152                 } else {
 153                     if ($gradeitem->{$k} != $v) {
 154                         $gradeitem->{$k} = $v;
 155                         $update = true;
 156                     }
 157                 }
 158             }
 159             if ($update) {
 160                 $gradeitem->update(null, $isbulkupdate);
 161             }
 162         }
 163     }
 164
 165 /// reset grades if requested
 166     if (!empty($itemdetails['reset'])) {
 167         $gradeitem->delete_all_grades('reset');
 168         return GRADE_UPDATE_OK;
 169     }
 170
 171 /// Some extra checks
 172     // do we use grading?
 173     if ($gradeitem->gradetype == GRADE_TYPE_NONE) {
 174         return GRADE_UPDATE_OK;
 175     }
 176
 177     // no grade submitted
 178     if (empty($grades)) {
 179         return GRADE_UPDATE_OK;
 180     }
 181
 182 /// Finally start processing of grades
 183     if (is_object($grades)) {
 184         $grades = array($grades->userid=>$grades);
 185     } else {
 186         if (array_key_exists('userid', $grades)) {
 187             $grades = array($grades['userid']=>$grades);
 188         }
 189     }
 190
 191 /// normalize and verify grade array
 192     foreach($grades as $k=>$g) {
 193         if (!is_array($g)) {
 194             $g = (array)$g;
 195             $grades[$k] = $g;
 196         }
 197
 198         if (empty($g['userid']) or $k != $g['userid']) {
 199             debugging('Incorrect grade array index, must be user id! Grade ignored.');
 200             unset($grades[$k]);
 201         }
 202     }
 203
 204     if (empty($grades)) {
 205         return GRADE_UPDATE_FAILED;
 206     }
 207
 208     $count = count($grades);
 209     if ($count > 0 and $count < 200) {
 210         list($uids, $params) = $DB->get_in_or_equal(array_keys($grades), SQL_PARAMS_NAMED, $start='uid');
 211         $params['gid'] = $gradeitem->id;
 212         $sql = "SELECT * FROM {grade_grades} WHERE itemid = :gid AND userid $uids";
 213
 214     } else {
 215         $sql = "SELECT * FROM {grade_grades} WHERE itemid = :gid";
 216         $params = array('gid' => $gradeitem->id);
 217     }
 218
 219     $rs = $DB->get_recordset_sql($sql, $params);
 220
 221     $failed = false;
 222
 223     while (count($grades) > 0) {
 224         $gradegrade = null;
 225         $grade       = null;
 226
 227         foreach ($rs as $gd) {
 228
 229             $userid = $gd->userid;
 230             if (!isset($grades[$userid])) {
 231                 // this grade not requested, continue
 232                 continue;
 233             }
 234             // existing grade requested
 235             $grade       = $grades[$userid];
 236             $gradegrade = new grade_grade($gd, false);
 237             unset($grades[$userid]);
 238             break;
 239         }
 240
 241         if (is_null($gradegrade)) {
 242             if (count($grades) == 0) {
 243                 // No more grades to process.
 244                 break;
 245             }
 246
 247             $grade       = reset($grades);
 248             $userid      = $grade['userid'];
 249             $gradegrade = new grade_grade(array('itemid' => $gradeitem->id, 'userid' => $userid), false);
 250             $gradegrade->load_optional_fields(); // add feedback and info too
 251             unset($grades[$userid]);
 252         }
 253
 254         $rawgrade       = false;
 255         $feedback       = false;
 256         $feedbackformat = FORMAT_MOODLE;
 257         $feedbackfiles = [];
 258         $usermodified   = $USER->id;
 259         $datesubmitted  = null;
 260         $dategraded     = null;
 261
 262         if (array_key_exists('rawgrade', $grade)) {
 263             $rawgrade = $grade['rawgrade'];
 264         }
 265
 266         if (array_key_exists('feedback', $grade)) {
 267             $feedback = $grade['feedback'];
 268         }
 269
 270         if (array_key_exists('feedbackformat', $grade)) {
 271             $feedbackformat = $grade['feedbackformat'];
 272         }
 273
 274         if (array_key_exists('feedbackfiles', $grade)) {
 275             $feedbackfiles = $grade['feedbackfiles'];
 276         }
 277
 278         if (array_key_exists('usermodified', $grade)) {
 279             $usermodified = $grade['usermodified'];
 280         }
 281
 282         if (array_key_exists('datesubmitted', $grade)) {
 283             $datesubmitted = $grade['datesubmitted'];
 284         }
 285
 286         if (array_key_exists('dategraded', $grade)) {
 287             $dategraded = $grade['dategraded'];
 288         }
 289
 290         // update or insert the grade
 291         if (!$gradeitem->update_raw_grade($userid, $rawgrade, $source, $feedback, $feedbackformat, $usermodified,
 292                 $dategraded, $datesubmitted, $gradegrade, $feedbackfiles, $isbulkupdate)) {
 293             $failed = true;
 294         }
 295     }
 296
 297     if ($rs) {
 298         $rs->close();
 299     }
 300
 301     if (!$failed) {
 302         return GRADE_UPDATE_OK;
 303     } else {
 304         return GRADE_UPDATE_FAILED;
 305     }
 306 }
 307
 308 /**
 309  * Updates a user's outcomes. Manual outcomes can not be updated.
 310  *
 311  * @category grade
 312  * @param string $source Source of the grade such as 'mod/assignment'
 313  * @param int    $courseid ID of course
 314  * @param string $itemtype Type of grade item. For example, 'mod' or 'block'
 315  * @param string $itemmodule More specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types
 316  * @param int    $iteminstance Instance ID of graded item. For example the forum ID.
 317  * @param int    $userid ID of the graded user
 318  * @param array  $data Array consisting of grade item itemnumber ({@link grade_update()}) => outcomegrade
 319  * @return bool returns true if grade items were found and updated successfully
 320  */
 321 function grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data) {
 322     if ($items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 323         $result = true;
 324         foreach ($items as $item) {
 325             if (!array_key_exists($item->itemnumber, $data)) {
 326                 continue;
 327             }
 328             $grade = $data[$item->itemnumber] < 1 ? null : $data[$item->itemnumber];
 329             $result = ($item->update_final_grade($userid, $grade, $source) && $result);
 330         }
 331         return $result;
 332     }
 333     return false; //grade items not found
 334 }
 335
 336 /**
 337  * Return true if the course needs regrading.
 338  *
 339  * @param int $courseid The course ID
 340  * @return bool true if course grades need updating.
 341  */
 342 function grade_needs_regrade_final_grades($courseid) {
 343     $course_item = grade_item::fetch_course_item($courseid);
 344     return $course_item->needsupdate;
 345 }
 346
 347 /**
 348  * Return true if the regrade process is likely to be time consuming and
 349  * will therefore require the progress bar.
 350  *
 351  * @param int $courseid The course ID
 352  * @return bool Whether the regrade process is likely to be time consuming
 353  */
 354 function grade_needs_regrade_progress_bar($courseid) {
 355     global $DB;
 356     $grade_items = grade_item::fetch_all(array('courseid' => $courseid));
 357
 358     list($sql, $params) = $DB->get_in_or_equal(array_keys($grade_items), SQL_PARAMS_NAMED, 'gi');
 359     $gradecount = $DB->count_records_select('grade_grades', 'itemid ' . $sql, $params);
 360
 361     // This figure may seem arbitrary, but after analysis it seems that 100 grade_grades can be calculated in ~= 0.5 seconds.
 362     // Any longer than this and we want to show the progress bar.
 363     return $gradecount > 100;
 364 }
 365
 366 /**
 367  * Check whether regarding of final grades is required and, if so, perform the regrade.
 368  *
 369  * If the regrade is expected to be time consuming (see grade_needs_regrade_progress_bar), then this
 370  * function will output the progress bar, and redirect to the current PAGE->url after regrading
 371  * completes. Otherwise the regrading will happen immediately and the page will be loaded as per
 372  * normal.
 373  *
 374  * A callback may be specified, which is called if regrading has taken place.
 375  * The callback may optionally return a URL which will be redirected to when the progress bar is present.
 376  *
 377  * @param stdClass $course The course to regrade
 378  * @param callable $callback A function to call if regrading took place
 379  * @return moodle_url The URL to redirect to if redirecting
 380  */
 381 function grade_regrade_final_grades_if_required($course, callable $callback = null) {
 382     global $PAGE, $OUTPUT;
 383
 384     if (!grade_needs_regrade_final_grades($course->id)) {
 385         return false;
 386     }
 387
 388     if (grade_needs_regrade_progress_bar($course->id)) {
 389         if ($PAGE->state !== moodle_page::STATE_IN_BODY) {
 390             $PAGE->set_heading($course->fullname);
 391             echo $OUTPUT->header();
 392         }
 393         echo $OUTPUT->heading(get_string('recalculatinggrades', 'grades'));
 394         $progress = new \core\progress\display(true);
 395         $status = grade_regrade_final_grades($course->id, null, null, $progress);
 396
 397         // Show regrade errors and set the course to no longer needing regrade (stop endless loop).
 398         if (is_array($status)) {
 399             foreach ($status as $error) {
 400                 $errortext = new \core\output\notification($error, \core\output\notification::NOTIFY_ERROR);
 401                 echo $OUTPUT->render($errortext);
 402             }
 403             $courseitem = grade_item::fetch_course_item($course->id);
 404             $courseitem->regrading_finished();
 405         }
 406
 407         if ($callback) {
 408             //
 409             $url = call_user_func($callback);
 410         }
 411
 412         if (empty($url)) {
 413             $url = $PAGE->url;
 414         }
 415
 416         echo $OUTPUT->continue_button($url);
 417         echo $OUTPUT->footer();
 418         die();
 419     } else {
 420         $result = grade_regrade_final_grades($course->id);
 421         if ($callback) {
 422             call_user_func($callback);
 423         }
 424         return $result;
 425     }
 426 }
 427
 428 /**
 429  * Returns grading information for given activity, optionally with user grades
 430  * Manual, course or category items can not be queried.
 431  *
 432  * @category grade
 433  * @param int    $courseid ID of course
 434  * @param string $itemtype Type of grade item. For example, 'mod' or 'block'
 435  * @param string $itemmodule More specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types
 436  * @param int    $iteminstance ID of the item module
 437  * @param mixed  $userid_or_ids Either a single user ID, an array of user IDs or null. If user ID or IDs are not supplied returns information about grade_item
 438  * @return array Array of grade information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers
 439  */
 440 function grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=null) {
 441     global $CFG;
 442
 443     $return = new stdClass();
 444     $return->items    = array();
 445     $return->outcomes = array();
 446
 447     $course_item = grade_item::fetch_course_item($courseid);
 448     $needsupdate = array();
 449     if ($course_item->needsupdate) {
 450         $result = grade_regrade_final_grades($courseid);
 451         if ($result !== true) {
 452             $needsupdate = array_keys($result);
 453         }
 454     }
 455
 456     if ($grade_items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 457         foreach ($grade_items as $grade_item) {
 458             $decimalpoints = null;
 459
 460             if (empty($grade_item->outcomeid)) {
 461                 // prepare information about grade item
 462                 $item = new stdClass();
 463                 $item->id = $grade_item->id;
 464                 $item->itemnumber = $grade_item->itemnumber;
 465                 $item->itemtype  = $grade_item->itemtype;
 466                 $item->itemmodule = $grade_item->itemmodule;
 467                 $item->iteminstance = $grade_item->iteminstance;
 468                 $item->scaleid    = $grade_item->scaleid;
 469                 $item->name       = $grade_item->get_name();
 470                 $item->grademin   = $grade_item->grademin;
 471                 $item->grademax   = $grade_item->grademax;
 472                 $item->gradepass  = $grade_item->gradepass;
 473                 $item->locked     = $grade_item->is_locked();
 474                 $item->hidden     = $grade_item->is_hidden();
 475                 $item->grades     = array();
 476
 477                 switch ($grade_item->gradetype) {
 478                     case GRADE_TYPE_NONE:
 479                         break;
 480
 481                     case GRADE_TYPE_VALUE:
 482                         $item->scaleid = 0;
 483                         break;
 484
 485                     case GRADE_TYPE_TEXT:
 486                         $item->scaleid   = 0;
 487                         $item->grademin   = 0;
 488                         $item->grademax   = 0;
 489                         $item->gradepass  = 0;
 490                         break;
 491                 }
 492
 493                 if (empty($userid_or_ids)) {
 494                     $userids = array();
 495
 496                 } else if (is_array($userid_or_ids)) {
 497                     $userids = $userid_or_ids;
 498
 499                 } else {
 500                     $userids = array($userid_or_ids);
 501                 }
 502
 503                 if ($userids) {
 504                     $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
 505                     foreach ($userids as $userid) {
 506                         $grade_grades[$userid]->grade_item =& $grade_item;
 507
 508                         $grade = new stdClass();
 509                         $grade->grade          = $grade_grades[$userid]->finalgrade;
 510                         $grade->locked         = $grade_grades[$userid]->is_locked();
 511                         $grade->hidden         = $grade_grades[$userid]->is_hidden();
 512                         $grade->overridden     = $grade_grades[$userid]->overridden;
 513                         $grade->feedback       = $grade_grades[$userid]->feedback;
 514                         $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
 515                         $grade->usermodified   = $grade_grades[$userid]->usermodified;
 516                         $grade->datesubmitted  = $grade_grades[$userid]->get_datesubmitted();
 517                         $grade->dategraded     = $grade_grades[$userid]->get_dategraded();
 518
 519                         // create text representation of grade
 520                         if ($grade_item->gradetype == GRADE_TYPE_TEXT or $grade_item->gradetype == GRADE_TYPE_NONE) {
 521                             $grade->grade          = null;
 522                             $grade->str_grade      = '-';
 523                             $grade->str_long_grade = $grade->str_grade;
 524
 525                         } else if (in_array($grade_item->id, $needsupdate)) {
 526                             $grade->grade          = false;
 527                             $grade->str_grade      = get_string('error');
 528                             $grade->str_long_grade = $grade->str_grade;
 529
 530                         } else if (is_null($grade->grade)) {
 531                             $grade->str_grade      = '-';
 532                             $grade->str_long_grade = $grade->str_grade;
 533
 534                         } else {
 535                             $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
 536                             if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
 537                                 $grade->str_long_grade = $grade->str_grade;
 538                             } else {
 539                                 $a = new stdClass();
 540                                 $a->grade = $grade->str_grade;
 541                                 $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
 542                                 $grade->str_long_grade = get_string('gradelong', 'grades', $a);
 543                             }
 544                         }
 545
 546                         // create html representation of feedback
 547                         if (is_null($grade->feedback)) {
 548                             $grade->str_feedback = '';
 549                         } else {
 550                             $feedback = file_rewrite_pluginfile_urls(
 551                                 $grade->feedback,
 552                                 'pluginfile.php',
 553                                 $grade_grades[$userid]->get_context()->id,
 554                                 GRADE_FILE_COMPONENT,
 555                                 GRADE_FEEDBACK_FILEAREA,
 556                                 $grade_grades[$userid]->id
 557                             );
 558
 559                             $grade->str_feedback = format_text($feedback, $grade->feedbackformat,
 560                                 ['context' => $grade_grades[$userid]->get_context()]);
 561                         }
 562
 563                         $item->grades[$userid] = $grade;
 564                     }
 565                 }
 566                 $return->items[$grade_item->itemnumber] = $item;
 567
 568             } else {
 569                 if (!$grade_outcome = grade_outcome::fetch(array('id'=>$grade_item->outcomeid))) {
 570                     debugging('Incorect outcomeid found');
 571                     continue;
 572                 }
 573
 574                 // outcome info
 575                 $outcome = new stdClass();
 576                 $outcome->id = $grade_item->id;
 577                 $outcome->itemnumber = $grade_item->itemnumber;
 578                 $outcome->itemtype   = $grade_item->itemtype;
 579                 $outcome->itemmodule = $grade_item->itemmodule;
 580                 $outcome->iteminstance = $grade_item->iteminstance;
 581                 $outcome->scaleid    = $grade_outcome->scaleid;
 582                 $outcome->name       = $grade_outcome->get_name();
 583                 $outcome->locked     = $grade_item->is_locked();
 584                 $outcome->hidden     = $grade_item->is_hidden();
 585
 586                 if (empty($userid_or_ids)) {
 587                     $userids = array();
 588                 } else if (is_array($userid_or_ids)) {
 589                     $userids = $userid_or_ids;
 590                 } else {
 591                     $userids = array($userid_or_ids);
 592                 }
 593
 594                 if ($userids) {
 595                     $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
 596                     foreach ($userids as $userid) {
 597                         $grade_grades[$userid]->grade_item =& $grade_item;
 598
 599                         $grade = new stdClass();
 600                         $grade->grade          = $grade_grades[$userid]->finalgrade;
 601                         $grade->locked         = $grade_grades[$userid]->is_locked();
 602                         $grade->hidden         = $grade_grades[$userid]->is_hidden();
 603                         $grade->feedback       = $grade_grades[$userid]->feedback;
 604                         $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
 605                         $grade->usermodified   = $grade_grades[$userid]->usermodified;
 606                         $grade->datesubmitted  = $grade_grades[$userid]->get_datesubmitted();
 607                         $grade->dategraded     = $grade_grades[$userid]->get_dategraded();
 608
 609                         // create text representation of grade
 610                         if (in_array($grade_item->id, $needsupdate)) {
 611                             $grade->grade     = false;
 612                             $grade->str_grade = get_string('error');
 613
 614                         } else if (is_null($grade->grade)) {
 615                             $grade->grade = 0;
 616                             $grade->str_grade = get_string('nooutcome', 'grades');
 617
 618                         } else {
 619                             $grade->grade = (int)$grade->grade;
 620                             $scale = $grade_item->load_scale();
 621                             $grade->str_grade = format_string($scale->scale_items[(int)$grade->grade-1]);
 622                         }
 623
 624                         // create html representation of feedback
 625                         if (is_null($grade->feedback)) {
 626                             $grade->str_feedback = '';
 627                         } else {
 628                             $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 629                         }
 630
 631                         $outcome->grades[$userid] = $grade;
 632                     }
 633                 }
 634
 635                 if (isset($return->outcomes[$grade_item->itemnumber])) {
 636                     // itemnumber duplicates - lets fix them!
 637                     $newnumber = $grade_item->itemnumber + 1;
 638                     while(grade_item::fetch(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid, 'itemnumber'=>$newnumber))) {
 639                         $newnumber++;
 640                     }
 641                     $outcome->itemnumber    = $newnumber;
 642                     $grade_item->itemnumber = $newnumber;
 643                     $grade_item->update('system');
 644                 }
 645
 646                 $return->outcomes[$grade_item->itemnumber] = $outcome;
 647
 648             }
 649         }
 650     }
 651
 652     // sort results using itemnumbers
 653     ksort($return->items, SORT_NUMERIC);
 654     ksort($return->outcomes, SORT_NUMERIC);
 655
 656     return $return;
 657 }
 658
 659 ///////////////////////////////////////////////////////////////////
 660 ///// End of public API for communication with modules/blocks /////
 661 ///////////////////////////////////////////////////////////////////
 662
 663
 664
 665 ///////////////////////////////////////////////////////////////////
 666 ///// Internal API: used by gradebook plugins and Moodle core /////
 667 ///////////////////////////////////////////////////////////////////
 668
 669 /**
 670  * Returns a  course gradebook setting
 671  *
 672  * @param int $courseid
 673  * @param string $name of setting, maybe null if reset only
 674  * @param string $default value to return if setting is not found
 675  * @param bool $resetcache force reset of internal static cache
 676  * @return string value of the setting, $default if setting not found, NULL if supplied $name is null
 677  */
 678 function grade_get_setting($courseid, $name, $default=null, $resetcache=false) {
 679     global $DB;
 680
 681     $cache = cache::make('core', 'gradesetting');
 682     $gradesetting = $cache->get($courseid) ?: array();
 683
 684     if ($resetcache or empty($gradesetting)) {
 685         $gradesetting = array();
 686         $cache->set($courseid, $gradesetting);
 687
 688     } else if (is_null($name)) {
 689         return null;
 690
 691     } else if (array_key_exists($name, $gradesetting)) {
 692         return $gradesetting[$name];
 693     }
 694
 695     if (!$data = $DB->get_record('grade_settings', array('courseid'=>$courseid, 'name'=>$name))) {
 696         $result = null;
 697     } else {
 698         $result = $data->value;
 699     }
 700
 701     if (is_null($result)) {
 702         $result = $default;
 703     }
 704
 705     $gradesetting[$name] = $result;
 706     $cache->set($courseid, $gradesetting);
 707     return $result;
 708 }
 709
 710 /**
 711  * Returns all course gradebook settings as object properties
 712  *
 713  * @param int $courseid
 714  * @return object
 715  */
 716 function grade_get_settings($courseid) {
 717     global $DB;
 718
 719      $settings = new stdClass();
 720      $settings->id = $courseid;
 721
 722     if ($records = $DB->get_records('grade_settings', array('courseid'=>$courseid))) {
 723         foreach ($records as $record) {
 724             $settings->{$record->name} = $record->value;
 725         }
 726     }
 727
 728     return $settings;
 729 }
 730
 731 /**
 732  * Add, update or delete a course gradebook setting
 733  *
 734  * @param int $courseid The course ID
 735  * @param string $name Name of the setting
 736  * @param string $value Value of the setting. NULL means delete the setting.
 737  */
 738 function grade_set_setting($courseid, $name, $value) {
 739     global $DB;
 740
 741     if (is_null($value)) {
 742         $DB->delete_records('grade_settings', array('courseid'=>$courseid, 'name'=>$name));
 743
 744     } else if (!$existing = $DB->get_record('grade_settings', array('courseid'=>$courseid, 'name'=>$name))) {
 745         $data = new stdClass();
 746         $data->courseid = $courseid;
 747         $data->name     = $name;
 748         $data->value    = $value;
 749         $DB->insert_record('grade_settings', $data);
 750
 751     } else {
 752         $data = new stdClass();
 753         $data->id       = $existing->id;
 754         $data->value    = $value;
 755         $DB->update_record('grade_settings', $data);
 756     }
 757
 758     grade_get_setting($courseid, null, null, true); // reset the cache
 759 }
 760
 761 /**
 762  * Returns string representation of grade value
 763  *
 764  * @param float|null $value The grade value
 765  * @param object $grade_item Grade item object passed by reference to prevent scale reloading
 766  * @param bool $localized use localised decimal separator
 767  * @param int $displaytype type of display. For example GRADE_DISPLAY_TYPE_REAL, GRADE_DISPLAY_TYPE_PERCENTAGE, GRADE_DISPLAY_TYPE_LETTER
 768  * @param int $decimals The number of decimal places when displaying float values
 769  * @return string
 770  */
 771 function grade_format_gradevalue(?float $value, &$grade_item, $localized=true, $displaytype=null, $decimals=null) {
 772     if ($grade_item->gradetype == GRADE_TYPE_NONE or $grade_item->gradetype == GRADE_TYPE_TEXT) {
 773         return '';
 774     }
 775
 776     // no grade yet?
 777     if (is_null($value)) {
 778         return '-';
 779     }
 780
 781     if ($grade_item->gradetype != GRADE_TYPE_VALUE and $grade_item->gradetype != GRADE_TYPE_SCALE) {
 782         //unknown type??
 783         return '';
 784     }
 785
 786     if (is_null($displaytype)) {
 787         $displaytype = $grade_item->get_displaytype();
 788     }
 789
 790     if (is_null($decimals)) {
 791         $decimals = $grade_item->get_decimals();
 792     }
 793
 794     switch ($displaytype) {
 795         case GRADE_DISPLAY_TYPE_REAL:
 796             return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized);
 797
 798         case GRADE_DISPLAY_TYPE_PERCENTAGE:
 799             return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized);
 800
 801         case GRADE_DISPLAY_TYPE_LETTER:
 802             return grade_format_gradevalue_letter($value, $grade_item);
 803
 804         case GRADE_DISPLAY_TYPE_REAL_PERCENTAGE:
 805             return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ' (' .
 806                     grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ')';
 807
 808         case GRADE_DISPLAY_TYPE_REAL_LETTER:
 809             return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ' (' .
 810                     grade_format_gradevalue_letter($value, $grade_item) . ')';
 811
 812         case GRADE_DISPLAY_TYPE_PERCENTAGE_REAL:
 813             return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ' (' .
 814                     grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ')';
 815
 816         case GRADE_DISPLAY_TYPE_LETTER_REAL:
 817             return grade_format_gradevalue_letter($value, $grade_item) . ' (' .
 818                     grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ')';
 819
 820         case GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE:
 821             return grade_format_gradevalue_letter($value, $grade_item) . ' (' .
 822                     grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ')';
 823
 824         case GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER:
 825             return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ' (' .
 826                     grade_format_gradevalue_letter($value, $grade_item) . ')';
 827         default:
 828             return '';
 829     }
 830 }
 831
 832 /**
 833  * Returns a float representation of a grade value
 834  *
 835  * @param float|null $value The grade value
 836  * @param object $grade_item Grade item object
 837  * @param int $decimals The number of decimal places
 838  * @param bool $localized use localised decimal separator
 839  * @return string
 840  */
 841 function grade_format_gradevalue_real(?float $value, $grade_item, $decimals, $localized) {
 842     if ($grade_item->gradetype == GRADE_TYPE_SCALE) {
 843         if (!$scale = $grade_item->load_scale()) {
 844             return get_string('error');
 845         }
 846
 847         $value = $grade_item->bounded_grade($value);
 848         return format_string($scale->scale_items[$value-1]);
 849
 850     } else {
 851         return format_float($value, $decimals, $localized);
 852     }
 853 }
 854
 855 /**
 856  * Returns a percentage representation of a grade value
 857  *
 858  * @param float|null $value The grade value
 859  * @param object $grade_item Grade item object
 860  * @param int $decimals The number of decimal places
 861  * @param bool $localized use localised decimal separator
 862  * @return string
 863  */
 864 function grade_format_gradevalue_percentage(?float $value, $grade_item, $decimals, $localized) {
 865     $min = $grade_item->grademin;
 866     $max = $grade_item->grademax;
 867     if ($min == $max) {
 868         return '';
 869     }
 870     $value = $grade_item->bounded_grade($value);
 871     $percentage = (($value-$min)*100)/($max-$min);
 872     return format_float($percentage, $decimals, $localized).' %';
 873 }
 874
 875 /**
 876  * Returns a letter grade representation of a grade value
 877  * The array of grade letters used is produced by {@link grade_get_letters()} using the course context
 878  *
 879  * @param float|null $value The grade value
 880  * @param object $grade_item Grade item object
 881  * @return string
 882  */
 883 function grade_format_gradevalue_letter(?float $value, $grade_item) {
 884     global $CFG;
 885     $context = context_course::instance($grade_item->courseid, IGNORE_MISSING);
 886     if (!$letters = grade_get_letters($context)) {
 887         return ''; // no letters??
 888     }
 889
 890     if (is_null($value)) {
 891         return '-';
 892     }
 893
 894     $value = grade_grade::standardise_score($value, $grade_item->grademin, $grade_item->grademax, 0, 100);
 895     $value = bounded_number(0, $value, 100); // just in case
 896
 897     $gradebookcalculationsfreeze = 'gradebook_calculations_freeze_' . $grade_item->courseid;
 898
 899     foreach ($letters as $boundary => $letter) {
 900         if (property_exists($CFG, $gradebookcalculationsfreeze) && (int)$CFG->{$gradebookcalculationsfreeze} <= 20160518) {
 901             // Do nothing.
 902         } else {
 903             // The boundary is a percentage out of 100 so use 0 as the min and 100 as the max.
 904             $boundary = grade_grade::standardise_score($boundary, 0, 100, 0, 100);
 905         }
 906         if ($value >= $boundary) {
 907             return format_string($letter);
 908         }
 909     }
 910     return '-'; // no match? maybe '' would be more correct
 911 }
 912
 913
 914 /**
 915  * Returns grade options for gradebook grade category menu
 916  *
 917  * @param int $courseid The course ID
 918  * @param bool $includenew Include option for new category at array index -1
 919  * @return array of grade categories in course
 920  */
 921 function grade_get_categories_menu($courseid, $includenew=false) {
 922     $result = array();
 923     if (!$categories = grade_category::fetch_all(array('courseid'=>$courseid))) {
 924         //make sure course category exists
 925         if (!grade_category::fetch_course_category($courseid)) {
 926             debugging('Can not create course grade category!');
 927             return $result;
 928         }
 929         $categories = grade_category::fetch_all(array('courseid'=>$courseid));
 930     }
 931     foreach ($categories as $key=>$category) {
 932         if ($category->is_course_category()) {
 933             $result[$category->id] = get_string('uncategorised', 'grades');
 934             unset($categories[$key]);
 935         }
 936     }
 937     if ($includenew) {
 938         $result[-1] = get_string('newcategory', 'grades');
 939     }
 940     $cats = array();
 941     foreach ($categories as $category) {
 942         $cats[$category->id] = $category->get_name();
 943     }
 944     core_collator::asort($cats);
 945
 946     return ($result+$cats);
 947 }
 948
 949 /**
 950  * Returns the array of grade letters to be used in the supplied context
 951  *
 952  * @param object $context Context object or null for defaults
 953  * @return array of grade_boundary (minimum) => letter_string
 954  */
 955 function grade_get_letters($context=null) {
 956     global $DB;
 957
 958     if (empty($context)) {
 959         //default grading letters
 960         return array('93'=>'A', '90'=>'A-', '87'=>'B+', '83'=>'B', '80'=>'B-', '77'=>'C+', '73'=>'C', '70'=>'C-', '67'=>'D+', '60'=>'D', '0'=>'F');
 961     }
 962
 963     $cache = cache::make('core', 'grade_letters');
 964     $data = $cache->get($context->id);
 965
 966     if (!empty($data)) {
 967         return $data;
 968     }
 969
 970     $letters = array();
 971
 972     $contexts = $context->get_parent_context_ids();
 973     array_unshift($contexts, $context->id);
 974
 975     foreach ($contexts as $ctxid) {
 976         if ($records = $DB->get_records('grade_letters', array('contextid'=>$ctxid), 'lowerboundary DESC')) {
 977             foreach ($records as $record) {
 978                 $letters[$record->lowerboundary] = $record->letter;
 979             }
 980         }
 981
 982         if (!empty($letters)) {
 983             // Cache the grade letters for this context.
 984             $cache->set($context->id, $letters);
 985             return $letters;
 986         }
 987     }
 988
 989     $letters = grade_get_letters(null);
 990     // Cache the grade letters for this context.
 991     $cache->set($context->id, $letters);
 992     return $letters;
 993 }
 994
 995
 996 /**
 997  * Verify new value of grade item idnumber. Checks for uniqueness of new ID numbers. Old ID numbers are kept intact.
 998  *
 999  * @param string $idnumber string (with magic quotes)
1000  * @param int $courseid ID numbers are course unique only
1001  * @param grade_item $grade_item The grade item this idnumber is associated with
1002  * @param stdClass $cm used for course module idnumbers and items attached to modules
1003  * @return bool true means idnumber ok
1004  */
1005 function grade_verify_idnumber($idnumber, $courseid, $grade_item=null, $cm=null) {
1006     global $DB;
1007
1008     if ($idnumber == '') {
1009         //we allow empty idnumbers
1010         return true;
1011     }
1012
1013     // keep existing even when not unique
1014     if ($cm and $cm->idnumber == $idnumber) {
1015         if ($grade_item and $grade_item->itemnumber != 0) {
1016             // grade item with itemnumber > 0 can't have the same idnumber as the main
1017             // itemnumber 0 which is synced with course_modules
1018             return false;
1019         }
1020         return true;
1021     } else if ($grade_item and $grade_item->idnumber == $idnumber) {
1022         return true;
1023     }
1024
1025     if ($DB->record_exists('course_modules', array('course'=>$courseid, 'idnumber'=>$idnumber))) {
1026         return false;
1027     }
1028
1029     if ($DB->record_exists('grade_items', array('courseid'=>$courseid, 'idnumber'=>$idnumber))) {
1030         return false;
1031     }
1032
1033     return true;
1034 }
1035
1036 /**
1037  * Force final grade recalculation in all course items
1038  *
1039  * @param int $courseid The course ID to recalculate
1040  */
1041 function grade_force_full_regrading($courseid) {
1042     global $DB;
1043     $DB->set_field('grade_items', 'needsupdate', 1, array('courseid'=>$courseid));
1044 }
1045
1046 /**
1047  * Forces regrading of all site grades. Used when changing site setings
1048  */
1049 function grade_force_site_regrading() {
1050     global $CFG, $DB;
1051     $DB->set_field('grade_items', 'needsupdate', 1);
1052 }
1053
1054 /**
1055  * Recover a user's grades from grade_grades_history
1056  * @param int $userid the user ID whose grades we want to recover
1057  * @param int $courseid the relevant course
1058  * @return bool true if successful or false if there was an error or no grades could be recovered
1059  */
1060 function grade_recover_history_grades($userid, $courseid) {
1061     global $CFG, $DB;
1062
1063     if ($CFG->disablegradehistory) {
1064         debugging('Attempting to recover grades when grade history is disabled.');
1065         return false;
1066     }
1067
1068     //Were grades recovered? Flag to return.
1069     $recoveredgrades = false;
1070
1071     //Check the user is enrolled in this course
1072     //Dont bother checking if they have a gradeable role. They may get one later so recover
1073     //whatever grades they have now just in case.
1074     $course_context = context_course::instance($courseid);
1075     if (!is_enrolled($course_context, $userid)) {
1076         debugging('Attempting to recover the grades of a user who is deleted or not enrolled. Skipping recover.');
1077         return false;
1078     }
1079
1080     //Check for existing grades for this user in this course
1081     //Recovering grades when the user already has grades can lead to duplicate indexes and bad data
1082     //In the future we could move the existing grades to the history table then recover the grades from before then
1083     $sql = "SELECT gg.id
1084               FROM {grade_grades} gg
1085               JOIN {grade_items} gi ON gi.id = gg.itemid
1086              WHERE gi.courseid = :courseid AND gg.userid = :userid";
1087     $params = array('userid' => $userid, 'courseid' => $courseid);
1088     if ($DB->record_exists_sql($sql, $params)) {
1089         debugging('Attempting to recover the grades of a user who already has grades. Skipping recover.');
1090         return false;
1091     } else {
1092         //Retrieve the user's old grades
1093         //have history ID as first column to guarantee we a unique first column
1094         $sql = "SELECT h.id, gi.itemtype, gi.itemmodule, gi.iteminstance as iteminstance, gi.itemnumber, h.source, h.itemid, h.userid, h.rawgrade, h.rawgrademax,
1095                        h.rawgrademin, h.rawscaleid, h.usermodified, h.finalgrade, h.hidden, h.locked, h.locktime, h.exported, h.overridden, h.excluded, h.feedback,
1096                        h.feedbackformat, h.information, h.informationformat, h.timemodified, itemcreated.tm AS timecreated
1097                   FROM {grade_grades_history} h
1098                   JOIN (SELECT itemid, MAX(id) AS id
1099                           FROM {grade_grades_history}
1100                          WHERE userid = :userid1
1101                       GROUP BY itemid) maxquery ON h.id = maxquery.id AND h.itemid = maxquery.itemid
1102                   JOIN {grade_items} gi ON gi.id = h.itemid
1103                   JOIN (SELECT itemid, MAX(timemodified) AS tm
1104                           FROM {grade_grades_history}
1105                          WHERE userid = :userid2 AND action = :insertaction
1106                       GROUP BY itemid) itemcreated ON itemcreated.itemid = h.itemid
1107                  WHERE gi.courseid = :courseid";
1108         $params = array('userid1' => $userid, 'userid2' => $userid , 'insertaction' => GRADE_HISTORY_INSERT, 'courseid' => $courseid);
1109         $oldgrades = $DB->get_records_sql($sql, $params);
1110
1111         //now move the old grades to the grade_grades table
1112         foreach ($oldgrades as $oldgrade) {
1113             unset($oldgrade->id);
1114
1115             $grade = new grade_grade($oldgrade, false);//2nd arg false as dont want to try and retrieve a record from the DB
1116             $grade->insert($oldgrade->source);
1117
1118             //dont include default empty grades created when activities are created
1119             if (!is_null($oldgrade->finalgrade) || !is_null($oldgrade->feedback)) {
1120                 $recoveredgrades = true;
1121             }
1122         }
1123     }
1124
1125     //Some activities require manual grade synching (moving grades from the activity into the gradebook)
1126     //If the student was deleted when synching was done they may have grades in the activity that haven't been moved across
1127     grade_grab_course_grades($courseid, null, $userid);
1128
1129     return $recoveredgrades;
1130 }
1131
1132 /**
1133  * Updates all final grades in course.
1134  *
1135  * @param int $courseid The course ID
1136  * @param int $userid If specified try to do a quick regrading of the grades of this user only
1137  * @param object $updated_item Optional grade item to be marked for regrading. It is required if $userid is set.
1138  * @param \core\progress\base $progress If provided, will be used to update progress on this long operation.
1139  * @return bool true if ok, array of errors if problems found. Grade item id => error message
1140  */
1141 function grade_regrade_final_grades($courseid, $userid=null, $updated_item=null, $progress=null) {
1142     // This may take a very long time and extra memory.
1143     \core_php_time_limit::raise();
1144     raise_memory_limit(MEMORY_EXTRA);
1145
1146     $course_item = grade_item::fetch_course_item($courseid);
1147
1148     if ($progress == null) {
1149         $progress = new \core\progress\none();
1150     }
1151
1152     if ($userid) {
1153         // one raw grade updated for one user
1154         if (empty($updated_item)) {
1155             print_error("cannotbenull", 'debug', '', "updated_item");
1156         }
1157         if ($course_item->needsupdate) {
1158             $updated_item->force_regrading();
1159             return array($course_item->id =>'Can not do fast regrading after updating of raw grades');
1160         }
1161
1162     } else {
1163         if (!$course_item->needsupdate) {
1164             // nothing to do :-)
1165             return true;
1166         }
1167     }
1168
1169     // Categories might have to run some processing before we fetch the grade items.
1170     // This gives them a final opportunity to update and mark their children to be updated.
1171     // We need to work on the children categories up to the parent ones, so that, for instance,
1172     // if a category total is updated it will be reflected in the parent category.
1173     $cats = grade_category::fetch_all(array('courseid' => $courseid));
1174     $flatcattree = array();
1175     foreach ($cats as $cat) {
1176         if (!isset($flatcattree[$cat->depth])) {
1177             $flatcattree[$cat->depth] = array();
1178         }
1179         $flatcattree[$cat->depth][] = $cat;
1180     }
1181     krsort($flatcattree);
1182     foreach ($flatcattree as $depth => $cats) {
1183         foreach ($cats as $cat) {
1184             $cat->pre_regrade_final_grades();
1185         }
1186     }
1187
1188     $progresstotal = 0;
1189     $progresscurrent = 0;
1190
1191     $grade_items = grade_item::fetch_all(array('courseid'=>$courseid));
1192     $depends_on = array();
1193
1194     foreach ($grade_items as $gid=>$gitem) {
1195         if ((!empty($updated_item) and $updated_item->id == $gid) ||
1196                 $gitem->is_course_item() || $gitem->is_category_item() || $gitem->is_calculated()) {
1197             $grade_items[$gid]->needsupdate = 1;
1198         }
1199
1200         // We load all dependencies of these items later we can discard some grade_items based on this.
1201         if ($grade_items[$gid]->needsupdate) {
1202             $depends_on[$gid] = $grade_items[$gid]->depends_on();
1203             $progresstotal++;
1204         }
1205     }
1206
1207     $progress->start_progress('regrade_course', $progresstotal);
1208
1209     $errors = array();
1210     $finalids = array();
1211     $updatedids = array();
1212     $gids     = array_keys($grade_items);
1213     $failed = 0;
1214
1215     while (count($finalids) < count($gids)) { // work until all grades are final or error found
1216         $count = 0;
1217         foreach ($gids as $gid) {
1218             if (in_array($gid, $finalids)) {
1219                 continue; // already final
1220             }
1221
1222             if (!$grade_items[$gid]->needsupdate) {
1223                 $finalids[] = $gid; // we can make it final - does not need update
1224                 continue;
1225             }
1226             $thisprogress = $progresstotal;
1227             foreach ($grade_items as $item) {
1228                 if ($item->needsupdate) {
1229                     $thisprogress--;
1230                 }
1231             }
1232             // Clip between $progresscurrent and $progresstotal.
1233             $thisprogress = max(min($thisprogress, $progresstotal), $progresscurrent);
1234             $progress->progress($thisprogress);
1235             $progresscurrent = $thisprogress;
1236
1237             foreach ($depends_on[$gid] as $did) {
1238                 if (!in_array($did, $finalids)) {
1239                     // This item depends on something that is not yet in finals array.
1240                     continue 2;
1241                 }
1242             }
1243
1244             // If this grade item has no dependancy with any updated item at all, then remove it from being recalculated.
1245
1246             // When we get here, all of this grade item's decendents are marked as final so they would be marked as updated too
1247             // if they would have been regraded. We don't need to regrade items which dependants (not only the direct ones
1248             // but any dependant in the cascade) have not been updated.
1249
1250             // If $updated_item was specified we discard the grade items that do not depend on it or on any grade item that
1251             // depend on $updated_item.
1252
1253             // Here we check to see if the direct decendants are marked as updated.
1254             if (!empty($updated_item) && $gid != $updated_item->id && !in_array($updated_item->id, $depends_on[$gid])) {
1255
1256                 // We need to ensure that none of this item's dependencies have been updated.
1257                 // If we find that one of the direct decendants of this grade item is marked as updated then this
1258                 // grade item needs to be recalculated and marked as updated.
1259                 // Being marked as updated is done further down in the code.
1260
1261                 $updateddependencies = false;
1262                 foreach ($depends_on[$gid] as $dependency) {
1263                     if (in_array($dependency, $updatedids)) {
1264                         $updateddependencies = true;
1265                         break;
1266                     }
1267                 }
1268                 if ($updateddependencies === false) {
1269                     // If no direct descendants are marked as updated, then we don't need to update this grade item. We then mark it
1270                     // as final.
1271                     $count++;
1272                     $finalids[] = $gid;
1273                     continue;
1274                 }
1275             }
1276
1277             // Let's update, calculate or aggregate.
1278             $result = $grade_items[$gid]->regrade_final_grades($userid);
1279
1280             if ($result === true) {
1281
1282                 // We should only update the database if we regraded all users.
1283                 if (empty($userid)) {
1284                     $grade_items[$gid]->regrading_finished();
1285                     // Do the locktime item locking.
1286                     $grade_items[$gid]->check_locktime();
1287                 } else {
1288                     $grade_items[$gid]->needsupdate = 0;
1289                 }
1290                 $count++;
1291                 $finalids[] = $gid;
1292                 $updatedids[] = $gid;
1293
1294             } else {
1295                 $grade_items[$gid]->force_regrading();
1296                 $errors[$gid] = $result;
1297             }
1298         }
1299
1300         if ($count == 0) {
1301             $failed++;
1302         } else {
1303             $failed = 0;
1304         }
1305
1306         if ($failed > 1) {
1307             foreach($gids as $gid) {
1308                 if (in_array($gid, $finalids)) {
1309                     continue; // this one is ok
1310                 }
1311                 $grade_items[$gid]->force_regrading();
1312                 $errors[$grade_items[$gid]->id] = get_string('errorcalculationbroken', 'grades');
1313             }
1314             break; // Found error.
1315         }
1316     }
1317     $progress->end_progress();
1318
1319     if (count($errors) == 0) {
1320         if (empty($userid)) {
1321             // do the locktime locking of grades, but only when doing full regrading
1322             grade_grade::check_locktime_all($gids);
1323         }
1324         return true;
1325     } else {
1326         return $errors;
1327     }
1328 }
1329
1330 /**
1331  * Refetches grade data from course activities
1332  *
1333  * @param int $courseid The course ID
1334  * @param string $modname Limit the grade fetch to a single module type. For example 'forum'
1335  * @param int $userid limit the grade fetch to a single user
1336  */
1337 function grade_grab_course_grades($courseid, $modname=null, $userid=0) {
1338     global $CFG, $DB;
1339
1340     if ($modname) {
1341         $sql = "SELECT a.*, cm.idnumber as cmidnumber, m.name as modname
1342                   FROM {".$modname."} a, {course_modules} cm, {modules} m
1343                  WHERE m.name=:modname AND m.visible=1 AND m.id=cm.module AND cm.instance=a.id AND cm.course=:courseid";
1344         $params = array('modname'=>$modname, 'courseid'=>$courseid);
1345
1346         if ($modinstances = $DB->get_records_sql($sql, $params)) {
1347             foreach ($modinstances as $modinstance) {
1348                 grade_update_mod_grades($modinstance, $userid);
1349             }
1350         }
1351         return;
1352     }
1353
1354     if (!$mods = core_component::get_plugin_list('mod') ) {
1355         print_error('nomodules', 'debug');
1356     }
1357
1358     foreach ($mods as $mod => $fullmod) {
1359         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
1360             continue;
1361         }
1362
1363         // include the module lib once
1364         if (file_exists($fullmod.'/lib.php')) {
1365             // get all instance of the activity
1366             $sql = "SELECT a.*, cm.idnumber as cmidnumber, m.name as modname
1367                       FROM {".$mod."} a, {course_modules} cm, {modules} m
1368                      WHERE m.name=:mod AND m.visible=1 AND m.id=cm.module AND cm.instance=a.id AND cm.course=:courseid";
1369             $params = array('mod'=>$mod, 'courseid'=>$courseid);
1370
1371             if ($modinstances = $DB->get_records_sql($sql, $params)) {
1372                 foreach ($modinstances as $modinstance) {
1373                     grade_update_mod_grades($modinstance, $userid);
1374                 }
1375             }
1376         }
1377     }
1378 }
1379
1380 /**
1381  * Force full update of module grades in central gradebook
1382  *
1383  * @param object $modinstance Module object with extra cmidnumber and modname property
1384  * @param int $userid Optional user ID if limiting the update to a single user
1385  * @return bool True if success
1386  */
1387 function grade_update_mod_grades($modinstance, $userid=0) {
1388     global $CFG, $DB;
1389
1390     $fullmod = $CFG->dirroot.'/mod/'.$modinstance->modname;
1391     if (!file_exists($fullmod.'/lib.php')) {
1392         debugging('missing lib.php file in module ' . $modinstance->modname);
1393         return false;
1394     }
1395     include_once($fullmod.'/lib.php');
1396
1397     $updateitemfunc   = $modinstance->modname.'_grade_item_update';
1398     $updategradesfunc = $modinstance->modname.'_update_grades';
1399
1400     if (function_exists($updategradesfunc) and function_exists($updateitemfunc)) {
1401         //new grading supported, force updating of grades
1402         $updateitemfunc($modinstance);
1403         $updategradesfunc($modinstance, $userid);
1404     } else if (function_exists($updategradesfunc) xor function_exists($updateitemfunc)) {
1405         // Module does not support grading?
1406         debugging("You have declared one of $updateitemfunc and $updategradesfunc but not both. " .
1407                   "This will cause broken behaviour.", DEBUG_DEVELOPER);
1408     }
1409
1410     return true;
1411 }
1412
1413 /**
1414  * Remove grade letters for given context
1415  *
1416  * @param context $context The context
1417  * @param bool $showfeedback If true a success notification will be displayed
1418  */
1419 function remove_grade_letters($context, $showfeedback) {
1420     global $DB, $OUTPUT;
1421
1422     $strdeleted = get_string('deleted');
1423
1424     $records = $DB->get_records('grade_letters', array('contextid' => $context->id));
1425     foreach ($records as $record) {
1426         $DB->delete_records('grade_letters', array('id' => $record->id));
1427         // Trigger the letter grade deleted event.
1428         $event = \core\event\grade_letter_deleted::create(array(
1429             'objectid' => $record->id,
1430             'context' => $context,
1431         ));
1432         $event->trigger();
1433     }
1434     if ($showfeedback) {
1435         echo $OUTPUT->notification($strdeleted.' - '.get_string('letters', 'grades'), 'notifysuccess');
1436     }
1437
1438     $cache = cache::make('core', 'grade_letters');
1439     $cache->delete($context->id);
1440 }
1441
1442 /**
1443  * Remove all grade related course data
1444  * Grade history is kept
1445  *
1446  * @param int $courseid The course ID
1447  * @param bool $showfeedback If true success notifications will be displayed
1448  */
1449 function remove_course_grades($courseid, $showfeedback) {
1450     global $DB, $OUTPUT;
1451
1452     $fs = get_file_storage();
1453     $strdeleted = get_string('deleted');
1454
1455     $course_category = grade_category::fetch_course_category($courseid);
1456     $course_category->delete('coursedelete');
1457     $fs->delete_area_files(context_course::instance($courseid)->id, 'grade', 'feedback');
1458     if ($showfeedback) {
1459         echo $OUTPUT->notification($strdeleted.' - '.get_string('grades', 'grades').', '.get_string('items', 'grades').', '.get_string('categories', 'grades'), 'notifysuccess');
1460     }
1461
1462     if ($outcomes = grade_outcome::fetch_all(array('courseid'=>$courseid))) {
1463         foreach ($outcomes as $outcome) {
1464             $outcome->delete('coursedelete');
1465         }
1466     }
1467     $DB->delete_records('grade_outcomes_courses', array('courseid'=>$courseid));
1468     if ($showfeedback) {
1469         echo $OUTPUT->notification($strdeleted.' - '.get_string('outcomes', 'grades'), 'notifysuccess');
1470     }
1471
1472     if ($scales = grade_scale::fetch_all(array('courseid'=>$courseid))) {
1473         foreach ($scales as $scale) {
1474             $scale->delete('coursedelete');
1475         }
1476     }
1477     if ($showfeedback) {
1478         echo $OUTPUT->notification($strdeleted.' - '.get_string('scales'), 'notifysuccess');
1479     }
1480
1481     $DB->delete_records('grade_settings', array('courseid'=>$courseid));
1482     if ($showfeedback) {
1483         echo $OUTPUT->notification($strdeleted.' - '.get_string('settings', 'grades'), 'notifysuccess');
1484     }
1485 }
1486
1487 /**
1488  * Called when course category is deleted
1489  * Cleans the gradebook of associated data
1490  *
1491  * @param int $categoryid The course category id
1492  * @param int $newparentid If empty everything is deleted. Otherwise the ID of the category where content moved
1493  * @param bool $showfeedback print feedback
1494  */
1495 function grade_course_category_delete($categoryid, $newparentid, $showfeedback) {
1496     global $DB;
1497
1498     $context = context_coursecat::instance($categoryid);
1499     $records = $DB->get_records('grade_letters', array('contextid' => $context->id));
1500     foreach ($records as $record) {
1501         $DB->delete_records('grade_letters', array('id' => $record->id));
1502         // Trigger the letter grade deleted event.
1503         $event = \core\event\grade_letter_deleted::create(array(
1504             'objectid' => $record->id,
1505             'context' => $context,
1506         ));
1507         $event->trigger();
1508     }
1509 }
1510
1511 /**
1512  * Does gradebook cleanup when a module is uninstalled
1513  * Deletes all associated grade items
1514  *
1515  * @param string $modname The grade item module name to remove. For example 'forum'
1516  */
1517 function grade_uninstalled_module($modname) {
1518     global $CFG, $DB;
1519
1520     $sql = "SELECT *
1521               FROM {grade_items}
1522              WHERE itemtype='mod' AND itemmodule=?";
1523
1524     // go all items for this module and delete them including the grades
1525     $rs = $DB->get_recordset_sql($sql, array($modname));
1526     foreach ($rs as $item) {
1527         $grade_item = new grade_item($item, false);
1528         $grade_item->delete('moduninstall');
1529     }
1530     $rs->close();
1531 }
1532
1533 /**
1534  * Deletes all of a user's grade data from gradebook
1535  *
1536  * @param int $userid The user whose grade data should be deleted
1537  */
1538 function grade_user_delete($userid) {
1539     if ($grades = grade_grade::fetch_all(array('userid'=>$userid))) {
1540         foreach ($grades as $grade) {
1541             $grade->delete('userdelete');
1542         }
1543     }
1544 }
1545
1546 /**
1547  * Purge course data when user unenrolls from a course
1548  *
1549  * @param int $courseid The ID of the course the user has unenrolled from
1550  * @param int $userid The ID of the user unenrolling
1551  */
1552 function grade_user_unenrol($courseid, $userid) {
1553     if ($items = grade_item::fetch_all(array('courseid'=>$courseid))) {
1554         foreach ($items as $item) {
1555             if ($grades = grade_grade::fetch_all(array('userid'=>$userid, 'itemid'=>$item->id))) {
1556                 foreach ($grades as $grade) {
1557                     $grade->delete('userdelete');
1558                 }
1559             }
1560         }
1561     }
1562 }
1563
1564 /**
1565  * Reset all course grades, refetch from the activities and recalculate
1566  *
1567  * @param int $courseid The course to reset
1568  * @return bool success
1569  */
1570 function grade_course_reset($courseid) {
1571
1572     // no recalculations
1573     grade_force_full_regrading($courseid);
1574
1575     $grade_items = grade_item::fetch_all(array('courseid'=>$courseid));
1576     foreach ($grade_items as $gid=>$grade_item) {
1577         $grade_item->delete_all_grades('reset');
1578     }
1579
1580     //refetch all grades
1581     grade_grab_course_grades($courseid);
1582
1583     // recalculate all grades
1584     grade_regrade_final_grades($courseid);
1585     return true;
1586 }
1587
1588 /**
1589  * Convert a number to 5 decimal point float, an empty string or a null db compatible format
1590  * (we need this to decide if db value changed)
1591  *
1592  * @param float|null $number The number to convert
1593  * @return float|null float or null
1594  */
1595 function grade_floatval(?float $number) {
1596     if (is_null($number) or $number === '') {
1597         return null;
1598     }
1599     // we must round to 5 digits to get the same precision as in 10,5 db fields
1600     // note: db rounding for 10,5 is different from php round() function
1601     return round($number, 5);
1602 }
1603
1604 /**
1605  * Compare two float numbers safely. Uses 5 decimals php precision using {@link grade_floatval()}. Nulls accepted too.
1606  * Used for determining if a database update is required
1607  *
1608  * @param float|null $f1 Float one to compare
1609  * @param float|null $f2 Float two to compare
1610  * @return bool True if the supplied values are different
1611  */
1612 function grade_floats_different(?float $f1, ?float $f2): bool {
1613     // note: db rounding for 10,5 is different from php round() function
1614     return (grade_floatval($f1) !== grade_floatval($f2));
1615 }
1616
1617 /**
1618  * Compare two float numbers safely. Uses 5 decimals php precision using {@link grade_floatval()}
1619  *
1620  * Do not use rounding for 10,5 at the database level as the results may be
1621  * different from php round() function.
1622  *
1623  * @since Moodle 2.0
1624  * @param float|null $f1 Float one to compare
1625  * @param float|null $f2 Float two to compare
1626  * @return bool True if the values should be considered as the same grades
1627  */
1628 function grade_floats_equal(?float $f1, ?float $f2): bool {
1629     return (grade_floatval($f1) === grade_floatval($f2));
1630 }
1631
1632 /**
1633  * Get the most appropriate grade date for a grade item given the user that the grade relates to.
1634  *
1635  * @param \stdClass $grade
1636  * @param \stdClass $user
1637  * @return int|null
1638  */
1639 function grade_get_date_for_user_grade(\stdClass $grade, \stdClass $user): ?int {
1640     // The `datesubmitted` is the time that the grade was created.
1641     // The `dategraded` is the time that it was modified or overwritten.
1642     // If the grade was last modified by the user themselves use the date graded.
1643     // Otherwise use date submitted.
1644     if ($grade->usermodified == $user->id || empty($grade->datesubmitted)) {
1645         return $grade->dategraded;
1646     } else {
1647         return $grade->datesubmitted;
1648     }
1649 }