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 category

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

Defines 1 class


Class: grade_category  - X-Ref

grade_category is an object mapped to DB table {prefix}grade_categories

build_path($grade_category)   X-Ref
Builds this category's path string based on its parents (if any) and its own id number.
This is typically done just before inserting this object in the DB for the first time,
or when a new parent is added or changed. It is a recursive function: once the calling
object no longer has a parent, the path is complete.

param: grade_category $grade_category A Grade_Category object
return: string The category's path string

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

param: array $params associative arrays varname=>value
return: grade_category The retrieved grade_category instance or false if none found.

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

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

update($source = null, $isbulkupdate = false)   X-Ref
In addition to update() as defined in grade_object, call force_regrading of parent categories, if applicable.

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

delete($source=null)   X-Ref
If parent::delete() is successful, send force_regrading message to parent category.

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

insert($source = null, $isbulkupdate = false)   X-Ref
In addition to the normal insert() defined in grade_object, this method sets the depth
and path for this object, and update the record accordingly.

We do this here instead of in the constructor as they both need to know the record's
ID number, which only gets created at insertion time.
This method also creates an associated grade_item if this wasn't done during construction.

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

insert_course_category($courseid)   X-Ref
Internal function - used only from fetch_course_category()
Normal insert() can not be used for course category

param: int $courseid The course ID
return: int The ID of the new course category

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

force_regrading()   X-Ref
Marks this grade categories' associated grade item as needing regrading


pre_regrade_final_grades()   X-Ref
Something that should be called before we start regrading the whole course.

return: void

generate_grades($userid=null, ?\core\progress\base $progress = null)   X-Ref
Generates and saves final grades in associated category grade item.
These immediate children must already have their own final grades.
The category's aggregation method is used to generate final grades.

Please note that category grade is either calculated or aggregated, not both at the same time.

This method must be used ONLY from grade_item::regrade_final_grades(),
because the calculation must be done in correct order!

Steps to follow:
1. Get final grades from immediate children
3. Aggregate these grades
4. Save them in final grades of associated category grade item

param: int $userid The user ID if final grade generation should be limited to a single user
param: \core\progress\base|null $progress Optional progress indicator
return: bool

aggregate_grades($userid,$items,$grade_values,$oldgrade,$excluded,$grademinoverrides,$grademaxoverrides)   X-Ref
Internal function for grade category grade aggregation

param: int    $userid The User ID
param: array  $items Grade items
param: array  $grade_values Array of grade values
param: object $oldgrade Old grade
param: array  $excluded Excluded
param: array  $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid)
param: array  $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid)

set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit)   X-Ref
Set the flags on the grade_grade items to indicate how individual grades are used
in the aggregation.

WARNING: This function is called a lot during gradebook recalculation, be very performance considerate.

param: int $userid The user we have aggregated the grades for.
param: array $usedweights An array with keys for each of the grade_item columns included in the aggregation. The value are the relative weight.
param: array $novalue An array with keys for each of the grade_item columns skipped because
param: array $dropped An array with keys for each of the grade_item columns dropped
param: array $extracredit An array with keys for each of the grade_item columns

aggregate_values_and_adjust_bounds($grade_values,$items,& $weights = null,$grademinoverrides = array()   X-Ref
Internal function that calculates the aggregated grade and new min/max for this grade category

Must be public as it is used by grade_grade::get_hiding_affected()

param: array $grade_values An array of values to be aggregated
param: array $items The array of grade_items
param: array & $weights If provided, will be filled with the normalized weights
param: array  $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid)
param: array  $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid)
return: array containing values for:

aggregate_values($grade_values, $items)   X-Ref
Internal function that calculates the aggregated grade for this grade category

Must be public as it is used by grade_grade::get_hiding_affected()

param: array $grade_values An array of values to be aggregated
param: array $items The array of grade_items
return: float The aggregate grade for this grade category

auto_update_max()   X-Ref
Some aggregation types may need to update their max grade.

This must be executed after updating the weights as it relies on them.

return: void

auto_update_weights()   X-Ref
Recalculate the weights of the grade items in this category.

The category total is not updated here, a further call to
{@link self::auto_update_max()} is required.

return: void

apply_limit_rules(&$grade_values, $items)   X-Ref
Given an array of grade values (numerical indices) applies droplow or keephigh rules to limit the final array.

param: array $grade_values itemid=>$grade_value float
param: array $items grade item objects
return: array Limited grades.

can_apply_limit_rules()   X-Ref
Returns whether or not we can apply the limit rules.

There are cases where drop lowest or keep highest should not be used
at all. This method will determine whether or not this logic can be
applied considering the current setup of the category.

return: bool

is_extracredit_used()   X-Ref
Returns true if category uses extra credit of any kind

return: bool True if extra credit used

aggregation_uses_extracredit($aggregation)   X-Ref
Returns true if aggregation passed is using extracredit.

param: int $aggregation Aggregation const.
return: bool True if extra credit used

is_aggregationcoef_used()   X-Ref
Returns true if category uses special aggregation coefficient

return: bool True if an aggregation coefficient is being used

aggregation_uses_aggregationcoef($aggregation)   X-Ref
Returns true if aggregation uses aggregationcoef

param: int $aggregation Aggregation const.
return: bool True if an aggregation coefficient is being used

get_coefstring($first=true)   X-Ref
Recursive function to find which weight/extra credit field to use in the grade item form.

param: string $first Whether or not this is the first item in the recursion
return: string

fetch_course_tree($courseid, $include_category_items=false)   X-Ref
Returns tree with all grade_items and categories as elements

param: int $courseid The course ID
param: bool $include_category_items as category children
return: array

_fetch_course_tree_recursion($category_array, &$sortorder)   X-Ref
An internal function that recursively sorts grade categories within a course

param: array $category_array The seed of the recursion
param: int   $sortorder The current sortorder
return: array An array containing 'object', 'type', 'depth' and optionally 'children'

get_children($include_category_items=false)   X-Ref
Fetches and returns all the children categories and/or grade_items belonging to this category.
By default only returns the immediate children (depth=1), but deeper levels can be requested,
as well as all levels (0). The elements are indexed by sort order.

param: bool $include_category_items Whether or not to include category grade_items in the children array
return: array Array of child objects (grade_category and grade_item).

_get_children_recursion($category)   X-Ref
Private method used to retrieve all children of this category recursively

param: grade_category $category Source of current recursion
return: array An array of child grade categories

load_grade_item()   X-Ref
Uses {@link get_grade_item()} to load or create a grade_item, then saves it as $this->grade_item.

return: grade_item

get_grade_item()   X-Ref
Retrieves this grade categories' associated grade_item from the database

If no grade_item exists yet, creates one.

return: grade_item

load_parent_category()   X-Ref
Uses $this->parent to instantiate $this->parent_category based on the referenced record in the DB

return: grade_category The parent category

get_parent_category()   X-Ref
Uses $this->parent to instantiate and return a grade_category object

return: grade_category Returns the parent category or null if this category has no parent

get_name($escape = true)   X-Ref
Returns the most descriptive field for this grade category

param: bool $escape Whether the returned category name is to be HTML escaped or not.
return: string name

get_description()   X-Ref
Describe the aggregation settings for this category so the reports make more sense.

return: string description

set_parent($parentid, $source=null)   X-Ref
Sets this category's parent id

param: int $parentid The ID of the category that is the new parent to $this
param: string $source From where was the object updated (mod/forum, manual, etc.)
return: bool success

get_final($userid=null)   X-Ref
Returns the final grade values for this grade category.

param: int $userid Optional user ID to retrieve a single user's final grade
return: mixed An array of all final_grades (stdClass objects) for this grade_item, or a single final_grade.

get_sortorder()   X-Ref
Returns the sortorder of the grade categories' associated grade_item

This method is also available in grade_item for cases where the object type is not known.

return: int Sort order

get_idnumber()   X-Ref
Returns the idnumber of the grade categories' associated grade_item.

This method is also available in grade_item for cases where the object type is not known.

return: string idnumber

set_sortorder($sortorder)   X-Ref
Sets the sortorder variable for this category.

This method is also available in grade_item, for cases where the object type is not know.

param: int $sortorder The sortorder to assign to this category

move_after_sortorder($sortorder)   X-Ref
Move this category after the given sortorder

Does not change the parent

param: int $sortorder to place after.
return: void

is_course_category()   X-Ref
Return true if this is the top most category that represents the total course grade.

return: bool

fetch_course_category($courseid)   X-Ref
Return the course level grade_category object

param: int $courseid The Course ID
return: grade_category Returns the course level grade_category instance

is_editable()   X-Ref
Is grading object editable?

return: bool

is_locked()   X-Ref
Returns the locked state/date of the grade categories' associated grade_item.

This method is also available in grade_item, for cases where the object type is not known.

return: bool

set_locked($lockedstate, $cascade=false, $refresh=true)   X-Ref
Sets the grade_item's locked variable and updates the grade_item.

Calls set_locked() on the categories' grade_item

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 success if category locked (not all children mayb be locked though)

set_properties(&$instance, $params)   X-Ref
Overrides grade_object::set_properties() to add special handling for changes to category aggregation types

param: stdClass $instance the object to set the properties on
param: array|stdClass $params Either an associative array or an object containing property name, property value pairs

set_hidden($hidden, $cascade=false)   X-Ref
Sets the grade_item's hidden variable and updates the grade_item.

Overrides grade_item::set_hidden() to add cascading of the hidden value to grade items in this grade category

param: int $hidden 0 mean always visible, 1 means always hidden and a number > 1 is a timestamp to hide until
param: bool $cascade apply to child objects too

apply_default_settings()   X-Ref
Applies default settings on this category

return: bool True if anything changed

apply_forced_settings()   X-Ref
Applies forced settings on this category

return: bool True if anything changed

updated_forced_settings()   X-Ref
Notification of change in forced category settings.

Causes all course and category grade items to be marked as needing to be updated

get_default_aggregation_coefficient_values($aggregationmethod)   X-Ref
Determine the default aggregation values for a given aggregation method.

param: int $aggregationmethod The aggregation method constant value.
return: array Containing the keys 'aggregationcoef', 'aggregationcoef2' and 'weightoverride'.

notify_changed($deleted)   X-Ref
Cleans the cache.

We invalidate them all so it can be completely reloaded.

Being conservative here, if there is a new grade_category we purge them, the important part
is that this is not purged when there are no changes in grade_categories.

param: bool $deleted
return: void

generate_record_set_key($params)   X-Ref
Generates a unique key per query.

Not unique between grade_object children. self::retrieve_record_set and self::set_record_set will be in charge of
selecting the appropriate cache.

param: array $params An array of conditions like $fieldname => $fieldvalue
return: string

retrieve_record_set($params)   X-Ref
Tries to retrieve a record set from the cache.

param: array $params The query params
return: grade_object[]|bool An array of grade_objects or false if not found.

set_record_set($params, $records)   X-Ref
Sets a result to the records cache, even if there were no results.

param: string $params The query params
param: grade_object[]|bool $records An array of grade_objects or false if there are no records matching the $key filters
return: void

clean_record_set()   X-Ref
Cleans the cache.

Aggressive deletion to be conservative given the gradebook design.
The key is based on the requested params, not easy nor worth to purge selectively.

return: void