Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
completion_info Class Reference

Class represents completion information for a course. More...

Public Member Functions

 __construct ($course)
 Constructs with course details.
 
 clear_criteria ()
 Clear old course completion criteria.
 
 count_course_user_data ($user_id=null)
 Determines how much course completion data exists for a course.
 
 count_user_data ($cm)
 Determines how much completion data exists for an activity.
 
 delete_all_completion_data ()
 Deletes all activity and course completion data for an entire course (the below delete_all_state function does this for a single activity).
 
 delete_all_state ($cm)
 Deletes completion state related to an activity for all users.
 
 delete_course_completion_data ()
 Deletes all course completion completion data.
 
 display_help_icon ()
 Returns the 'Your progress' help icon, if completion tracking is enabled.
 
 get_activities ()
 Obtains a list of activities for which completion is enabled on the course.
 
 get_aggregation_method ($criteriatype=null)
 Get aggregation method.
 
 get_completion ($user_id, $criteriatype)
 Get a course completion for a user.
 
 get_completion_data (int $coursemoduleid, int $userid, array $defaultdata)
 Get completion data include viewed field.
 
 get_completions ($user_id, $criteriatype=null)
 Get all course criteria's completion objects for a user.
 
 get_core_completion_state (cm_info $cm, int $userid)
 Get the latest completion state for each criteria used in the module.
 
 get_criteria ($criteriatype=null)
 Get course completion criteria.
 
 get_data ($cm, $wholecourse=false, $userid=0, $unused=null)
 Obtains completion data for a particular activity and user (from the completion cache if available, or by SQL query)
 
 get_grade_completion (cm_info $cm, int $userid)
 Fetches the completion state for an activity completion's require grade completion requirement.
 
 get_incomplete_criteria ()
 
 get_num_tracked_users ($where='', $whereparams=array(), $groupid=0)
 Returns the number of users whose progress is tracked in this course.
 
 get_progress_all ($where='', $where_params=array(), $groupid=0, $sort='', $pagesize='', $start='', context $extracontext=null)
 Obtains progress information across a course for all users on that course, or for all users in a specific group.
 
 get_tracked_users ($where='', $whereparams=array(), $groupid=0, $sort='', $limitfrom='', $limitnum='', context $extracontext=null)
 Return array of users whose progress is tracked in this course.
 
 get_user_completion ($user_id, $criteria)
 Get completion object for a user and a criteria.
 
 has_activities ()
 Return whether or not the course has activities with completion enabled.
 
 has_criteria ()
 Check if course has completion criteria set.
 
 inform_grade_changed ($cm, $item, $grade, $deleted, $isbulkupdate=false)
 Called by grade code to inform the completion system when a grade has been changed.
 
 internal_get_state ($cm, $userid, $current)
 Calculates the completion state for an activity and user.
 
 internal_set_data ($cm, $data, $isbulkupdate=false)
 Updates completion data for a particular coursemodule and user (user is determined from $data).
 
type internal_systemerror ($error)
 This is to be used only for system errors (things that shouldn't happen) and not user-level errors.
 
 is_course_complete ($user_id)
 Has the supplied user completed this course.
 
 is_course_locked ()
 Check if this course's completion criteria should be locked.
 
 is_enabled ($cm=null)
 Checks whether completion is enabled in a particular course and possibly activity.
 
 is_tracked_user ($userid)
 Checks to see if the userid supplied has a tracked role in this course.
 
 print_help_icon ()
 Displays the 'Your progress' help icon, if completion tracking is enabled.
 
 reset_all_state ($cm)
 Recalculates completion state related to an activity for all users.
 
 set_module_viewed ($cm, $userid=0)
 Marks a module as viewed.
 
 update_state ($cm, $possibleresult=COMPLETION_UNKNOWN, $userid=0, $override=false, $isbulkupdate=false)
 Updates (if necessary) the completion state of activity $cm for the given user.
 
 user_can_override_completion ($user)
 Check whether the supplied user can override the activity completion statuses within the current course.
 

Static Public Member Functions

static aggregate_completion_states ($type, $old, $new)
 Aggregate activity completion state.
 
static get_aggregation_methods ()
 Return array of aggregation methods.
 
static internal_get_grade_state ($item, $grade, bool $returnpassfail=false)
 Calculates the completion state that would result from a graded item (where grade-based completion is turned on) based on the actual grade and settings.
 
static is_enabled_for_site ()
 Determines whether completion is enabled across entire site.
 

Public Attributes

int $course_id
 

Protected Member Functions

 get_other_cm_completion_data (cm_info $cm, int $userid)
 Adds the user's custom completion data on the given course module.
 

Detailed Description

Class represents completion information for a course.

Does not contain any data, so you can safely construct it multiple times without causing any problems.

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

Constructor & Destructor Documentation

◆ __construct()

completion_info::__construct ( $course)

Constructs with course details.

When instantiating a new completion info object you must provide a course object with at least id, and enablecompletion properties. Property cacherev is needed if you check completion of the current user since it is used for cache validation.

Parameters
stdClass$courseMoodle course object.

Member Function Documentation

◆ aggregate_completion_states()

static completion_info::aggregate_completion_states ( $type,
$old,
$new )
static

Aggregate activity completion state.

Parameters
int$typeAggregation type (COMPLETION_* constant)
bool$oldOld state
bool$newNew state
Return values
bool

◆ count_course_user_data()

completion_info::count_course_user_data ( $user_id = null)

Determines how much course completion data exists for a course.

This is used when deciding whether completion information should be 'locked' in the completion settings form and activity completion settings.

Parameters
int$user_idOptionally only get course completion data for a single user
Return values
intThe number of users who have completion data stored for this course, 0 if none

◆ count_user_data()

completion_info::count_user_data ( $cm)

Determines how much completion data exists for an activity.

This is used when deciding whether completion information should be 'locked' in the module editing form.

Parameters
cm_info$cmActivity
Return values
intThe number of users who have completion data stored for this activity, 0 if none

◆ delete_all_completion_data()

completion_info::delete_all_completion_data ( )

Deletes all activity and course completion data for an entire course (the below delete_all_state function does this for a single activity).

Used by course reset page.

◆ delete_all_state()

completion_info::delete_all_state ( $cm)

Deletes completion state related to an activity for all users.

Intended for use only when the activity itself is deleted.

Parameters
stdClass | cm_info$cmActivity

◆ delete_course_completion_data()

completion_info::delete_course_completion_data ( )

Deletes all course completion completion data.

Intended to be used when unlocking completion criteria settings.

◆ display_help_icon()

completion_info::display_help_icon ( )

Returns the 'Your progress' help icon, if completion tracking is enabled.

Return values
stringHTML code for help icon, or blank if not needed
Deprecated
since Moodle 4.0 - The 'Your progress' info isn't displayed any more.

◆ get_activities()

completion_info::get_activities ( )

Obtains a list of activities for which completion is enabled on the course.

The list is ordered by the section order of those activities.

Return values
cm_info[]Array from $cmid => $cm of all activities with completion enabled, empty array if none

◆ get_aggregation_method()

completion_info::get_aggregation_method ( $criteriatype = null)

Get aggregation method.

Parameters
int$criteriatypeIf none supplied, get overall aggregation method (optional)
Return values
intOne of COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY

◆ get_aggregation_methods()

static completion_info::get_aggregation_methods ( )
static

Return array of aggregation methods.

Return values
array

◆ get_completion()

completion_info::get_completion ( $user_id,
$criteriatype )

Get a course completion for a user.

Parameters
int$user_idUser id
int$criteriatypeSpecific criteria type to return
Return values
bool|completion_criteria_completionreturns false on fail

◆ get_completion_data()

completion_info::get_completion_data ( int $coursemoduleid,
int $userid,
array $defaultdata )

Get completion data include viewed field.

Parameters
int$coursemoduleidThe course module id.
int$useridThe User ID.
array$defaultdataDefault data completion.
Return values
arrayData completion retrieved.

◆ get_completions()

completion_info::get_completions ( $user_id,
$criteriatype = null )

Get all course criteria's completion objects for a user.

Parameters
int$user_idUser id
int$criteriatypeSpecific criteria type to return (optional)
Return values
array

◆ get_core_completion_state()

completion_info::get_core_completion_state ( cm_info $cm,
int $userid )

Get the latest completion state for each criteria used in the module.

Parameters
cm_info$cmThe corresponding module's information
int$useridThe id for the user we are calculating core completion state
Return values
array\$dataThe individualised core completion state used in the module. Consists of the following keys completiongrade, passgrade, viewed

◆ get_criteria()

completion_info::get_criteria ( $criteriatype = null)

Get course completion criteria.

Parameters
int$criteriatypeSpecific criteria type to return (optional)

◆ get_data()

completion_info::get_data ( $cm,
$wholecourse = false,
$userid = 0,
$unused = null )

Obtains completion data for a particular activity and user (from the completion cache if available, or by SQL query)

Parameters
stdClass | cm_info$cmActivity; only required field is ->id
bool$wholecourseIf true (default false) then, when necessary to fill the cache, retrieves information from the entire course not just for this one activity
int$useridUser ID or 0 (default) for current user
null$unusedThis parameter has been deprecated since 4.0 and should not be used anymore.
Return values
objectCompletion data. Record from course_modules_completion plus other completion statuses such as
  • Completion status for 'must-receive-grade' completion rule.
  • Custom completion statuses defined by the activity module plugin.

◆ get_grade_completion()

completion_info::get_grade_completion ( cm_info $cm,
int $userid )

Fetches the completion state for an activity completion's require grade completion requirement.

Parameters
cm_info$cmThe course module information.
int$useridThe user ID.
Return values
intThe completion state.

◆ get_incomplete_criteria()

completion_info::get_incomplete_criteria ( )

◆ get_num_tracked_users()

completion_info::get_num_tracked_users ( $where = '',
$whereparams = array(),
$groupid = 0 )

Returns the number of users whose progress is tracked in this course.

Optionally supply a search's where clause, or a group id.

Parameters
string$whereWhere clause sql (use 'u.whatever' for user table fields)
array$whereparamsWhere clause params
int$groupidGroup id
Return values
intNumber of tracked users

◆ get_other_cm_completion_data()

completion_info::get_other_cm_completion_data ( cm_info $cm,
int $userid )
protected

Adds the user's custom completion data on the given course module.

Parameters
cm_info$cmThe course module information.
int$useridThe user ID.
Return values
arrayThe additional completion data.

◆ get_progress_all()

completion_info::get_progress_all ( $where = '',
$where_params = array(),
$groupid = 0,
$sort = '',
$pagesize = '',
$start = '',
context $extracontext = null )

Obtains progress information across a course for all users on that course, or for all users in a specific group.

Intended for use when displaying progress.

This includes only users who, in course context, have one of the roles for which progress is tracked (the gradebookroles admin option) and are enrolled in course.

Users are included (in the first array) even if they do not have completion progress for any course-module.

Parameters
bool$sortfirstnameIf true, sort by first name, otherwise sort by last name
string$whereWhere clause sql (optional)
array$where_paramsWhere clause params (optional)
int$groupidGroup ID or 0 (default)/false for all groups
int$pagesizeNumber of users to actually return (optional)
int$startUser to start at if paging (optional)
context$extracontextIf set, includes extra user information fields as appropriate to display for current user in this context
Return values
stdClasswith ->total and ->start (same as $start) and ->users; an array of user objects (like mdl_user id, firstname, lastname) containing an additional ->progress array of coursemoduleid => completionstate

◆ get_tracked_users()

completion_info::get_tracked_users ( $where = '',
$whereparams = array(),
$groupid = 0,
$sort = '',
$limitfrom = '',
$limitnum = '',
context $extracontext = null )

Return array of users whose progress is tracked in this course.

Optionally supply a search's where clause, group id, sorting, paging.

Parameters
string$whereWhere clause sql, referring to 'u.' fields (optional)
array$whereparamsWhere clause params (optional)
int$groupidGroup ID to restrict to (optional)
string$sortOrder by clause (optional)
int$limitfromResult start (optional)
int$limitnumResult max size (optional)
context$extracontextIf set, includes extra user information fields as appropriate to display for current user in this context
Return values
arrayArray of user objects with user fields (including all identity fields)

◆ get_user_completion()

completion_info::get_user_completion ( $user_id,
$criteria )

Get completion object for a user and a criteria.

Parameters
int$user_idUser id
completion_criteria$criteriaCriteria object
Return values
completion_criteria_completion

◆ has_activities()

completion_info::has_activities ( )

Return whether or not the course has activities with completion enabled.

Return values
booleantrue when there is at least one activity with completion enabled.

◆ has_criteria()

completion_info::has_criteria ( )

Check if course has completion criteria set.

Return values
boolReturns true if there are criteria

◆ inform_grade_changed()

completion_info::inform_grade_changed ( $cm,
$item,
$grade,
$deleted,
$isbulkupdate = false )

Called by grade code to inform the completion system when a grade has been changed.

If the changed grade is used to determine completion for the course-module, then the completion status will be updated.

Parameters
stdClass | cm_info$cmCourse-module for item that owns grade
grade_item$itemGrade item
stdClass$grade
bool$deleted
bool$isbulkupdateIf bulk grade update is happening.

◆ internal_get_grade_state()

static completion_info::internal_get_grade_state ( $item,
$grade,
bool $returnpassfail = false )
static

Calculates the completion state that would result from a graded item (where grade-based completion is turned on) based on the actual grade and settings.

Internal function. Not private, so we can unit-test it.

Parameters
grade_item$iteman instance of grade_item
grade_grade$gradean instance of grade_grade
bool$returnpassfailIf course module has pass grade completion criteria
Return values
intCompletion state e.g. COMPLETION_INCOMPLETE

◆ internal_get_state()

completion_info::internal_get_state ( $cm,
$userid,
$current )

Calculates the completion state for an activity and user.

Internal function. Not private, so we can unit-test it.

Parameters
stdClass | cm_info$cmActivity
int$useridID of user
stdClass$currentPrevious completion information from database
Return values
mixed

◆ internal_set_data()

completion_info::internal_set_data ( $cm,
$data,
$isbulkupdate = false )

Updates completion data for a particular coursemodule and user (user is determined from $data).

(Internal function. Not private, so we can unit-test it.)

Parameters
stdClass | cm_info$cmActivity
stdClass$dataData about completion for that user
bool$isbulkupdateIf bulk grade update is happening.

◆ internal_systemerror()

type completion_info::internal_systemerror ( $error)

This is to be used only for system errors (things that shouldn't happen) and not user-level errors.

$CFG

Parameters
string$errorError string (will not be displayed to user unless debugging is enabled)
Exceptions
moodle_exceptionException with the error string as debug info

◆ is_course_complete()

completion_info::is_course_complete ( $user_id)

Has the supplied user completed this course.

Parameters
int$user_idUser's id
Return values
boolean

◆ is_course_locked()

completion_info::is_course_locked ( )

Check if this course's completion criteria should be locked.

Return values
boolean

◆ is_enabled()

completion_info::is_enabled ( $cm = null)

Checks whether completion is enabled in a particular course and possibly activity.

Parameters
stdClass | cm_info$cmCourse-module object. If not specified, returns the course completion enable state.
Return values
mixedCOMPLETION_ENABLED or COMPLETION_DISABLED (==0) in the case of site and course; COMPLETION_TRACKING_MANUAL, _AUTOMATIC or _NONE (==0) for a course-module.

◆ is_enabled_for_site()

static completion_info::is_enabled_for_site ( )
static

Determines whether completion is enabled across entire site.

Return values
boolCOMPLETION_ENABLED (true) if completion is enabled for the site, COMPLETION_DISABLED (false) if it's complete

◆ is_tracked_user()

completion_info::is_tracked_user ( $userid)

Checks to see if the userid supplied has a tracked role in this course.

Parameters
int$useridUser id
Return values
bool

◆ print_help_icon()

completion_info::print_help_icon ( )

Displays the 'Your progress' help icon, if completion tracking is enabled.

Just prints the result of display_help_icon().

Deprecated
since Moodle 2.0 - Use display_help_icon instead.

◆ reset_all_state()

completion_info::reset_all_state ( $cm)

Recalculates completion state related to an activity for all users.

Intended for use if completion conditions change. (This should be avoided as it may cause some things to become incomplete when they were previously complete, with the effect - for example - of hiding a later activity that was previously available.)

Resetting state of manual tickbox has same result as deleting state for it.

Parameters
stcClass | cm_info$cmActivity

◆ set_module_viewed()

completion_info::set_module_viewed ( $cm,
$userid = 0 )

Marks a module as viewed.

Should be called whenever a module is 'viewed' (it is up to the module how to determine that). Has no effect if viewing is not set as a completion condition.

Note that this function must be called before you print the page header because it is possible that the navigation block may depend on it. If you call it after printing the header, it shows a developer debug warning.

Parameters
stdClass | cm_info$cmActivity
int$useridUser ID or 0 (default) for current user
Return values
void

◆ update_state()

completion_info::update_state ( $cm,
$possibleresult = COMPLETION_UNKNOWN,
$userid = 0,
$override = false,
$isbulkupdate = false )

Updates (if necessary) the completion state of activity $cm for the given user.

For manual completion, this function is called when completion is toggled with $possibleresult set to the target state.

For automatic completion, this function should be called every time a module does something which might influence a user's completion state. For example, if a forum provides options for marking itself 'completed' once a user makes N posts, this function should be called every time a user makes a new post. [After the post has been saved to the database]. When calling, you do not need to pass in the new completion state. Instead this function carries out completion calculation by checking grades and viewed state itself, and calling the involved module via mod_{modulename}::completion::::custom_completion\get_overall_completion_state() to check module-specific conditions.

Parameters
stdClass | cm_info$cmCourse-module
int$possibleresultExpected completion result. If the event that has just occurred (e.g. add post) can only result in making the activity complete when it wasn't before, use COMPLETION_COMPLETE. If the event that has just occurred (e.g. delete post) can only result in making the activity not complete when it was previously complete, use COMPLETION_INCOMPLETE. Otherwise use COMPLETION_UNKNOWN. Setting this value to something other than COMPLETION_UNKNOWN significantly improves performance because it will abandon processing early if the user's completion state already matches the expected result. For manual events, COMPLETION_COMPLETE or COMPLETION_INCOMPLETE must be used; these directly set the specified state.
int$useridUser ID to be updated. Default 0 = current user
bool$overrideWhether manually overriding the existing completion state.
bool$isbulkupdateIf bulk grade update is happening.
Return values
void
Exceptions
moodle_exceptionif trying to override without permission.

◆ user_can_override_completion()

completion_info::user_can_override_completion ( $user)

Check whether the supplied user can override the activity completion statuses within the current course.

Parameters
stdClass$userThe user object.
Return values
boolTrue if the user can override, false otherwise.

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