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

Inheritance diagram for grade_grade:

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

Copyright: 2006 Nicolas Connault

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 $items array of all grade item ids

Return values

void

◆ delete()

grade_grade::delete ( $source = null )

Deletes the grade_grade instance from the database.

Parameters

string $source The location the deletion occurred (mod/forum, manual, etc.).

Return values

bool	Returns 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 $params associative arrays varname=>value

Return values

grade_grade Returns 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 $params associative arrays varname=>value

Return values

array array 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	$table	The table to retrieve from
string	$classname	The name of the class to instantiate
array	$params	An array of conditions like $fieldname => $fieldvalue

Return values

array|bool Array 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	$table	The table to retrieve from
string	$classname	The name of the class to instantiate
array	$params	An array of conditions like $fieldname => $fieldvalue

Return values

mixed An 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_missing	include grades that do not exist yet

Return values

array userid=>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	$dependson	Array to flatten
array	$dependencydepth	Array of itemids => depth. Initially these should be all set to 1.

Return values

array Flattened array

◆ 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

string One 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

int Timestamp

◆ 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

float The 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

float The 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

array A 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

int	0 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_grades	all course grades of one user, & used for better internal caching
array	$grade_items	array of grade items, & used for better internal caching

Return values

array This 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\$locktime timestamp 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	$source	From where was the object inserted (mod/forum, manual, etc.)
string	$isbulkupdate	If bulk grade update is happening.

Return values

int	The 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

bool	True 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

bool	true 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

bool	true 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

bool	True if locked, false if not

◆ is_overridden()

grade_grade::is_overridden ( )

Checks if grade overridden.

Return values

bool	True 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_item An 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_item The 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	$deleted	True if grade was actually deleted
bool	$isbulkupdate	If 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 $state requested excluded state

Return values

bool	True 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	$hidden	new hidden status
bool	$cascade	ignored

Reimplemented from grade_object.

◆ set_locked()

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

Lock/unlock this grade.

Parameters

int	$lockedstate	0, 1 or a timestamp int(10) after which date the item will be locked.
bool	$cascade	Ignored param
bool	$refresh	Refresh grades when unlocking

Return values

bool	True 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 $locktime timestamp for lock to activate

Return values

void

◆ set_overridden()

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

Set the overridden status of grade.

Parameters

bool	$state	requested overridden state
bool	$refresh	refresh grades from external activities if needed

Return values

bool	true 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	$instance	The object to set the properties on
array	$params	An array of properties to set like $propertyname => $propertyvalue

Return values

array|stdClass Either 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

float Converted 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	$source	from where was the object inserted (mod/forum, manual, etc.)
bool	$isbulkupdate	If bulk grade update is happening.

Return values

bool success

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

bool	True 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:

lib/grade/grade_grade.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Function Documentation

◆ add_feedback_files()

◆ can_control_visibility()

◆ check_locktime_all()

◆ delete()

◆ delete_feedback_files()

◆ fetch()

◆ fetch_all()

◆ fetch_all_helper()

◆ fetch_helper()

◆ fetch_users_grades()

◆ flatten_dependencies_array()

◆ get_aggregation_hint()

◆ get_aggregationstatus()

◆ get_aggregationweight()

◆ get_context()

◆ get_dategraded()

◆ get_datesubmitted()

◆ get_grade_max()

◆ get_grade_min()

◆ get_grade_min_and_max()

◆ get_hidden()

◆ get_hiding_affected()

◆ get_locktime()

◆ get_record_data()

◆ insert()

◆ is_editable()

◆ is_excluded()

◆ is_hidden()

◆ is_hiddenuntil()

◆ is_locked()

◆ is_overridden()

◆ is_passed()

◆ load_grade_item()

◆ load_optional_fields()

◆ notify_changed() [1/2]

◆ notify_changed() [2/2]

◆ set_aggregationstatus()

◆ set_aggregationweight()

◆ set_excluded()

◆ set_hidden()

◆ set_locked()

◆ set_locktime()

◆ set_overridden()

◆ set_properties()

◆ standardise_score()

◆ update()

◆ update_feedback_files()

◆ update_from_db()

Member Data Documentation

◆ $aggregationstatus

◆ $aggregationweight

◆ $feedback

◆ $feedbackfiles

◆ $feedbackformat

◆ $finalgrade

◆ $grade_item

◆ $id

◆ $information

◆ $informationformat

◆ $itemid

◆ $label

◆ $rawgrade

◆ $rawgrademax

◆ $rawgrademin

◆ $rawscaleid

◆ $required_fields

◆ $table

◆ $userid

◆ $usermodified