Search moodle.org's
Developer Documentation
Developer Documentation
- 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.
/lib/ -> completionlib.php (source)
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
completion_info:: (44 methods):
get_aggregation_methods()
__construct()
is_enabled_for_site()
is_enabled()
print_help_icon()
display_help_icon()
get_completion()
get_completions()
get_user_completion()
has_criteria()
get_criteria()
get_aggregation_method()
get_incomplete_criteria()
clear_criteria()
is_course_complete()
user_can_override_completion()
update_state()
internal_get_state()
get_grade_completion()
set_module_viewed()
count_user_data()
count_course_user_data()
is_course_locked()
delete_course_completion_data()
delete_all_completion_data()
delete_all_state()
reset_all_state()
get_data()
get_core_completion_state()
get_other_cm_completion_data()
internal_set_data()
has_activities()
get_activities()
is_tracked_user()
get_num_tracked_users()
get_tracked_users()
get_progress_all()
inform_grade_changed()
internal_get_grade_state()
aggregate_completion_states()
internal_systemerror()
get_completion_data()
completion_cron_aggregate()
aggregate_completions()
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 |
