Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
- Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
- PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/lib/ -> gradelib.php (source)
Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 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: | 1649 lines (63 kb) |
| Included or required: | 1 time |
| Referenced: | 5 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, $isbulkupdate = false) 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. return: int Returns GRADE_UPDATE_OK, GRADE_UPDATE_FAILED, GRADE_UPDATE_MULTIPLE or GRADE_UPDATE_ITEM_LOCKED 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 param: bool $isbulkupdate If bulk grade update is happening. |
| grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data) X-Ref |
| Updates a user's outcomes. Manual outcomes can not be updated. return: bool returns true if grade items were found and updated successfully 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 |
| grade_needs_regrade_final_grades($courseid) X-Ref |
| Return true if the course needs regrading. return: bool true if course grades need updating. param: int $courseid The course ID |
| 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. return: bool Whether the regrade process is likely to be time consuming param: int $courseid The course ID |
| 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. return: moodle_url The URL to redirect to if redirecting param: stdClass $course The course to regrade param: callable $callback A function to call if regrading took place |
| 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. return: array Array of grade information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers 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 |
| grade_get_setting($courseid, $name, $default=null, $resetcache=false) X-Ref |
| Returns a course gradebook setting return: string value of the setting, $default if setting not found, NULL if supplied $name is null 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 |
| grade_get_settings($courseid) X-Ref |
| Returns all course gradebook settings as object properties return: object param: int $courseid |
| 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(?float $value, &$grade_item, $localized=true, $displaytype=null, $decimals=null) X-Ref |
| Returns string representation of grade value return: string param: float|null $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 |
| grade_format_gradevalue_real(?float $value, $grade_item, $decimals, $localized) X-Ref |
| Returns a float representation of a grade value return: string param: float|null $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 |
| grade_format_gradevalue_percentage(?float $value, $grade_item, $decimals, $localized) X-Ref |
| Returns a percentage representation of a grade value return: string param: float|null $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 |
| grade_format_gradevalue_letter(?float $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 return: string param: float|null $value The grade value param: object $grade_item Grade item object |
| grade_get_categories_menu($courseid, $includenew=false) X-Ref |
| Returns grade options for gradebook grade category menu return: array of grade categories in course param: int $courseid The course ID param: bool $includenew Include option for new category at array index -1 |
| grade_get_letters($context=null) X-Ref |
| Returns the array of grade letters to be used in the supplied context return: array of grade_boundary (minimum) => letter_string param: object $context Context object or null for defaults |
| 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. return: bool true means idnumber ok 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 |
| 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 return: bool true if successful or false if there was an error or no grades could be recovered param: int $userid the user ID whose grades we want to recover param: int $courseid the relevant course |
| grade_regrade_final_grades($courseid, $userid=null, $updated_item=null, $progress=null) X-Ref |
| Updates all final grades in course. return: bool true if ok, array of errors if problems found. Grade item id => error message 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. |
| 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 return: bool True if success 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 |
| 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 return: bool success param: int $courseid The course to reset |
| grade_floatval(?float $number) X-Ref |
| Convert a number to 5 decimal point float, null db compatible format (we need this to decide if db value changed) return: float|null float or null param: float|null $number The number to convert |
| grade_floats_different(?float $f1, ?float $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 return: bool True if the supplied values are different param: float|null $f1 Float one to compare param: float|null $f2 Float two to compare |
| grade_floats_equal(?float $f1, ?float $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. return: bool True if the values should be considered as the same grades param: float|null $f1 Float one to compare param: float|null $f2 Float two to compare |
| 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. return: int|null param: \stdClass $grade param: \stdClass $user |
