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