Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

Definition of a class to represent a grade item

Copyright: 2006 Nicolas Connault
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 2599 lines (94 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 1 file
 lib/grade/grade_object.php

Defines 1 class

grade_item:: (73 methods):
  __construct()
  update()
  qualifies_for_regrading()
  fetch()
  has_grades()
  has_overridden_grades()
  fetch_all()
  delete()
  delete_all_grades()
  duplicate()
  insert()
  add_idnumber()
  is_locked()
  set_locked()
  check_locktime()
  set_locktime()
  get_locktime()
  set_hidden()
  has_hidden_grades()
  regrading_finished()
  regrade_final_grades()
  adjust_raw_grade()
  rescale_grades_keep_percentage()
  force_regrading()
  load_scale()
  load_outcome()
  get_parent_category()
  load_parent_category()
  get_item_category()
  load_item_category()
  is_category_item()
  is_course_item()
  is_manual_item()
  is_outcome_item()
  is_external_item()
  is_overridable_item()
  is_overridable_item_feedback()
  is_raw_used()
  is_aggregate_item()
  fetch_course_item()
  is_editable()
  is_calculated()
  get_calculation()
  set_calculation()
  denormalize_formula()
  normalize_formula()
  get_final()
  get_grade()
  get_sortorder()
  get_idnumber()
  get_grade_item()
  set_sortorder()
  move_after_sortorder()
  fix_duplicate_sortorder()
  get_name()
  get_description()
  set_parent()
  set_aggregation_fields_for_aggregation()
  bounded_grade()
  depends_on()
  refresh_grades()
  update_final_grade()
  update_raw_grade()
  compute()
  use_formula()
  validate_formula()
  get_displaytype()
  get_decimals()
  get_formatted_range()
  get_coefstring()
  can_control_visibility()
  notify_changed()
  get_context()


Class: grade_item  - X-Ref

Class representing a grade item.

It is responsible for handling its DB representation, modifying and returning its metadata.

__construct($params = null, $fetch = true)   X-Ref
Constructor. Optionally (and by default) attempts to fetch corresponding row from the database

param: array $params An array with required parameters for this grade object.
param: bool $fetch Whether to fetch corresponding row from the database or not,

update($source = null, $isbulkupdate = false)   X-Ref
In addition to update() as defined in grade_object, handle the grade_outcome and grade_scale objects.
Force regrading if necessary, rounds the float numbers using php function,
the reason is we need to compare the db value with computed number to skip regrading if possible.

param: string $source from where was the object inserted (mod/forum, manual, etc.)
param: bool $isbulkupdate If bulk grade update is happening.
return: bool success

qualifies_for_regrading()   X-Ref
Compares the values held by this object with those of the matching record in DB, and returns
whether or not these differences are sufficient to justify an update of all parent objects.
This assumes that this object has an id number and a matching record in DB. If not, it will return false.

return: bool

fetch($params)   X-Ref
Finds and returns a grade_item instance based on params.

param: array $params associative arrays varname=>value
return: grade_item|bool Returns a grade_item instance or false if none found

has_grades()   X-Ref
Check to see if there are any existing grades for this grade_item.

return: boolean - true if there are valid grades for this grade_item.

has_overridden_grades()   X-Ref
Check to see if there are existing overridden grades for this grade_item.

return: boolean - true if there are overridden grades for this grade_item.

fetch_all($params)   X-Ref
Finds and returns all grade_item instances based on params.

param: array $params associative arrays varname=>value
return: array array of grade_item instances or false if none found.

delete($source=null)   X-Ref
Delete all grades and force_regrading of parent category.

param: string $source from where was the object deleted (mod/forum, manual, etc.)
return: bool success

delete_all_grades($source=null)   X-Ref
Delete all grades

param: string $source from where was the object deleted (mod/forum, manual, etc.)
return: bool

duplicate()   X-Ref
Duplicate grade item.

return: grade_item The duplicate grade item

insert($source = null, $isbulkupdate = false)   X-Ref
In addition to perform parent::insert(), calls force_regrading() method too.

param: string $source From where was the object inserted (mod/forum, manual, etc.)
param: string $isbulkupdate If bulk grade update is happening.
return: int PK ID if successful, false otherwise

add_idnumber($idnumber)   X-Ref
Set idnumber of grade item, updates also course_modules table

param: string $idnumber (without magic quotes)
return: bool success

is_locked($userid=NULL)   X-Ref
Returns the locked state of this grade_item (if the grade_item is locked OR no specific
$userid is given) or the locked state of a specific grade within this item if a specific
$userid is given and the grade_item is unlocked.

param: int $userid The user's ID
return: bool Locked state

set_locked($lockedstate, $cascade=false, $refresh=true)   X-Ref
Locks or unlocks this grade_item and (optionally) all its associated final grades.

param: int $lockedstate 0, 1 or a timestamp int(10) after which date the item will be locked.
param: bool $cascade Lock/unlock child objects too
param: bool $refresh Refresh grades when unlocking
return: bool True if grade_item all grades updated, false if at least one update fails

check_locktime()   X-Ref
Lock the grade if needed. Make sure this is called only when final grades are valid


set_locktime($locktime)   X-Ref
Set the locktime for this grade item.

param: int $locktime timestamp for lock to activate
return: void

get_locktime()   X-Ref
Set the locktime for this grade item.

return: int $locktime timestamp for lock to activate

set_hidden($hidden, $cascade=false)   X-Ref
Set the hidden status of grade_item and all grades.

0 mean always visible, 1 means always hidden and a number > 1 is a timestamp to hide until

param: int $hidden new hidden status
param: bool $cascade apply to child objects too

has_hidden_grades($groupsql="", array $params=null, $groupwheresql="")   X-Ref
Returns the number of grades that are hidden

param: string $groupsql SQL to limit the query by group
param: array $params SQL params for $groupsql
param: string $groupwheresql Where conditions for $groupsql
return: int The number of hidden grades

regrading_finished()   X-Ref
Mark regrading as finished successfully. This will also be called when subsequent regrading will not change any grades.
Situations such as an error being found will still result in the regrading being finished.


regrade_final_grades($userid=null, ?\core\progress\base $progress = null)   X-Ref
Performs the necessary calculations on the grades_final referenced by this grade_item.
Also resets the needsupdate flag once successfully performed.

This function must be used ONLY from lib/gradeslib.php/grade_regrade_final_grades(),
because the regrading must be done in correct order!!

param: int $userid Supply a user ID to limit the regrading to a single user
param: \core\progress\base|null $progress Optional progress object, will be updated per user
return: bool true if ok, error string otherwise

adjust_raw_grade($rawgrade, $rawmin, $rawmax)   X-Ref
Given a float grade value or integer grade scale, applies a number of adjustment based on
grade_item variables and returns the result.

param: float $rawgrade The raw grade value
param: float $rawmin original rawmin
param: float $rawmax original rawmax
return: mixed

rescale_grades_keep_percentage($oldgrademin, $oldgrademax, $newgrademin, $newgrademax, $source = null)   X-Ref
Update the rawgrademax and rawgrademin for all grade_grades records for this item.
Scale every rawgrade to maintain the percentage. This function should be called
after the gradeitem has been updated to the new min and max values.

param: float $oldgrademin The previous grade min value
param: float $oldgrademax The previous grade max value
param: float $newgrademin The new grade min value
param: float $newgrademax The new grade max value
param: string $source from where was the object inserted (mod/forum, manual, etc.)
return: bool True on success

force_regrading()   X-Ref
Sets this grade_item's needsupdate to true. Also marks the course item as needing update.

return: void

load_scale()   X-Ref
Instantiates a grade_scale object from the DB if this item's scaleid variable is set

return: grade_scale Returns a grade_scale object or null if no scale used

load_outcome()   X-Ref
Instantiates a grade_outcome object from the DB if this item's outcomeid variable is set

return: grade_outcome This grade item's associated grade_outcome or null

get_parent_category()   X-Ref
Returns the grade_category object this grade_item belongs to (referenced by categoryid)
or category attached to category item.

return: grade_category|bool Returns a grade_category object if applicable or false if this is a course item

load_parent_category()   X-Ref
Calls upon the get_parent_category method to retrieve the grade_category object
from the DB and assigns it to $this->parent_category. It also returns the object.

return: grade_category This grade item's parent grade_category.

get_item_category()   X-Ref
Returns the grade_category for a grade category grade item

return: grade_category|bool Returns a grade_category instance if applicable or false otherwise

load_item_category()   X-Ref
Calls upon the get_item_category method to retrieve the grade_category object
from the DB and assigns it to $this->item_category. It also returns the object.

return: grade_category

is_category_item()   X-Ref
Is the grade item associated with category?

return: bool

is_course_item()   X-Ref
Is the grade item associated with course?

return: bool

is_manual_item()   X-Ref
Is this a manually graded item?

return: bool

is_outcome_item()   X-Ref
Is this an outcome item?

return: bool

is_external_item()   X-Ref
Is the grade item external - associated with module, plugin or something else?

return: bool

is_overridable_item()   X-Ref
Is the grade item overridable

return: bool

is_overridable_item_feedback()   X-Ref
Is the grade item feedback overridable

return: bool

is_raw_used()   X-Ref
Returns true if grade items uses raw grades

return: bool

is_aggregate_item()   X-Ref
Returns true if the grade item is an aggreggated type grade.

return: bool

fetch_course_item($courseid)   X-Ref
Returns the grade item associated with the course

param: int $courseid
return: grade_item Course level grade item object

is_editable()   X-Ref
Is grading object editable?

return: bool

is_calculated()   X-Ref
Checks if grade calculated. Returns this object's calculation.

return: bool true if grade item calculated.

get_calculation()   X-Ref
Returns calculation string if grade calculated.

return: string Returns the grade item's calculation if calculation is used, null if not

set_calculation($formula)   X-Ref
Sets this item's calculation (creates it) if not yet set, or
updates it if already set (in the DB). If no calculation is given,
the calculation is removed.

param: string $formula string representation of formula used for calculation
return: bool success

denormalize_formula($formula, $courseid)   X-Ref
Denormalizes the calculation formula to [idnumber] form

param: string $formula A string representation of the formula
param: int $courseid The course ID
return: string The denormalized formula as a string

normalize_formula($formula, $courseid)   X-Ref
Normalizes the calculation formula to [#giXX#] form

param: string $formula The formula
param: int $courseid The course ID
return: string The normalized formula as a string

get_final($userid=NULL)   X-Ref
Returns the final values for this grade item (as imported by module or other source).

param: int $userid Optional: to retrieve a single user's final grade
return: array|grade_grade An array of all grade_grade instances for this grade_item, or a single grade_grade instance.

get_grade($userid, $create=true)   X-Ref
Get (or create if not exist yet) grade for this user

param: int $userid The user ID
param: bool $create If true and the user has no grade for this grade item a new grade_grade instance will be inserted
return: grade_grade The grade_grade instance for the user for this grade item

get_sortorder()   X-Ref
Returns the sortorder of this grade_item. This method is also available in
grade_category, for cases where the object type is not know.

return: int Sort order

get_idnumber()   X-Ref
Returns the idnumber of this grade_item. This method is also available in
grade_category, for cases where the object type is not know.

return: string The grade item idnumber

get_grade_item()   X-Ref
Returns this grade_item. This method is also available in
grade_category, for cases where the object type is not know.

return: grade_item

set_sortorder($sortorder)   X-Ref
Sets the sortorder of this grade_item. This method is also available in
grade_category, for cases where the object type is not know.

param: int $sortorder

move_after_sortorder($sortorder)   X-Ref
Update this grade item's sortorder so that it will appear after $sortorder

param: int $sortorder The sort order to place this grade item after

fix_duplicate_sortorder($courseid)   X-Ref
Detect duplicate grade item's sortorder and re-sort them.
Note: Duplicate sortorder will be introduced while duplicating activities or
merging two courses.

param: int $courseid id of the course for which grade_items sortorder need to be fixed.

get_name($fulltotal=false, $escape = true)   X-Ref
Returns the most descriptive field for this object.

Determines what type of grade item it is then returns the appropriate string

param: bool $fulltotal If the item is a category total, returns $categoryname."total" instead of "Category total" or "Course total"
param: bool $escape Whether the returned category name is to be HTML escaped or not.
return: string name

get_description()   X-Ref
A grade item can return a more detailed description which will be added to the header of the column/row in some reports.

return: string description

set_parent($parentid, $updateaggregationfields = true)   X-Ref
Sets this item's categoryid. A generic method shared by objects that have a parent id of some kind.

param: int $parentid The ID of the new parent
param: bool $updateaggregationfields Whether or not to convert the aggregation fields when switching between category.
return: bool True if success

set_aggregation_fields_for_aggregation($from, $to)   X-Ref
Update the aggregation fields when the aggregation changed.

This method should always be called when the aggregation has changed, but also when
the item was moved to another category, even it if uses the same aggregation method.

Some values such as the weight only make sense within a category, once moved the
values should be reset to let the user adapt them accordingly.

Note that this method does not save the grade item.
{@link grade_item::update()} has to be called manually after using this method.

param: int $from Aggregation method constant value.
param: int $to   Aggregation method constant value.
return: boolean   True when at least one field was changed, false otherwise

bounded_grade($gradevalue)   X-Ref
Makes sure value is a valid grade value.

param: float $gradevalue
return: mixed float or int fixed grade value

depends_on($reset_cache=false)   X-Ref
Finds out on which other items does this depend directly when doing calculation or category aggregation

param: bool $reset_cache
return: array of grade_item IDs this one depends on

refresh_grades($userid=0)   X-Ref
Refetch grades from modules, plugins.

param: int $userid optional, limit the refetch to a single user
return: bool Returns true on success or if there is nothing to do

update_final_grade($userid, $finalgrade = false, $source = null, $feedback = false,$feedbackformat = FORMAT_MOODLE, $usermodified = null, $timemodified = null, $isbulkupdate = false)   X-Ref
Updates final grade value for given user, this is a only way to update final
grades from gradebook and import because it logs the change in history table
and deals with overridden flag. This flag is set to prevent later overriding
from raw grades submitted from modules.

param: int $userid The graded user
param: float|false $finalgrade The float value of final grade, false means do not change
param: string $source The modification source
param: string $feedback Optional teacher feedback
param: int $feedbackformat A format like FORMAT_PLAIN or FORMAT_HTML
param: int $usermodified The ID of the user making the modification
param: int $timemodified Optional parameter to set the time modified, if not present current time.
param: bool $isbulkupdate If bulk grade update is happening.
return: bool success

update_raw_grade($userid, $rawgrade = false, $source = null, $feedback = false,$feedbackformat = FORMAT_MOODLE, $usermodified = null, $dategraded = null, $datesubmitted=null,$grade = null, array $feedbackfiles = [], $isbulkupdate = false)   X-Ref
Updates raw grade value for given user, this is a only way to update raw
grades from external source (modules, etc.),
because it logs the change in history table and deals with final grade recalculation.

param: int $userid the graded user
param: mixed $rawgrade float value of raw grade - false means do not change
param: string $source modification source
param: string $feedback optional teacher feedback
param: int $feedbackformat A format like FORMAT_PLAIN or FORMAT_HTML
param: int $usermodified the ID of the user who did the grading
param: int $dategraded A timestamp of when the student's work was graded
param: int $datesubmitted A timestamp of when the student's work was submitted
param: grade_grade $grade A grade object, useful for bulk upgrades
param: array $feedbackfiles An array identifying the location of files we want to copy to the gradebook feedback area.
param: bool $isbulkupdate If bulk grade update is happening.
return: bool success

compute($userid=null)   X-Ref
Calculates final grade values using the formula in the calculation property.
The parameters are taken from final grades of grade items in current course only.

param: int $userid Supply a user ID to limit the calculations to the grades of a single user
return: bool false if error

use_formula($userid, $params, $useditems, $oldgrade)   X-Ref
Internal function that does the final grade calculation

param: int $userid The user ID
param: array $params An array of grade items of the form {'gi'.$itemid]} => $finalgrade
param: array $useditems An array of grade item IDs that this grade item depends on plus its own ID
param: grade_grade $oldgrade A grade_grade instance containing the old values from the database
return: bool False if an error occurred

validate_formula($formulastr)   X-Ref
Validate the formula.

param: string $formulastr
return: bool true if calculation possible, false otherwise

get_displaytype()   X-Ref
Returns the value of the display type

It can be set at 3 levels: grade_item, course setting and site. The lowest level overrides the higher ones.

return: int Display type

get_decimals()   X-Ref
Returns the value of the decimals field

It can be set at 3 levels: grade_item, course setting and site. The lowest level overrides the higher ones.

return: int Decimals (0 - 5)

get_formatted_range($rangesdisplaytype=null, $rangesdecimalpoints=null)   X-Ref
Returns a string representing the range of grademin - grademax for this grade item.

param: int $rangesdisplaytype
param: int $rangesdecimalpoints
return: string

get_coefstring()   X-Ref
Queries parent categories recursively to find the aggregationcoef type that applies to this grade item.

return: string|false Returns the coefficient string of false is no coefficient is being used

can_control_visibility()   X-Ref
Returns whether the grade item can control the visibility of the grades

return: bool

notify_changed($deleted)   X-Ref
Used to notify the completion system (if necessary) that a user's grade
has changed, and clear up a possible score cache.

param: bool $deleted True if grade was actually deleted

get_context()   X-Ref
Helper function to get the accurate context for this grade column.

return: context