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 an individual user's grade

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

Defines 1 class


Class: grade_grade  - X-Ref

grade_grades is an object mapped to DB table {prefix}grade_grades

fetch_users_grades($grade_item, $userids, $include_missing=true)   X-Ref
Returns array of grades for given grade_item+users

param: grade_item $grade_item
param: array $userids
param: bool $include_missing include grades that do not exist yet
return: array userid=>grade_grade array

load_grade_item()   X-Ref
Loads the grade_item object referenced by $this->itemid and saves it as $this->grade_item for easy access

return: grade_item The grade_item instance referenced by $this->itemid

is_editable()   X-Ref
Is grading object editable?

return: bool

is_locked()   X-Ref
Check grade lock status. Uses both grade item lock and grade lock.
Internally any date in locked field (including future ones) means locked,
the date is stored for logging purposes only.

return: bool True if locked, false if not

is_overridden()   X-Ref
Checks if grade overridden

return: bool True if grade is overriden

get_datesubmitted()   X-Ref
Returns timestamp of submission related to this grade, null if not submitted.

return: int Timestamp

get_aggregationweight()   X-Ref
Returns the weight this grade contributed to the aggregated grade

return: float|null

set_aggregationweight($aggregationweight)   X-Ref
Set aggregationweight.

param: float $aggregationweight
return: void

get_aggregationstatus()   X-Ref
Returns the info on how this value was used in the aggregated grade

return: string One of 'dropped', 'excluded', 'novalue', 'used' or 'extra'

set_aggregationstatus($aggregationstatus)   X-Ref
Set aggregationstatus flag

param: string $aggregationstatus
return: void

get_grade_min_and_max()   X-Ref
Returns the minimum and maximum number of points this grade is graded with respect to.

return: array A list containing, in order, the minimum and maximum number of points.

get_grade_min()   X-Ref
Returns the minimum number of points this grade is graded with.

return: float The minimum number of points

get_grade_max()   X-Ref
Returns the maximum number of points this grade is graded with respect to.

return: float The maximum number of points

get_dategraded()   X-Ref
Returns timestamp when last graded, null if no grade present

return: int

set_overridden($state, $refresh = true)   X-Ref
Set the overridden status of grade

param: bool $state requested overridden state
param: bool $refresh refresh grades from external activities if needed
return: bool true is db state changed

is_excluded()   X-Ref
Checks if grade excluded from aggregation functions

return: bool True if grade is excluded from aggregation

set_excluded($state)   X-Ref
Set the excluded status of grade

param: bool $state requested excluded state
return: bool True is database state changed

set_locked($lockedstate, $cascade=false, $refresh=true)   X-Ref
Lock/unlock this grade.

param: int $lockedstate 0, 1 or a timestamp int(10) after which date the item will be locked.
param: bool $cascade Ignored param
param: bool $refresh Refresh grades when unlocking
return: bool True if successful, false if can not set new lock state for grade

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

param: array $items array of all grade item ids
return: void

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

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

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

return: int $locktime timestamp for lock to activate

is_hidden()   X-Ref
Check grade hidden status. Uses data from both grade item and grade.

return: bool true if hidden, false if not

is_hiddenuntil()   X-Ref
Check grade hidden status. Uses data from both grade item and grade.

return: bool true if hiddenuntil, false if not

get_hidden()   X-Ref
Check grade hidden status. Uses data from both grade item and grade.

return: int 0 means visible, 1 hidden always, timestamp hidden until

set_hidden($hidden, $cascade=false)   X-Ref
Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.

param: int $hidden new hidden status
param: bool $cascade ignored

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

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

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

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

standardise_score($rawgrade, $source_min, $source_max, $target_min, $target_max)   X-Ref
Given a float value situated between a source minimum and a source maximum, converts it to the
corresponding value situated between a target minimum and a target maximum. Thanks to Darlene
for the formula :-)

param: float $rawgrade
param: float $source_min
param: float $source_max
param: float $target_min
param: float $target_max
return: float Converted value

flatten_dependencies_array(&$dependson, &$dependencydepth)   X-Ref
Given an array like this:
$a = array(1=>array(2, 3),
2=>array(4),
3=>array(1),
4=>array())
this function fully resolves the dependencies so each value will be an array of
the all items this item depends on and their dependencies (and their dependencies...).
It should not explode if there are circular dependencies.
The dependency depth array will list the number of branches in the tree above each leaf.

param: array $dependson Array to flatten
param: array $dependencydepth Array of itemids => depth. Initially these should be all set to 1.
return: array Flattened array

get_hiding_affected(&$grade_grades, &$grade_items)   X-Ref
Return array of grade item ids that are either hidden or indirectly depend
on hidden grades, excluded grades are not returned.
THIS IS A REALLY BIG HACK! to be replaced by conditional aggregation of hidden grades in 2.0

param: array $grade_grades all course grades of one user, & used for better internal caching
param: array $grade_items array of grade items, & used for better internal caching
return: array This is an array of following arrays:

is_passed($grade_item = null)   X-Ref
Returns true if the grade's value is superior or equal to the grade item's gradepass value, false otherwise.

param: grade_item $grade_item An optional grade_item of which gradepass value we can use, saves having to load the grade_grade's grade_item
return: bool

update($source=null, $isbulkupdate = false)   X-Ref
In addition to update() as defined in grade_object rounds the float numbers using php function,
the reason is we need to compare the db value with computed number to skip updates 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

add_feedback_files(int $historyid = null)   X-Ref
Handles adding feedback files in the gradebook.

param: int|null $historyid

update_feedback_files(int $historyid = null)   X-Ref
Handles updating feedback files in the gradebook.

param: int|null $historyid

delete_feedback_files()   X-Ref
Handles deleting feedback files in the gradebook.


delete($source = null)   X-Ref
Deletes the grade_grade instance from the database.

param: string $source The location the deletion occurred (mod/forum, manual, etc.).
return: bool Returns true if the deletion was successful, false otherwise.

notify_changed($deleted, $isbulkupdate = false)   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
param: bool $isbulkupdate If bulk grade update is happening.

get_aggregation_hint()   X-Ref
Get some useful information about how this grade_grade is reflected in the aggregation
for the grade_category. For example this could be an extra credit item, and it could be
dropped because it's in the X lowest or highest.

return: array(status, weight) - A keyword and a numerical weight that represents how this grade was included in the aggregation.

copy_feedback_files(context $context, string $filearea, int $itemid)   X-Ref
Handles copying feedback files to a specified gradebook file area.

param: context $context
param: string $filearea
param: int $itemid

get_context()   X-Ref
Determine the correct context for this grade_grade.

return: context