Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
- Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
- PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
/lib/ -> gradelib.php (source)
Differences Between: [Versions 310 and 400] [Versions 310 and 401] [Versions 310 and 402] [Versions 310 and 403]
Library of functions for gradebook - both public and internal
| Copyright: | 1999 onwards Martin Dougiamas {@link http://moodle.com} |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 1647 lines (62 kb) |
| Included or required: | 1 time |
| Referenced: | 4 times |
| Includes or requires: | 0 files |
Defines 33 functions
grade_update()
grade_update_outcomes()
grade_needs_regrade_final_grades()
grade_needs_regrade_progress_bar()
grade_regrade_final_grades_if_required()
grade_get_grades()
grade_get_setting()
grade_get_settings()
grade_set_setting()
grade_format_gradevalue()
grade_format_gradevalue_real()
grade_format_gradevalue_percentage()
grade_format_gradevalue_letter()
grade_get_categories_menu()
grade_get_letters()
grade_verify_idnumber()
grade_force_full_regrading()
grade_force_site_regrading()
grade_recover_history_grades()
grade_regrade_final_grades()
grade_grab_course_grades()
grade_update_mod_grades()
remove_grade_letters()
remove_course_grades()
grade_course_category_delete()
grade_uninstalled_module()
grade_user_delete()
grade_user_unenrol()
grade_course_reset()
grade_floatval()
grade_floats_different()
grade_floats_equal()
grade_get_date_for_user_grade()
grade_update_outcomes()
grade_needs_regrade_final_grades()
grade_needs_regrade_progress_bar()
grade_regrade_final_grades_if_required()
grade_get_grades()
grade_get_setting()
grade_get_settings()
grade_set_setting()
grade_format_gradevalue()
grade_format_gradevalue_real()
grade_format_gradevalue_percentage()
grade_format_gradevalue_letter()
grade_get_categories_menu()
grade_get_letters()
grade_verify_idnumber()
grade_force_full_regrading()
grade_force_site_regrading()
grade_recover_history_grades()
grade_regrade_final_grades()
grade_grab_course_grades()
grade_update_mod_grades()
remove_grade_letters()
remove_course_grades()
grade_course_category_delete()
grade_uninstalled_module()
grade_user_delete()
grade_user_unenrol()
grade_course_reset()
grade_floatval()
grade_floats_different()
grade_floats_equal()
grade_get_date_for_user_grade()
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 |
