Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 402 and 403]

Contains classes, functions and constants used during the tracking of activity completion for users. Completion top-level options (admin setting enablecompletion)

Copyright: 1999 onwards Martin Dougiamas {@link http://moodle.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1853 lines (73 kb)
Included or required: 1 time
Referenced: 1 time
Includes or requires: 0 files

Defines 1 class

Defines 44 functions


Class: completion_info  - X-Ref

Class represents completion information for a course.

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

get_aggregation_methods()   X-Ref
Return array of aggregation methods

return: array

__construct($course)   X-Ref
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.

param: stdClass $course Moodle course object.

is_enabled_for_site()   X-Ref
Determines whether completion is enabled across entire site.

return: bool COMPLETION_ENABLED (true) if completion is enabled for the site,

is_enabled($cm = null)   X-Ref
Checks whether completion is enabled in a particular course and possibly
activity.

param: stdClass|cm_info $cm Course-module object. If not specified, returns the course
return: mixed COMPLETION_ENABLED or COMPLETION_DISABLED (==0) in the case of

print_help_icon()   X-Ref
Displays the 'Your progress' help icon, if completion tracking is enabled.
Just prints the result of display_help_icon().


display_help_icon()   X-Ref
Returns the 'Your progress' help icon, if completion tracking is enabled.

return: string HTML code for help icon, or blank if not needed

get_completion($user_id, $criteriatype)   X-Ref
Get a course completion for a user

param: int $user_id User id
param: int $criteriatype Specific criteria type to return
return: bool|completion_criteria_completion returns false on fail

get_completions($user_id, $criteriatype = null)   X-Ref
Get all course criteria's completion objects for a user

param: int $user_id User id
param: int $criteriatype Specific criteria type to return (optional)
return: array

get_user_completion($user_id, $criteria)   X-Ref
Get completion object for a user and a criteria

param: int $user_id User id
param: completion_criteria $criteria Criteria object
return: completion_criteria_completion

has_criteria()   X-Ref
Check if course has completion criteria set

return: bool Returns true if there are criteria

get_criteria($criteriatype = null)   X-Ref
Get course completion criteria

param: int $criteriatype Specific criteria type to return (optional)

get_aggregation_method($criteriatype = null)   X-Ref
Get aggregation method

param: int $criteriatype If none supplied, get overall aggregation method (optional)
return: int One of COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY

get_incomplete_criteria()   X-Ref


clear_criteria()   X-Ref
Clear old course completion criteria


is_course_complete($user_id)   X-Ref
Has the supplied user completed this course

param: int $user_id User's id
return: boolean

user_can_override_completion($user)   X-Ref
Check whether the supplied user can override the activity completion statuses within the current course.

param: stdClass $user The user object.
return: bool True if the user can override, false otherwise.

update_state($cm, $possibleresult=COMPLETION_UNKNOWN, $userid=0,$override = false, $isbulkupdate = false)   X-Ref
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.

param: stdClass|cm_info $cm Course-module
param: int $possibleresult Expected completion result. If the event that
param: int $userid User ID to be updated. Default 0 = current user
param: bool $override Whether manually overriding the existing completion state.
param: bool $isbulkupdate If bulk grade update is happening.
return: void

internal_get_state($cm, $userid, $current)   X-Ref
Calculates the completion state for an activity and user.

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

param: stdClass|cm_info $cm Activity
param: int $userid ID of user
param: stdClass $current Previous completion information from database
return: mixed

get_grade_completion(cm_info $cm, int $userid)   X-Ref
Fetches the completion state for an activity completion's require grade completion requirement.

param: cm_info $cm The course module information.
param: int $userid The user ID.
return: int The completion state.

set_module_viewed($cm, $userid=0)   X-Ref
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.

param: stdClass|cm_info $cm Activity
param: int $userid User ID or 0 (default) for current user
return: void

count_user_data($cm)   X-Ref
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.

param: cm_info $cm Activity
return: int The number of users who have completion data stored for this

count_course_user_data($user_id = null)   X-Ref
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.

param: int $user_id Optionally only get course completion data for a single user
return: int The number of users who have completion data stored for this

is_course_locked()   X-Ref
Check if this course's completion criteria should be locked

return: boolean

delete_course_completion_data()   X-Ref
Deletes all course completion completion data.

Intended to be used when unlocking completion criteria settings.

delete_all_completion_data()   X-Ref
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($cm)   X-Ref
Deletes completion state related to an activity for all users.

Intended for use only when the activity itself is deleted.

param: stdClass|cm_info $cm Activity

reset_all_state($cm)   X-Ref
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.

param: stcClass|cm_info $cm Activity

get_data($cm, $wholecourse = false, $userid = 0, $unused = null)   X-Ref
Obtains completion data for a particular activity and user (from the
completion cache if available, or by SQL query)

param: stdClass|cm_info $cm Activity; only required field is ->id
param: bool $wholecourse If true (default false) then, when necessary to
param: int $userid User ID or 0 (default) for current user
param: null $unused This parameter has been deprecated since 4.0 and should not be used anymore.
return: object Completion data. Record from course_modules_completion plus other completion statuses such as

get_core_completion_state(cm_info $cm, int $userid)   X-Ref
Get the latest completion state for each criteria used in the module

param: cm_info $cm The corresponding module's information
param: int $userid The id for the user we are calculating core completion state
return: array $data The individualised core completion state used in the module.

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

param: cm_info $cm The course module information.
param: int $userid The user ID.
return: array The additional completion data.

internal_set_data($cm, $data, $isbulkupdate = false)   X-Ref
Updates completion data for a particular coursemodule and user (user is
determined from $data).

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

param: stdClass|cm_info $cm Activity
param: stdClass $data Data about completion for that user
param: bool $isbulkupdate If bulk grade update is happening.

has_activities()   X-Ref
Return whether or not the course has activities with completion enabled.

return: boolean true when there is at least one activity with completion enabled.

get_activities()   X-Ref
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: cm_info[] Array from $cmid => $cm of all activities with completion enabled,

is_tracked_user($userid)   X-Ref
Checks to see if the userid supplied has a tracked role in
this course

param: int $userid User id
return: bool

get_num_tracked_users($where = '', $whereparams = array()   X-Ref
Returns the number of users whose progress is tracked in this course.

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

param: string $where Where clause sql (use 'u.whatever' for user table fields)
param: array $whereparams Where clause params
param: int $groupid Group id
return: int Number of tracked users

get_tracked_users($where = '', $whereparams = array()   X-Ref
Return array of users whose progress is tracked in this course.

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

param: string $where Where clause sql, referring to 'u.' fields (optional)
param: array $whereparams Where clause params (optional)
param: int $groupid Group ID to restrict to (optional)
param: string $sort Order by clause (optional)
param: int $limitfrom Result start (optional)
param: int $limitnum Result max size (optional)
param: context $extracontext If set, includes extra user information fields
return: array Array of user objects with user fields (including all identity fields)

get_progress_all($where = '', $where_params = array()   X-Ref
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.

param: bool $sortfirstname If true, sort by first name, otherwise sort by
param: string $where Where clause sql (optional)
param: array $where_params Where clause params (optional)
param: int $groupid Group ID or 0 (default)/false for all groups
param: int $pagesize Number of users to actually return (optional)
param: int $start User to start at if paging (optional)
param: context $extracontext If set, includes extra user information fields
return: stdClass with ->total and ->start (same as $start) and ->users;

inform_grade_changed($cm, $item, $grade, $deleted, $isbulkupdate = false)   X-Ref
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.

param: stdClass|cm_info $cm Course-module for item that owns grade
param: grade_item $item Grade item
param: stdClass $grade
param: bool $deleted
param: bool $isbulkupdate If bulk grade update is happening.

internal_get_grade_state($item, $grade, bool $returnpassfail = false)   X-Ref
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.

param: grade_item $item an instance of grade_item
param: grade_grade $grade an instance of grade_grade
param: bool $returnpassfail If course module has pass grade completion criteria
return: int Completion state e.g. COMPLETION_INCOMPLETE

aggregate_completion_states($type, $old, $new)   X-Ref
Aggregate activity completion state

param: int     $type   Aggregation type (COMPLETION_* constant)
param: bool    $old    Old state
param: bool    $new    New state
return: bool

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

param: string $error Error string (will not be displayed to user unless debugging is enabled)

get_completion_data(int $coursemoduleid, int $userid, array $defaultdata)   X-Ref
Get completion data include viewed field.

param: int $coursemoduleid The course module id.
param: int $userid The User ID.
param: array $defaultdata Default data completion.
return: array Data completion retrieved.

completion_cron_aggregate($method, $data, &$state)   X-Ref
Aggregate criteria status's as per configured aggregation method.

param: int $method COMPLETION_AGGREGATION_* constant.
param: bool $data Criteria completion status.
param: bool|null $state Aggregation state.

aggregate_completions(int $coursecompletionid, bool $mtraceprogress = false)   X-Ref
Aggregate courses completions. This function is called when activity completion status is updated
for single user. Also when regular completion task runs it aggregates completions for all courses and users.

param: int $coursecompletionid Course completion ID to update (if 0 - update for all courses and users)
param: bool $mtraceprogress To output debug info

Functions that are not part of a class:

completion_can_view_data($userid, $course = null)   X-Ref
Utility function for checking if the logged in user can view
another's completion data for a particular course

param: int         $userid     Completion data's owner
param: mixed       $course     Course object or Course ID (optional)
return: boolean