Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
grade_grade Class Reference

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

Inheritance diagram for grade_grade:
grade_object core_grades\privacy\grade_grade_with_history

Public Member Functions

 can_control_visibility ()
 Returns whether the grade object can control the visibility of the grades.
 
 delete ($source=null)
 Deletes the grade_grade instance from the database.
 
 get_aggregation_hint ()
 Get some useful information about how this grade_grade is reflected in the aggregation for the grade_category.
 
 get_aggregationstatus ()
 Returns the info on how this value was used in the aggregated grade.
 
 get_aggregationweight ()
 Returns the weight this grade contributed to the aggregated grade.
 
 get_context ()
 Determine the correct context for this grade_grade.
 
 get_dategraded ()
 Returns timestamp when last graded, null if no grade present.
 
 get_datesubmitted ()
 Returns timestamp of submission related to this grade, null if not submitted.
 
 get_grade_max ()
 Returns the maximum number of points this grade is graded with respect to.
 
 get_grade_min ()
 Returns the minimum number of points this grade is graded with.
 
 get_hidden ()
 Check grade hidden status.
 
 get_locktime ()
 Get the locktime for this grade.
 
 get_record_data ()
 Returns object with fields and values that are defined in database.
 
 insert ($source=null, $isbulkupdate=false)
 Records this object in the Database, sets its id to the returned value, and returns that value.
 
 is_editable ()
 Is grading object editable?
 
 is_excluded ()
 Checks if grade excluded from aggregation functions.
 
 is_hidden ()
 Check grade hidden status.
 
 is_hiddenuntil ()
 Check grade hidden status.
 
 is_locked ()
 Check grade lock status.
 
 is_overridden ()
 Checks if grade overridden.
 
 is_passed ($grade_item=null)
 Returns true if the grade's value is superior or equal to the grade item's gradepass value, false otherwise.
 
 load_grade_item ()
 Loads the grade_item object referenced by $this->itemid and saves it as $this->grade_item for easy access.
 
 load_optional_fields ()
 Makes sure all the optional fields are loaded.
 
 set_aggregationstatus ($aggregationstatus)
 Set aggregationstatus flag.
 
 set_aggregationweight ($aggregationweight)
 Set aggregationweight.
 
 set_excluded ($state)
 Set the excluded status of grade.
 
 set_hidden ($hidden, $cascade=false)
 Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.
 
 set_locked ($lockedstate, $cascade=false, $refresh=true)
 Lock/unlock this grade.
 
 set_locktime ($locktime)
 Set the locktime for this grade.
 
 set_overridden ($state, $refresh=true)
 Set the overridden status of grade.
 
 update ($source=null, $isbulkupdate=false)
 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.
 
 update_from_db ()
 Using this object's id field, fetches the matching record in the DB, and looks at each variable in turn.
 

Static Public Member Functions

static check_locktime_all ($items)
 Lock the grade if needed.
 
static fetch ($params)
 Finds and returns a grade_grade instance based on params.
 
static fetch_all ($params)
 Finds and returns all grade_grade instances based on params.
 
static fetch_all_helper ($table, $classname, $params)
 Factory method which uses the parameters to retrieve all matching instances from the database.
 
static fetch_users_grades ($grade_item, $userids, $include_missing=true)
 Returns array of grades for given grade_item+users.
 
static get_hiding_affected (&$grade_grades, &$grade_items)
 Return array of grade item ids that are either hidden or indirectly depend on hidden grades, excluded grades are not returned.
 
static set_properties (&$instance, $params)
 Given an associated array or object, cycles through each key/variable and assigns the value to the corresponding variable in this object.
 
static standardise_score ($rawgrade, $source_min, $source_max, $target_min, $target_max)
 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.
 

Public Attributes

string $aggregationstatus = 'unknown'
 Aggregation status flag.
 
float $aggregationweight = null
 Aggregation weight is the specific weight used in the aggregation calculation for this grade.
 
bool $excluded = 0
 Grade excluded from aggregation functions $excluded.
 
bool $exported = 0
 Exported flag $exported.
 
string $feedback
 Feedback content.
 
array $feedbackfiles = []
 Feedback files to copy.
 
int $feedbackformat = FORMAT_PLAIN
 Feedback format.
 
float $finalgrade
 The final value of this grade.
 
grade_item $grade_item
 The grade_item object referenced by $this->itemid.
 
float $hidden = 0
 0 if visible, 1 always hidden or date not visible until $hidden
 
int $id
 The PK.
 
string $information
 Information text.
 
int $informationformat = FORMAT_PLAIN
 Information text format.
 
int $itemid
 The id of the grade_item this grade belongs to.
 
string $label
 label text.
 
float $locked = 0
 0 not locked, date when the item was locked locked
 
float $locktime = 0
 0 no automatic locking, date when to lock the grade automatically $locktime
 
array $optional_fields = array('feedback'=>null, 'feedbackformat'=>0, 'information'=>null, 'informationformat'=>0)
 Array of optional fields with default values (these should match db defaults) $optional_fields.
 
bool $overridden = 0
 Overridden flag $overridden.
 
float $rawgrade
 The grade value of this raw grade, if such was provided by the module.
 
float $rawgrademax = 100
 The maximum allowable grade when this grade was created.
 
float $rawgrademin = 0
 The minimum allowable grade when this grade was created.
 
int $rawscaleid
 id of the scale, if this grade is based on a scale.
 
array $required_fields
 Array of required table fields, must start with 'id'.
 
string $table = 'grade_grades'
 The DB table.
 
bool $timecreated = null
 TODO: HACK: create a new field datesubmitted - the date of submission if any (MDL-31377) $timecreated.
 
bool $timemodified = null
 TODO: HACK: create a new field dategraded - the date of grading (MDL-31378) $timemodified.
 
int $userid
 The id of the user this grade belongs to.
 
int $usermodified
 The userid of the person who last modified this grade.
 

Protected Member Functions

 add_feedback_files (int $historyid=null)
 Handles adding feedback files in the gradebook.
 
 delete_feedback_files ()
 Handles deleting feedback files in the gradebook.
 
 get_grade_min_and_max ()
 Returns the minimum and maximum number of points this grade is graded with respect to.
 
 notify_changed ($deleted, $isbulkupdate=false)
 Used to notify the completion system (if necessary) that a user's grade has changed, and clear up a possible score cache.
 
 notify_changed ($deleted)
 Called immediately after the object data has been inserted, updated, or deleted in the database.
 
 update_feedback_files (int $historyid=null)
 Handles updating feedback files in the gradebook.
 

Static Protected Member Functions

static fetch_helper ($table, $classname, $params)
 Factory method which uses the parameters to retrieve matching instances from the database.
 
static flatten_dependencies_array (&$dependson, &$dependencydepth)
 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...).
 

Detailed Description

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

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ add_feedback_files()

grade_grade::add_feedback_files ( int $historyid = null)
protected

Handles adding feedback files in the gradebook.

Parameters
int | null$historyid

Reimplemented from grade_object.

◆ can_control_visibility()

grade_object::can_control_visibility ( )
inherited

Returns whether the grade object can control the visibility of the grades.

Return values
bool

Reimplemented in grade_item.

◆ check_locktime_all()

static grade_grade::check_locktime_all ( $items)
static

Lock the grade if needed.

Make sure this is called only when final grades are valid

Parameters
array$itemsarray of all grade item ids
Return values
void

◆ delete()

grade_grade::delete ( $source = null)

Deletes the grade_grade instance from the database.

Parameters
string$sourceThe location the deletion occurred (mod/forum, manual, etc.).
Return values
boolReturns true if the deletion was successful, false otherwise.

Reimplemented from grade_object.

◆ delete_feedback_files()

grade_grade::delete_feedback_files ( )
protected

Handles deleting feedback files in the gradebook.

Reimplemented from grade_object.

◆ fetch()

static grade_grade::fetch ( $params)
static

Finds and returns a grade_grade instance based on params.

Parameters
array$paramsassociative arrays varname=>value
Return values
grade_gradeReturns a grade_grade instance or false if none found

Reimplemented from grade_object.

◆ fetch_all()

static grade_grade::fetch_all ( $params)
static

Finds and returns all grade_grade instances based on params.

Parameters
array$paramsassociative arrays varname=>value
Return values
arrayarray of grade_grade instances or false if none found.

Reimplemented from grade_object.

◆ fetch_all_helper()

static grade_object::fetch_all_helper ( $table,
$classname,
$params )
staticinherited

Factory method which uses the parameters to retrieve all matching instances from the database.

Parameters
string$tableThe table to retrieve from
string$classnameThe name of the class to instantiate
array$paramsAn array of conditions like $fieldname => $fieldvalue
Return values
array|boolArray of object instances or false if not found

◆ fetch_helper()

static grade_object::fetch_helper ( $table,
$classname,
$params )
staticprotectedinherited

Factory method which uses the parameters to retrieve matching instances from the database.

Parameters
string$tableThe table to retrieve from
string$classnameThe name of the class to instantiate
array$paramsAn array of conditions like $fieldname => $fieldvalue
Return values
mixedAn object instance or false if not found

◆ fetch_users_grades()

static grade_grade::fetch_users_grades ( $grade_item,
$userids,
$include_missing = true )
static

Returns array of grades for given grade_item+users.

Parameters
grade_item$grade_item
array$userids
bool$include_missinginclude grades that do not exist yet
Return values
arrayuserid=>grade_grade array

◆ flatten_dependencies_array()

static grade_grade::flatten_dependencies_array ( & $dependson,
& $dependencydepth )
staticprotected

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.

Parameters
array$dependsonArray to flatten
array$dependencydepthArray of itemids => depth. Initially these should be all set to 1.
Return values
bool|null

◆ get_aggregation_hint()

grade_grade::get_aggregation_hint ( )

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 values
array(status,weight)- A keyword and a numerical weight that represents how this grade was included in the aggregation.

◆ get_aggregationstatus()

grade_grade::get_aggregationstatus ( )

Returns the info on how this value was used in the aggregated grade.

Return values
stringOne of 'dropped', 'excluded', 'novalue', 'used' or 'extra'

◆ get_aggregationweight()

grade_grade::get_aggregationweight ( )

Returns the weight this grade contributed to the aggregated grade.

Return values
float|null

◆ get_context()

grade_grade::get_context ( )

Determine the correct context for this grade_grade.

Return values
context

◆ get_dategraded()

grade_grade::get_dategraded ( )

Returns timestamp when last graded, null if no grade present.

Return values
?int

◆ get_datesubmitted()

grade_grade::get_datesubmitted ( )

Returns timestamp of submission related to this grade, null if not submitted.

Return values
intTimestamp

◆ get_grade_max()

grade_grade::get_grade_max ( )

Returns the maximum number of points this grade is graded with respect to.

Since
Moodle 2.8.7, 2.9.1
Return values
floatThe maximum number of points

◆ get_grade_min()

grade_grade::get_grade_min ( )

Returns the minimum number of points this grade is graded with.

Since
Moodle 2.8.7, 2.9.1
Return values
floatThe minimum number of points

◆ get_grade_min_and_max()

grade_grade::get_grade_min_and_max ( )
protected

Returns the minimum and maximum number of points this grade is graded with respect to.

Since
Moodle 2.8.7, 2.9.1
Return values
arrayA list containing, in order, the minimum and maximum number of points.

◆ get_hidden()

grade_grade::get_hidden ( )

Check grade hidden status.

Uses data from both grade item and grade.

Return values
int0 means visible, 1 hidden always, timestamp hidden until

Reimplemented from grade_object.

◆ get_hiding_affected()

static grade_grade::get_hiding_affected ( & $grade_grades,
& $grade_items )
static

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

Parameters
array$grade_gradesall course grades of one user, & used for better internal caching
array$grade_itemsarray of grade items, & used for better internal caching
Return values
arrayThis is an array of following arrays: unknown => list of item ids that may be affected by hiding (with the ITEM ID as both the key and the value) - for BC with old gradereport plugins unknowngrades => list of item ids that may be affected by hiding (with the calculated grade as the value) altered => list of item ids that are definitely affected by hiding (with the calculated grade as the value) alteredgrademax => for each item in altered or unknown, the new value of the grademax alteredgrademin => for each item in altered or unknown, the new value of the grademin alteredgradestatus => for each item with a modified status - the value of the new status alteredgradeweight => for each item with a modified weight - the value of the new weight

◆ get_locktime()

grade_grade::get_locktime ( )

Get the locktime for this grade.

Return values
int\$locktimetimestamp for lock to activate

◆ get_record_data()

grade_object::get_record_data ( )
inherited

Returns object with fields and values that are defined in database.

Return values
stdClass

◆ insert()

grade_object::insert ( $source = null,
$isbulkupdate = false )
inherited

Records this object in the Database, sets its id to the returned value, and returns that value.

If successful this function also fetches the new object data from database and stores it in object properties.

Parameters
string$sourceFrom where was the object inserted (mod/forum, manual, etc.)
string$isbulkupdateIf bulk grade update is happening.
Return values
intThe new grade object ID if successful, false otherwise

Reimplemented in grade_category, grade_item, grade_outcome, and grade_scale.

◆ is_editable()

grade_grade::is_editable ( )

Is grading object editable?

Return values
bool

◆ is_excluded()

grade_grade::is_excluded ( )

Checks if grade excluded from aggregation functions.

Return values
boolTrue if grade is excluded from aggregation

◆ is_hidden()

grade_grade::is_hidden ( )

Check grade hidden status.

Uses data from both grade item and grade.

Return values
booltrue if hidden, false if not

Reimplemented from grade_object.

◆ is_hiddenuntil()

grade_grade::is_hiddenuntil ( )

Check grade hidden status.

Uses data from both grade item and grade.

Return values
booltrue if hiddenuntil, false if not

Reimplemented from grade_object.

◆ is_locked()

grade_grade::is_locked ( )

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 values
boolTrue if locked, false if not

◆ is_overridden()

grade_grade::is_overridden ( )

Checks if grade overridden.

Return values
boolTrue if grade is overriden

◆ is_passed()

grade_grade::is_passed ( $grade_item = null)

Returns true if the grade's value is superior or equal to the grade item's gradepass value, false otherwise.

Parameters
grade_item$grade_itemAn optional grade_item of which gradepass value we can use, saves having to load the grade_grade's grade_item
Return values
?bool

◆ load_grade_item()

grade_grade::load_grade_item ( )

Loads the grade_item object referenced by $this->itemid and saves it as $this->grade_item for easy access.

Return values
?grade_itemThe grade_item instance referenced by $this->itemid

◆ load_optional_fields()

grade_object::load_optional_fields ( )
inherited

Makes sure all the optional fields are loaded.

If id present, meaning the instance exists in the database, then data will be fetched from the database. Defaults are used for new instances.

◆ notify_changed() [1/2]

grade_grade::notify_changed ( $deleted,
$isbulkupdate = false )
protected

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

Parameters
bool$deletedTrue if grade was actually deleted
bool$isbulkupdateIf bulk grade update is happening.

◆ notify_changed() [2/2]

grade_object::notify_changed ( $deleted)
protectedinherited

Called immediately after the object data has been inserted, updated, or deleted in the database.

Default does nothing, can be overridden to hook in special behaviour.

Parameters
bool$deleted

Reimplemented in grade_category, and grade_item.

◆ set_aggregationstatus()

grade_grade::set_aggregationstatus ( $aggregationstatus)

Set aggregationstatus flag.

Parameters
string$aggregationstatus
Return values
void

◆ set_aggregationweight()

grade_grade::set_aggregationweight ( $aggregationweight)

Set aggregationweight.

Parameters
float$aggregationweight
Return values
void

◆ set_excluded()

grade_grade::set_excluded ( $state)

Set the excluded status of grade.

Parameters
bool$staterequested excluded state
Return values
boolTrue is database state changed

◆ set_hidden()

grade_grade::set_hidden ( $hidden,
$cascade = false )

Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.

Parameters
int$hiddennew hidden status
bool$cascadeignored

Reimplemented from grade_object.

◆ set_locked()

grade_grade::set_locked ( $lockedstate,
$cascade = false,
$refresh = true )

Lock/unlock this grade.

Parameters
int$lockedstate0, 1 or a timestamp int(10) after which date the item will be locked.
bool$cascadeIgnored param
bool$refreshRefresh grades when unlocking
Return values
boolTrue if successful, false if can not set new lock state for grade

◆ set_locktime()

grade_grade::set_locktime ( $locktime)

Set the locktime for this grade.

Parameters
int$locktimetimestamp for lock to activate
Return values
void

◆ set_overridden()

grade_grade::set_overridden ( $state,
$refresh = true )

Set the overridden status of grade.

Parameters
bool$staterequested overridden state
bool$refreshrefresh grades from external activities if needed
Return values
booltrue is db state changed

◆ set_properties()

static grade_object::set_properties ( & $instance,
$params )
staticinherited

Given an associated array or object, cycles through each key/variable and assigns the value to the corresponding variable in this object.

Parameters
grade_object$instanceThe object to set the properties on
array$paramsAn array of properties to set like $propertyname => $propertyvalue
Return values
array|stdClassEither an associative array or an object containing property name, property value pairs

Reimplemented in grade_category.

◆ standardise_score()

static grade_grade::standardise_score ( $rawgrade,
$source_min,
$source_max,
$target_min,
$target_max )
static

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 :-)

Parameters
float$rawgrade
float$source_min
float$source_max
float$target_min
float$target_max
Return values
?floatConverted value

◆ update()

grade_grade::update ( $source = null,
$isbulkupdate = false )

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.

Parameters
string$sourcefrom where was the object inserted (mod/forum, manual, etc.)
bool$isbulkupdateIf bulk grade update is happening.
Return values
boolsuccess

Reimplemented from grade_object.

◆ update_feedback_files()

grade_grade::update_feedback_files ( int $historyid = null)
protected

Handles updating feedback files in the gradebook.

Parameters
int | null$historyid

Reimplemented from grade_object.

◆ update_from_db()

grade_object::update_from_db ( )
inherited

Using this object's id field, fetches the matching record in the DB, and looks at each variable in turn.

If the DB has different data, the db's data is used to update the object. This is different from the update() function, which acts on the DB record based on the object.

Return values
boolTrue if successful

Member Data Documentation

◆ $aggregationstatus

string grade_grade::$aggregationstatus = 'unknown'

Aggregation status flag.

Can be one of 'unknown', 'dropped', 'novalue' or 'used'. $aggregationstatus

◆ $aggregationweight

float grade_grade::$aggregationweight = null

Aggregation weight is the specific weight used in the aggregation calculation for this grade.

$aggregationweight

◆ $feedback

string grade_grade::$feedback

Feedback content.

$feedback

◆ $feedbackfiles

array grade_grade::$feedbackfiles = []

Feedback files to copy.

Example -

[ 'contextid' => 1, 'component' => 'mod_xyz', 'filearea' => 'mod_xyz_feedback', 'itemid' => 2 ];

◆ $feedbackformat

int grade_grade::$feedbackformat = FORMAT_PLAIN

Feedback format.

$feedbackformat

◆ $finalgrade

float grade_grade::$finalgrade

The final value of this grade.

$finalgrade

◆ $grade_item

grade_item grade_grade::$grade_item

The grade_item object referenced by $this->itemid.

$grade_item

◆ $id

int grade_object::$id
inherited

The PK.

$id

◆ $information

string grade_grade::$information

Information text.

$information

◆ $informationformat

int grade_grade::$informationformat = FORMAT_PLAIN

Information text format.

$informationformat

◆ $itemid

int grade_grade::$itemid

The id of the grade_item this grade belongs to.

$itemid

◆ $label

string grade_grade::$label

label text.

$label

◆ $rawgrade

float grade_grade::$rawgrade

The grade value of this raw grade, if such was provided by the module.

$rawgrade

◆ $rawgrademax

float grade_grade::$rawgrademax = 100

The maximum allowable grade when this grade was created.

$rawgrademax

◆ $rawgrademin

float grade_grade::$rawgrademin = 0

The minimum allowable grade when this grade was created.

$rawgrademin

◆ $rawscaleid

int grade_grade::$rawscaleid

id of the scale, if this grade is based on a scale.

$rawscaleid

◆ $required_fields

array grade_grade::$required_fields
Initial value:
= array('id', 'itemid', 'userid', 'rawgrade', 'rawgrademax', 'rawgrademin',
'rawscaleid', 'usermodified', 'finalgrade', 'hidden', 'locked',
'locktime', 'exported', 'overridden', 'excluded', 'timecreated',
'timemodified', 'aggregationstatus', 'aggregationweight')

Array of required table fields, must start with 'id'.

$required_fields

◆ $table

string grade_grade::$table = 'grade_grades'

The DB table.

$table

◆ $userid

int grade_grade::$userid

The id of the user this grade belongs to.

$userid

◆ $usermodified

int grade_grade::$usermodified

The userid of the person who last modified this grade.

$usermodified


The documentation for this class was generated from the following file: