Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
/lib/ -> gradelib.php (source)

Functions that are not part of a class:

grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=NULL, $itemdetails=NULL)   X-Ref
Submit new or update grade; update/create grade_item definition. Grade must have userid specified,
rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded'.
Missing property or key means does not change the existing value.

Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',
'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted' and 'hidden'. 'reset' means delete all current grades including locked ones.

Manual, course or category items can not be updated by this function.

param: string $source Source of the grade such as 'mod/assignment'
param: int    $courseid ID of course
param: string $itemtype Type of grade item. For example, mod or block
param: string $itemmodule More specific then $itemtype. For example, assignment or forum. May be NULL for some item types
param: int    $iteminstance Instance ID of graded item
param: int    $itemnumber Most probably 0. Modules can use other numbers when having more than one grade for each user
param: mixed  $grades Grade (object, array) or several grades (arrays of arrays or objects), NULL if updating grade_item definition only
param: mixed  $itemdetails Object or array describing the grading item, NULL if no change
return: int Returns GRADE_UPDATE_OK, GRADE_UPDATE_FAILED, GRADE_UPDATE_MULTIPLE or GRADE_UPDATE_ITEM_LOCKED

grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data)   X-Ref
Updates a user's outcomes. Manual outcomes can not be updated.

param: string $source Source of the grade such as 'mod/assignment'
param: int    $courseid ID of course
param: string $itemtype Type of grade item. For example, 'mod' or 'block'
param: string $itemmodule More specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types
param: int    $iteminstance Instance ID of graded item. For example the forum ID.
param: int    $userid ID of the graded user
param: array  $data Array consisting of grade item itemnumber ({@link grade_update()}) => outcomegrade
return: bool returns true if grade items were found and updated successfully

grade_needs_regrade_final_grades($courseid)   X-Ref
Return true if the course needs regrading.

param: int $courseid The course ID
return: bool true if course grades need updating.

grade_needs_regrade_progress_bar($courseid)   X-Ref
Return true if the regrade process is likely to be time consuming and
will therefore require the progress bar.

param: int $courseid The course ID
return: bool Whether the regrade process is likely to be time consuming

grade_regrade_final_grades_if_required($course, callable $callback = null)   X-Ref
Check whether regarding of final grades is required and, if so, perform the regrade.

If the regrade is expected to be time consuming (see grade_needs_regrade_progress_bar), then this
function will output the progress bar, and redirect to the current PAGE->url after regrading
completes. Otherwise the regrading will happen immediately and the page will be loaded as per
normal.

A callback may be specified, which is called if regrading has taken place.
The callback may optionally return a URL which will be redirected to when the progress bar is present.

param: stdClass $course The course to regrade
param: callable $callback A function to call if regrading took place
return: moodle_url The URL to redirect to if redirecting

grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=null)   X-Ref
Returns grading information for given activity, optionally with user grades
Manual, course or category items can not be queried.

param: int    $courseid ID of course
param: string $itemtype Type of grade item. For example, 'mod' or 'block'
param: string $itemmodule More specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types
param: int    $iteminstance ID of the item module
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
return: array Array of grade information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers

grade_get_setting($courseid, $name, $default=null, $resetcache=false)   X-Ref
Returns a  course gradebook setting

param: int $courseid
param: string $name of setting, maybe null if reset only
param: string $default value to return if setting is not found
param: bool $resetcache force reset of internal static cache
return: string value of the setting, $default if setting not found, NULL if supplied $name is null

grade_get_settings($courseid)   X-Ref
Returns all course gradebook settings as object properties

param: int $courseid
return: object

grade_set_setting($courseid, $name, $value)   X-Ref
Add, update or delete a course gradebook setting

param: int $courseid The course ID
param: string $name Name of the setting
param: string $value Value of the setting. NULL means delete the setting.

grade_format_gradevalue($value, &$grade_item, $localized=true, $displaytype=null, $decimals=null)   X-Ref
Returns string representation of grade value

param: float $value The grade value
param: object $grade_item Grade item object passed by reference to prevent scale reloading
param: bool $localized use localised decimal separator
param: int $displaytype type of display. For example GRADE_DISPLAY_TYPE_REAL, GRADE_DISPLAY_TYPE_PERCENTAGE, GRADE_DISPLAY_TYPE_LETTER
param: int $decimals The number of decimal places when displaying float values
return: string

grade_format_gradevalue_real($value, $grade_item, $decimals, $localized)   X-Ref
Returns a float representation of a grade value

param: float $value The grade value
param: object $grade_item Grade item object
param: int $decimals The number of decimal places
param: bool $localized use localised decimal separator
return: string

grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized)   X-Ref
Returns a percentage representation of a grade value

param: float $value The grade value
param: object $grade_item Grade item object
param: int $decimals The number of decimal places
param: bool $localized use localised decimal separator
return: string

grade_format_gradevalue_letter($value, $grade_item)   X-Ref
Returns a letter grade representation of a grade value
The array of grade letters used is produced by {@link grade_get_letters()} using the course context

param: float $value The grade value
param: object $grade_item Grade item object
return: string

grade_get_categories_menu($courseid, $includenew=false)   X-Ref
Returns grade options for gradebook grade category menu

param: int $courseid The course ID
param: bool $includenew Include option for new category at array index -1
return: array of grade categories in course

grade_get_letters($context=null)   X-Ref
Returns the array of grade letters to be used in the supplied context

param: object $context Context object or null for defaults
return: array of grade_boundary (minimum) => letter_string

grade_verify_idnumber($idnumber, $courseid, $grade_item=null, $cm=null)   X-Ref
Verify new value of grade item idnumber. Checks for uniqueness of new ID numbers. Old ID numbers are kept intact.

param: string $idnumber string (with magic quotes)
param: int $courseid ID numbers are course unique only
param: grade_item $grade_item The grade item this idnumber is associated with
param: stdClass $cm used for course module idnumbers and items attached to modules
return: bool true means idnumber ok

grade_force_full_regrading($courseid)   X-Ref
Force final grade recalculation in all course items

param: int $courseid The course ID to recalculate

grade_force_site_regrading()   X-Ref
Forces regrading of all site grades. Used when changing site setings


grade_recover_history_grades($userid, $courseid)   X-Ref
Recover a user's grades from grade_grades_history

param: int $userid the user ID whose grades we want to recover
param: int $courseid the relevant course
return: bool true if successful or false if there was an error or no grades could be recovered

grade_regrade_final_grades($courseid, $userid=null, $updated_item=null, $progress=null)   X-Ref
Updates all final grades in course.

param: int $courseid The course ID
param: int $userid If specified try to do a quick regrading of the grades of this user only
param: object $updated_item Optional grade item to be marked for regrading. It is required if $userid is set.
param: \core\progress\base $progress If provided, will be used to update progress on this long operation.
return: bool true if ok, array of errors if problems found. Grade item id => error message

grade_grab_course_grades($courseid, $modname=null, $userid=0)   X-Ref
Refetches grade data from course activities

param: int $courseid The course ID
param: string $modname Limit the grade fetch to a single module type. For example 'forum'
param: int $userid limit the grade fetch to a single user

grade_update_mod_grades($modinstance, $userid=0)   X-Ref
Force full update of module grades in central gradebook

param: object $modinstance Module object with extra cmidnumber and modname property
param: int $userid Optional user ID if limiting the update to a single user
return: bool True if success

remove_grade_letters($context, $showfeedback)   X-Ref
Remove grade letters for given context

param: context $context The context
param: bool $showfeedback If true a success notification will be displayed

remove_course_grades($courseid, $showfeedback)   X-Ref
Remove all grade related course data
Grade history is kept

param: int $courseid The course ID
param: bool $showfeedback If true success notifications will be displayed

grade_course_category_delete($categoryid, $newparentid, $showfeedback)   X-Ref
Called when course category is deleted
Cleans the gradebook of associated data

param: int $categoryid The course category id
param: int $newparentid If empty everything is deleted. Otherwise the ID of the category where content moved
param: bool $showfeedback print feedback

grade_uninstalled_module($modname)   X-Ref
Does gradebook cleanup when a module is uninstalled
Deletes all associated grade items

param: string $modname The grade item module name to remove. For example 'forum'

grade_user_delete($userid)   X-Ref
Deletes all of a user's grade data from gradebook

param: int $userid The user whose grade data should be deleted

grade_user_unenrol($courseid, $userid)   X-Ref
Purge course data when user unenrolls from a course

param: int $courseid The ID of the course the user has unenrolled from
param: int $userid The ID of the user unenrolling

grade_course_reset($courseid)   X-Ref
Reset all course grades, refetch from the activities and recalculate

param: int $courseid The course to reset
return: bool success

grade_floatval($number)   X-Ref
Convert a number to 5 decimal point float, an empty string or a null db compatible format
(we need this to decide if db value changed)

param: mixed $number The number to convert
return: mixed float or null

grade_floats_different($f1, $f2)   X-Ref
Compare two float numbers safely. Uses 5 decimals php precision using {@link grade_floatval()}. Nulls accepted too.
Used for determining if a database update is required

param: float $f1 Float one to compare
param: float $f2 Float two to compare
return: bool True if the supplied values are different

grade_floats_equal($f1, $f2)   X-Ref
Compare two float numbers safely. Uses 5 decimals php precision using {@link grade_floatval()}

Do not use rounding for 10,5 at the database level as the results may be
different from php round() function.

param: float $f1 Float one to compare
param: float $f2 Float two to compare
return: bool True if the values should be considered as the same grades

grade_get_date_for_user_grade(\stdClass $grade, \stdClass $user)   X-Ref
Get the most appropriate grade date for a grade item given the user that the grade relates to.

param: \stdClass $grade
param: \stdClass $user
return: int|null