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.

Copyright: 2008 Sam Marshall

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 $course Moodle course object.

Member Function Documentation

◆ aggregate_completion_states()

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

static

Aggregate activity completion state.

Parameters

int	$type	Aggregation type (COMPLETION_* constant)
bool	$old	Old state
bool	$new	New 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_id Optionally only get course completion data for a single user

Return values

int	The 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 $cm Activity

Return values

int	The 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 $cm Activity

◆ 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

string HTML 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 $criteriatype If none supplied, get overall aggregation method (optional)

Return values

int	One 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_id	User id
int	$criteriatype	Specific criteria type to return

Return values

bool|completion_criteria_completion returns 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	$coursemoduleid	The course module id.
int	$userid	The User ID.
array	$defaultdata	Default data completion.

Return values

array Data 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_id	User id
int	$criteriatype	Specific 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	$cm	The corresponding module's information
int	$userid	The id for the user we are calculating core completion state

Return values

array\$data The 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 $criteriatype Specific 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	$cm	Activity; only required field is ->id
bool	$wholecourse	If true (default false) then, when necessary to fill the cache, retrieves information from the entire course not just for this one activity
int	$userid	User ID or 0 (default) for current user
null	$unused	This parameter has been deprecated since 4.0 and should not be used anymore.

Return values

object

Completion 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	$cm	The course module information.
int	$userid	The user ID.

Return values

int	The completion state.

◆ get_incomplete_criteria()

completion_info::get_incomplete_criteria ( )

Deprecated: since Moodle 2.8 MDL-46290.

◆ 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	$where	Where clause sql (use 'u.whatever' for user table fields)
array	$whereparams	Where clause params
int	$groupid	Group id

Return values

int	Number 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	$cm	The course module information.
int	$userid	The user ID.

Return values

array The 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	$sortfirstname	If true, sort by first name, otherwise sort by last name
string	$where	Where clause sql (optional)
array	$where_params	Where clause params (optional)
int	$groupid	Group ID or 0 (default)/false for all groups
int	$pagesize	Number of users to actually return (optional)
int	$start	User to start at if paging (optional)
context	$extracontext	If set, includes extra user information fields as appropriate to display for current user in this context

Return values

stdClass with ->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	$where	Where clause sql, referring to 'u.' fields (optional)
array	$whereparams	Where clause params (optional)
int	$groupid	Group ID to restrict to (optional)
string	$sort	Order by clause (optional)
int	$limitfrom	Result start (optional)
int	$limitnum	Result max size (optional)
context	$extracontext	If set, includes extra user information fields as appropriate to display for current user in this context

Return values

array Array 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_id	User id
completion_criteria	$criteria	Criteria 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

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

bool	Returns 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	$cm	Course-module for item that owns grade
grade_item	$item	Grade item
stdClass	$grade
bool	$deleted
bool	$isbulkupdate	If 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	$item	an instance of grade_item
grade_grade	$grade	an instance of grade_grade
bool	$returnpassfail	If course module has pass grade completion criteria

Return values

int	Completion 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	$cm	Activity
int	$userid	ID of user
stdClass	$current	Previous 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	$cm	Activity
stdClass	$data	Data about completion for that user
bool	$isbulkupdate	If 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 $error Error string (will not be displayed to user unless debugging is enabled)

Exceptions

moodle_exception Exception 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_id User'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 $cm Course-module object. If not specified, returns the course completion enable state.

Return values

mixed COMPLETION_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

bool	COMPLETION_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 $userid User 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 $cm Activity

◆ 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	$cm	Activity
int	$userid	User 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	$cm	Course-module
int	$possibleresult	Expected 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	$userid	User ID to be updated. Default 0 = current user
bool	$override	Whether manually overriding the existing completion state.
bool	$isbulkupdate	If bulk grade update is happening.

Return values

void

Exceptions

moodle_exception if 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 $user The user object.

Return values

bool	True if the user can override, false otherwise.

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

lib/completionlib.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ aggregate_completion_states()

◆ count_course_user_data()

◆ count_user_data()

◆ delete_all_completion_data()

◆ delete_all_state()

◆ delete_course_completion_data()

◆ display_help_icon()

◆ get_activities()

◆ get_aggregation_method()

◆ get_aggregation_methods()

◆ get_completion()

◆ get_completion_data()

◆ get_completions()

◆ get_core_completion_state()

◆ get_criteria()

◆ get_data()

◆ get_grade_completion()

◆ get_incomplete_criteria()

◆ get_num_tracked_users()

◆ get_other_cm_completion_data()

◆ get_progress_all()

◆ get_tracked_users()

◆ get_user_completion()

◆ has_activities()

◆ has_criteria()

◆ inform_grade_changed()

◆ internal_get_grade_state()

◆ internal_get_state()

◆ internal_set_data()

◆ internal_systemerror()

◆ is_course_complete()

◆ is_course_locked()

◆ is_enabled()

◆ is_enabled_for_site()

◆ is_tracked_user()

◆ print_help_icon()

◆ reset_all_state()

◆ set_module_viewed()

◆ update_state()

◆ user_can_override_completion()