Course completion

There are several states of completion of the course

1. Completion is turned off
2. Completion is turned on
3. Without any criteria
4. With one or more criteria
5. Course is completed

In the following, we explain each state in more detail.

Settings→Course administration→Edit settings Completion tracking → 'Disabled, not shown in activity settings'

Database(DB): table 'mdl_course' field 'enablecompletion' is 0

Settings→Course administration→Edit settings Completion tracking → 'Enabled, control via…..'

DB: table 'mdl_course' field 'enablecompletion' is 1

DB: table 'mdl_course_completion_criteria' does not contain any records with 'course' = [concrete course id]

DB: table 'mdl_course_completion_criteria' contains record(s) with 'course' = [concrete course id]

Please note: mdl_course_completion_criteria.moduleinstance refers to a mdl_course_modules.id column, not to mdl_course_modules.instance.

DB: table 'mdl_course_completions' field 'timecompleted' != NULL

via php code:

$params = array(
    'userid' => $user_id,
    'course' => $course_id
);
$ccompletion = new completion_completion($params);
$ccompletion->is_complete();

The course completion information is retrieved through an object of class completion_info, which you instantiate for a specific course:

// $course should be a course object with at least an id
$completion = new completion_info($course);

ATTENTION: The course completion information is only up-to-date after the /admin/cron.php has been executed.

The course completion criteria are grouped by type. There are eight types, defined as constants:

1. COMPLETION_CRITERIA_TYPE_SELF
2. COMPLETION_CRITERIA_TYPE_DATE
3. COMPLETION_CRITERIA_TYPE_UNENROL
4. COMPLETION_CRITERIA_TYPE_ACTIVITY
5. COMPLETION_CRITERIA_TYPE_DURATION
6. COMPLETION_CRITERIA_TYPE_GRADE
7. COMPLETION_CRITERIA_TYPE_ROLE
8. COMPLETION_CRITERIA_TYPE_COURSE

(See /completion/criteria/completion_criteria.php)

The aggregation methods are telling you if all criteria should be met, or just some:

• If the course completion criteria should ALL be met, the aggregation method is COMPLETION_AGGREGATION_ALL.
• If ANY course completion criterion is sufficient, the aggregation method is COMPLETION_AGGREGATION_ANY

You can retrieve the aggregation method for a specific criterion type by querying the completion_info object (see above). For example, the following code retrieves the aggregation method set for the 'Another course must be completed to complete this course' criterion:

$aggregation_method = $completion->get_aggregation_method(COMPLETION_CRITERIA_TYPE_COURSE);

• If the aggregation method in this example is COMPLETION_AGGREGATION_ALL, then all specified courses, say A and B, must be completed before you can complete this course, say C.
• If the aggregation method is COMPLETION_AGGREGATION_ANY, then either A or B must be completed before you can complete C.

To find out if a specific course completion criterion has been met, you first have to retrieve all criteria of that type:

$completions = $completion->get_completions($user_id, COMPLETION_CRITERIA_TYPE_COURSE);

Calling $completion→get_completions returns an array of completion_criteria_completion objects. On each of these objects, you can call the is_complete method, which as you'd expect returns either true or false.

However, you also need to take the aggregation into account. Suppose you want to know if the criterion 'Other courses must be completed' has been met, then you need to know whether ALL other courses should be completed, or whether ANY other course would do. For that you need to get the aggregation method for this criterion type.

$aggregation_method = $completion->get_aggregation_method(COMPLETION_CRITERIA_TYPE_COURSE);

Using the $completions we retrieved earlier, we're now ready to loop over the 'other' course completions. Here's an example where we're using a separate function to do that:

/**
 * @param array $completions          array of objects of class completion_criteria_completion  
 * @param int   $aggregation_method   type of aggregation method (usually either COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY)
 */
static function are_complete($completions, $aggregation_method) {
    foreach($completions as $completion) {
        if ( ($aggregation_method == COMPLETION_AGGREGATION_ALL) && (!$completion->is_complete()) ) return false;
        if ( ($aggregation_method == COMPLETION_AGGREGATION_ANY) && ($completion->is_complete()) ) return true;
    }
    return ($aggregation_method == COMPLETION_AGGREGATION_ALL) ? true : false;
} // function are_complete

In our example, we have used the criterion type 'other course completions' (COMPLETION_CRITERIA_TYPE_COURSE), but the function would work just as well for any other criterion type.