Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Completion external API
 *
 * @package    core_completion
 * @category   external
 * @copyright  2015 Juan Leyva <juan@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      Moodle 2.9
 */

defined('MOODLE_INTERNAL') || die;

require_once("$CFG->libdir/externallib.php");
require_once("$CFG->libdir/completionlib.php");

/**
 * Completion external functions
 *
 * @package    core_completion
 * @category   external
 * @copyright  2015 Juan Leyva <juan@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      Moodle 2.9
 */
class core_completion_external extends external_api {

    /**
     * Describes the parameters for update_activity_completion_status_manually.
     *
     * @return external_function_parameters
     * @since Moodle 2.9
     */
    public static function update_activity_completion_status_manually_parameters() {
        return new external_function_parameters (
            array(
                'cmid' => new external_value(PARAM_INT, 'course module id'),
                'completed' => new external_value(PARAM_BOOL, 'activity completed or not'),
            )
        );
    }

    /**
     * Update completion status for the current user in an activity, only for activities with manual tracking.
     * @param  int $cmid      Course module id
     * @param  bool $completed Activity completed or not
     * @return array            Result and possible warnings
     * @since Moodle 2.9
     * @throws moodle_exception
     */
    public static function update_activity_completion_status_manually($cmid,  $completed) {

        // Validate and normalize parameters.
        $params = self::validate_parameters(self::update_activity_completion_status_manually_parameters(),
            array('cmid' => $cmid, 'completed' => $completed));
        $cmid = $params['cmid'];
        $completed = $params['completed'];

        $warnings = array();

        $context = context_module::instance($cmid);
        self::validate_context($context);
        require_capability('moodle/course:togglecompletion', $context);

        list($course, $cm) = get_course_and_cm_from_cmid($cmid);

        // Set up completion object and check it is enabled.
        $completion = new completion_info($course);
        if (!$completion->is_enabled()) {
            throw new moodle_exception('completionnotenabled', 'completion');
        }

        // Check completion state is manual.
        if ($cm->completion != COMPLETION_TRACKING_MANUAL) {
            throw new moodle_exception('cannotmanualctrack', 'error');
        }

        $targetstate = ($completed) ? COMPLETION_COMPLETE : COMPLETION_INCOMPLETE;
        $completion->update_state($cm, $targetstate);

        $result = array();
        $result['status'] = true;
        $result['warnings'] = $warnings;
        return $result;
    }

    /**
     * Describes the update_activity_completion_status_manually return value.
     *
     * @return external_single_structure
     * @since Moodle 2.9
     */
    public static function update_activity_completion_status_manually_returns() {

        return new external_single_structure(
            array(
                'status'    => new external_value(PARAM_BOOL, 'status, true if success'),
                'warnings'  => new external_warnings(),
            )
        );
    }

    /**
     * Describes the parameters for override_activity_completion_status.
     *
     * @return external_external_function_parameters
     * @since Moodle 3.4
     */
    public static function override_activity_completion_status_parameters() {
        return new external_function_parameters (
            array(
                'userid' => new external_value(PARAM_INT, 'user id'),
                'cmid' => new external_value(PARAM_INT, 'course module id'),
                'newstate' => new external_value(PARAM_INT, 'the new activity completion state'),
            )
        );
    }

    /**
     * Update completion status for a user in an activity.
     * @param  int $userid    User id
     * @param  int $cmid      Course module id
     * @param  int $newstate  Activity completion
     * @return array          Array containing the current (updated) completion status.
     * @since Moodle 3.4
     * @throws moodle_exception
     */
    public static function override_activity_completion_status($userid, $cmid, $newstate) {
        // Validate and normalize parameters.
        $params = self::validate_parameters(self::override_activity_completion_status_parameters(),
            array('userid' => $userid, 'cmid' => $cmid, 'newstate' => $newstate));
        $userid = $params['userid'];
        $cmid = $params['cmid'];
        $newstate = $params['newstate'];

        $context = context_module::instance($cmid);
        self::validate_context($context);

        list($course, $cm) = get_course_and_cm_from_cmid($cmid);

        // Set up completion object and check it is enabled.
        $completion = new completion_info($course);
        if (!$completion->is_enabled()) {
            throw new moodle_exception('completionnotenabled', 'completion');
        }

        // Update completion state and get the new state back.
        $completion->update_state($cm, $newstate, $userid, true);
        $completiondata = $completion->get_data($cm, false, $userid);

        // Return the current state of completion.
        return [
            'cmid' => $completiondata->coursemoduleid,
            'userid' => $completiondata->userid,
            'state' => $completiondata->completionstate,
            'timecompleted' => $completiondata->timemodified,
            'overrideby' => $completiondata->overrideby,
            'tracking' => $completion->is_enabled($cm)
        ];
    }

    /**
     * Describes the override_activity_completion_status return value.
     *
     * @return external_single_structure
     * @since Moodle 3.4
     */
    public static function override_activity_completion_status_returns() {

        return new external_single_structure(
            array(
                'cmid' => new external_value(PARAM_INT, 'The course module id'),
                'userid' => new external_value(PARAM_INT, 'The user id to which the completion info belongs'),
                'state'   => new external_value(PARAM_INT, 'The current completion state.'),
                'timecompleted' => new external_value(PARAM_INT, 'time of completion'),
                'overrideby' => new external_value(PARAM_INT, 'The user id who has overriden the status, or null'),
                'tracking'      => new external_value(PARAM_INT, 'type of tracking:
                                                                    0 means none, 1 manual, 2 automatic'),
            )
        );
    }

    /**
     * Returns description of method parameters
     *
     * @return external_function_parameters
     * @since Moodle 2.9
     */
    public static function get_activities_completion_status_parameters() {
        return new external_function_parameters(
            array(
                'courseid' => new external_value(PARAM_INT, 'Course ID'),
                'userid'   => new external_value(PARAM_INT, 'User ID'),
            )
        );
    }

    /**
     * Get Activities completion status
     *
     * @param int $courseid ID of the Course
     * @param int $userid ID of the User
     * @return array of activities progress and warnings
     * @throws moodle_exception
     * @since Moodle 2.9
     * @throws moodle_exception
     */
    public static function get_activities_completion_status($courseid, $userid) {
< global $CFG, $USER;
> global $CFG, $USER, $PAGE;
require_once($CFG->libdir . '/grouplib.php'); $warnings = array(); $arrayparams = array( 'courseid' => $courseid, 'userid' => $userid, ); $params = self::validate_parameters(self::get_activities_completion_status_parameters(), $arrayparams); $course = get_course($params['courseid']); $user = core_user::get_user($params['userid'], '*', MUST_EXIST); core_user::require_active_user($user); $context = context_course::instance($course->id); self::validate_context($context); // Check that current user have permissions to see this user's activities. if ($user->id != $USER->id) { require_capability('report/progress:view', $context); if (!groups_user_groups_visible($course, $user->id)) { // We are not in the same group! throw new moodle_exception('accessdenied', 'admin'); } } $completion = new completion_info($course); $activities = $completion->get_activities(); $results = array(); foreach ($activities as $activity) {
<
// Check if current user has visibility on this activity. if (!$activity->uservisible) { continue; }
<
// Get progress information and state (we must use get_data because it works for all user roles in course).
< $activitycompletiondata = $completion->get_data($activity, true, $user->id); < < $results[] = array(
> $exporter = new \core_completion\external\completion_info_exporter( > $course, > $activity, > $userid, > ); > $renderer = $PAGE->get_renderer('core'); > $data = (array)$exporter->export($renderer); > $results[] = array_merge([
'cmid' => $activity->id, 'modname' => $activity->modname, 'instance' => $activity->instance,
< 'state' => $activitycompletiondata->completionstate, < 'timecompleted' => $activitycompletiondata->timemodified,
'tracking' => $activity->completion,
< 'overrideby' => $activitycompletiondata->overrideby, < 'valueused' => core_availability\info::completion_value_used($course, $activity->id) < );
> ], $data);
} $results = array( 'statuses' => $results, 'warnings' => $warnings ); return $results; } /** * Returns description of method result value * * @return external_description * @since Moodle 2.9 */ public static function get_activities_completion_status_returns() { return new external_single_structure( array( 'statuses' => new external_multiple_structure( new external_single_structure(
< array( < 'cmid' => new external_value(PARAM_INT, 'comment ID'),
> [ > 'cmid' => new external_value(PARAM_INT, 'course module ID'),
'modname' => new external_value(PARAM_PLUGIN, 'activity module name'), 'instance' => new external_value(PARAM_INT, 'instance ID'),
< 'state' => new external_value(PARAM_INT, 'completion state value: < 0 means incomplete, 1 complete, < 2 complete pass, 3 complete fail'), < 'timecompleted' => new external_value(PARAM_INT, 'timestamp for completed activity'), < 'tracking' => new external_value(PARAM_INT, 'type of tracking: < 0 means none, 1 manual, 2 automatic'), < 'overrideby' => new external_value(PARAM_INT, 'The user id who has overriden the status, or null',
> 'state' => new external_value(PARAM_INT, > "Completion state value: > 0 means incomplete, > 1 complete, > 2 complete pass, > 3 complete fail" > ), > 'timecompleted' => new external_value(PARAM_INT, > 'timestamp for completed activity'), > 'tracking' => new external_value(PARAM_INT, > "type of tracking: > 0 means none, > 1 manual, > 2 automatic" > ), > 'overrideby' => new external_value(PARAM_INT, > 'The user id who has overriden the status, or null', VALUE_OPTIONAL), > 'valueused' => new external_value(PARAM_BOOL, > 'Whether the completion status affects the availability of another activity.',
VALUE_OPTIONAL),
< 'valueused' => new external_value(PARAM_BOOL, 'Whether the completion status affects the availability < of another activity.', VALUE_OPTIONAL), < ), 'Activity'
> 'hascompletion' => new external_value(PARAM_BOOL, > 'Whether this activity module has completion enabled', > VALUE_OPTIONAL), > 'isautomatic' => new external_value(PARAM_BOOL, > 'Whether this activity module instance tracks completion automatically.', > VALUE_OPTIONAL), > 'istrackeduser' => new external_value(PARAM_BOOL, > 'Whether completion is being tracked for this user.', > VALUE_OPTIONAL), > 'uservisible' => new external_value(PARAM_BOOL, > 'Whether this activity is visible to the user.', > VALUE_OPTIONAL), > 'details' => new external_multiple_structure( > new external_single_structure( > [ > 'rulename' => new external_value(PARAM_TEXT, 'Rule name'), > 'rulevalue' => new external_single_structure( > [ > 'status' => new external_value(PARAM_INT, 'Completion status'), > 'description' => new external_value(PARAM_TEXT, 'Completion description'), > ] > ) > ] > ), > 'Completion status details', > VALUE_DEFAULT, > [] > ), > > ], 'Activity'
), 'List of activities status' ), 'warnings' => new external_warnings() ) ); } /** * Returns description of method parameters * * @return external_function_parameters * @since Moodle 2.9 */ public static function get_course_completion_status_parameters() { return new external_function_parameters( array( 'courseid' => new external_value(PARAM_INT, 'Course ID'), 'userid' => new external_value(PARAM_INT, 'User ID'), ) ); } /** * Get Course completion status * * @param int $courseid ID of the Course * @param int $userid ID of the User * @return array of course completion status and warnings * @since Moodle 2.9 * @throws moodle_exception */ public static function get_course_completion_status($courseid, $userid) { global $CFG, $USER; require_once($CFG->libdir . '/grouplib.php'); $warnings = array(); $arrayparams = array( 'courseid' => $courseid, 'userid' => $userid, ); $params = self::validate_parameters(self::get_course_completion_status_parameters(), $arrayparams); $course = get_course($params['courseid']); $user = core_user::get_user($params['userid'], '*', MUST_EXIST); core_user::require_active_user($user); $context = context_course::instance($course->id); self::validate_context($context); // Can current user see user's course completion status? // This check verifies if completion is enabled because $course is mandatory. if (!completion_can_view_data($user->id, $course)) { throw new moodle_exception('cannotviewreport'); } // The previous function doesn't check groups. if ($user->id != $USER->id) { if (!groups_user_groups_visible($course, $user->id)) { // We are not in the same group! throw new moodle_exception('accessdenied', 'admin'); } } $info = new completion_info($course); // Check this user is enroled. if (!$info->is_tracked_user($user->id)) { if ($USER->id == $user->id) { throw new moodle_exception('notenroled', 'completion'); } else { throw new moodle_exception('usernotenroled', 'completion'); } } $completions = $info->get_completions($user->id); if (empty($completions)) { throw new moodle_exception('nocriteriaset', 'completion'); } // Load course completion. $completionparams = array( 'userid' => $user->id, 'course' => $course->id, ); $ccompletion = new completion_completion($completionparams); $completionrows = array(); // Loop through course criteria. foreach ($completions as $completion) { $criteria = $completion->get_criteria(); $completionrow = array(); $completionrow['type'] = $criteria->criteriatype; $completionrow['title'] = $criteria->get_title(); $completionrow['status'] = $completion->get_status(); $completionrow['complete'] = $completion->is_complete(); $completionrow['timecompleted'] = $completion->timecompleted; $completionrow['details'] = $criteria->get_details($completion); $completionrows[] = $completionrow; } $result = array( 'completed' => $info->is_course_complete($user->id), 'aggregation' => $info->get_aggregation_method(), 'completions' => $completionrows ); $results = array( 'completionstatus' => $result, 'warnings' => $warnings ); return $results; } /** * Returns description of method result value * * @return external_description * @since Moodle 2.9 */ public static function get_course_completion_status_returns() { return new external_single_structure( array( 'completionstatus' => new external_single_structure( array( 'completed' => new external_value(PARAM_BOOL, 'true if the course is complete, false otherwise'), 'aggregation' => new external_value(PARAM_INT, 'aggregation method 1 means all, 2 means any'), 'completions' => new external_multiple_structure( new external_single_structure( array( 'type' => new external_value(PARAM_INT, 'Completion criteria type'), 'title' => new external_value(PARAM_TEXT, 'Completion criteria Title'), 'status' => new external_value(PARAM_NOTAGS, 'Completion status (Yes/No) a % or number'), 'complete' => new external_value(PARAM_BOOL, 'Completion status (true/false)'), 'timecompleted' => new external_value(PARAM_INT, 'Timestamp for criteria completetion'), 'details' => new external_single_structure( array( 'type' => new external_value(PARAM_TEXT, 'Type description'), 'criteria' => new external_value(PARAM_RAW, 'Criteria description'), 'requirement' => new external_value(PARAM_TEXT, 'Requirement description'), 'status' => new external_value(PARAM_RAW, 'Status description, can be anything'), ), 'details'), ), 'Completions' ), '' ) ), 'Course status' ), 'warnings' => new external_warnings() ), 'Course completion status' ); } /** * Describes the parameters for mark_course_self_completed. * * @return external_function_parameters * @since Moodle 3.0 */ public static function mark_course_self_completed_parameters() { return new external_function_parameters ( array( 'courseid' => new external_value(PARAM_INT, 'Course ID') ) ); } /** * Update the course completion status for the current user (if course self-completion is enabled). * * @param int $courseid Course id * @return array Result and possible warnings * @since Moodle 3.0 * @throws moodle_exception */ public static function mark_course_self_completed($courseid) { global $USER; $warnings = array(); $params = self::validate_parameters(self::mark_course_self_completed_parameters(), array('courseid' => $courseid)); $course = get_course($params['courseid']); $context = context_course::instance($course->id); self::validate_context($context); // Set up completion object and check it is enabled. $completion = new completion_info($course); if (!$completion->is_enabled()) { throw new moodle_exception('completionnotenabled', 'completion'); } if (!$completion->is_tracked_user($USER->id)) { throw new moodle_exception('nottracked', 'completion'); } $completion = $completion->get_completion($USER->id, COMPLETION_CRITERIA_TYPE_SELF); // Self completion criteria not enabled. if (!$completion) { throw new moodle_exception('noselfcompletioncriteria', 'completion'); } // Check if the user has already marked himself as complete. if ($completion->is_complete()) { throw new moodle_exception('useralreadymarkedcomplete', 'completion'); } // Mark the course complete. $completion->mark_complete(); $result = array(); $result['status'] = true; $result['warnings'] = $warnings; return $result; } /** * Describes the mark_course_self_completed return value. * * @return external_single_structure * @since Moodle 3.0 */ public static function mark_course_self_completed_returns() { return new external_single_structure( array( 'status' => new external_value(PARAM_BOOL, 'status, true if success'), 'warnings' => new external_warnings(), ) ); } }