Merge branch 'MDL-29320-master' of git://github.com/junpataleta/moodle
[moodle.git] / completion / classes / external.php
CommitLineData
b9d17109
JL
1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
17/**
18 * Completion external API
19 *
20 * @package core_completion
21 * @category external
22 * @copyright 2015 Juan Leyva <juan@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @since Moodle 2.9
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once("$CFG->libdir/externallib.php");
30require_once("$CFG->libdir/completionlib.php");
31
32/**
33 * Completion external functions
34 *
35 * @package core_completion
36 * @category external
37 * @copyright 2015 Juan Leyva <juan@moodle.com>
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39 * @since Moodle 2.9
40 */
41class core_completion_external extends external_api {
42
43 /**
44 * Describes the parameters for update_activity_completion_status_manually.
45 *
9db43c73 46 * @return external_function_parameters
b9d17109
JL
47 * @since Moodle 2.9
48 */
49 public static function update_activity_completion_status_manually_parameters() {
50 return new external_function_parameters (
51 array(
52 'cmid' => new external_value(PARAM_INT, 'course module id'),
53 'completed' => new external_value(PARAM_BOOL, 'activity completed or not'),
54 )
55 );
56 }
57
58 /**
59 * Update completion status for the current user in an activity, only for activities with manual tracking.
60 * @param int $cmid Course module id
61 * @param bool $completed Activity completed or not
62 * @return array Result and possible warnings
63 * @since Moodle 2.9
64 * @throws moodle_exception
65 */
66 public static function update_activity_completion_status_manually($cmid, $completed) {
67
68 // Validate and normalize parameters.
69 $params = self::validate_parameters(self::update_activity_completion_status_manually_parameters(),
70 array('cmid' => $cmid, 'completed' => $completed));
71 $cmid = $params['cmid'];
72 $completed = $params['completed'];
73
74 $warnings = array();
75
76 $context = context_module::instance($cmid);
77 self::validate_context($context);
7868aab1 78 require_capability('moodle/course:togglecompletion', $context);
b9d17109
JL
79
80 list($course, $cm) = get_course_and_cm_from_cmid($cmid);
81
82 // Set up completion object and check it is enabled.
83 $completion = new completion_info($course);
84 if (!$completion->is_enabled()) {
85 throw new moodle_exception('completionnotenabled', 'completion');
86 }
87
88 // Check completion state is manual.
89 if ($cm->completion != COMPLETION_TRACKING_MANUAL) {
90 throw new moodle_exception('cannotmanualctrack', 'error');
91 }
92
93 $targetstate = ($completed) ? COMPLETION_COMPLETE : COMPLETION_INCOMPLETE;
94 $completion->update_state($cm, $targetstate);
95
96 $result = array();
97 $result['status'] = true;
98 $result['warnings'] = $warnings;
99 return $result;
100 }
101
102 /**
103 * Describes the update_activity_completion_status_manually return value.
104 *
105 * @return external_single_structure
106 * @since Moodle 2.9
107 */
108 public static function update_activity_completion_status_manually_returns() {
109
110 return new external_single_structure(
111 array(
112 'status' => new external_value(PARAM_BOOL, 'status, true if success'),
113 'warnings' => new external_warnings(),
114 )
115 );
116 }
117
a39918da
EEAK
118 /**
119 * Describes the parameters for override_activity_completion_status.
120 *
121 * @return external_external_function_parameters
8fbc41d8 122 * @since Moodle 3.4
a39918da
EEAK
123 */
124 public static function override_activity_completion_status_parameters() {
125 return new external_function_parameters (
126 array(
127 'userid' => new external_value(PARAM_INT, 'user id'),
128 'cmid' => new external_value(PARAM_INT, 'course module id'),
129 'newstate' => new external_value(PARAM_INT, 'the new activity completion state'),
130 )
131 );
132 }
133
134 /**
135 * Update completion status for a user in an activity.
136 * @param int $userid User id
137 * @param int $cmid Course module id
138 * @param int $newstate Activity completion
b08337c3 139 * @return array Array containing the current (updated) completion status.
8fbc41d8 140 * @since Moodle 3.4
a39918da
EEAK
141 * @throws moodle_exception
142 */
143 public static function override_activity_completion_status($userid, $cmid, $newstate) {
a39918da
EEAK
144 // Validate and normalize parameters.
145 $params = self::validate_parameters(self::override_activity_completion_status_parameters(),
146 array('userid' => $userid, 'cmid' => $cmid, 'newstate' => $newstate));
147 $userid = $params['userid'];
148 $cmid = $params['cmid'];
149 $newstate = $params['newstate'];
150
a39918da
EEAK
151 $context = context_module::instance($cmid);
152 self::validate_context($context);
153
154 list($course, $cm) = get_course_and_cm_from_cmid($cmid);
155
156 // Set up completion object and check it is enabled.
157 $completion = new completion_info($course);
158 if (!$completion->is_enabled()) {
159 throw new moodle_exception('completionnotenabled', 'completion');
160 }
161
b08337c3 162 // Update completion state and get the new state back.
a39918da 163 $completion->update_state($cm, $newstate, $userid, true);
a39918da 164 $completiondata = $completion->get_data($cm, false, $userid);
a39918da 165
8fbc41d8 166 // Return the current state of completion.
b08337c3
JD
167 return [
168 'cmid' => $completiondata->coursemoduleid,
169 'userid' => $completiondata->userid,
170 'state' => $completiondata->completionstate,
171 'timecompleted' => $completiondata->timemodified,
172 'overrideby' => $completiondata->overrideby,
173 'tracking' => $completion->is_enabled($cm)
8fbc41d8 174 ];
a39918da
EEAK
175 }
176
177 /**
178 * Describes the override_activity_completion_status return value.
179 *
180 * @return external_single_structure
8fbc41d8 181 * @since Moodle 3.4
a39918da
EEAK
182 */
183 public static function override_activity_completion_status_returns() {
184
185 return new external_single_structure(
186 array(
b08337c3
JD
187 'cmid' => new external_value(PARAM_INT, 'The course module id'),
188 'userid' => new external_value(PARAM_INT, 'The user id to which the completion info belongs'),
189 'state' => new external_value(PARAM_INT, 'The current completion state.'),
190 'timecompleted' => new external_value(PARAM_INT, 'time of completion'),
191 'overrideby' => new external_value(PARAM_INT, 'The user id who has overriden the status, or null'),
192 'tracking' => new external_value(PARAM_INT, 'type of tracking:
193 0 means none, 1 manual, 2 automatic'),
a39918da
EEAK
194 )
195 );
196 }
197
5f2406c9
CC
198 /**
199 * Returns description of method parameters
200 *
201 * @return external_function_parameters
202 * @since Moodle 2.9
203 */
204 public static function get_activities_completion_status_parameters() {
205 return new external_function_parameters(
206 array(
207 'courseid' => new external_value(PARAM_INT, 'Course ID'),
208 'userid' => new external_value(PARAM_INT, 'User ID'),
209 )
210 );
211 }
212
213 /**
214 * Get Activities completion status
215 *
216 * @param int $courseid ID of the Course
217 * @param int $userid ID of the User
218 * @return array of activities progress and warnings
219 * @throws moodle_exception
220 * @since Moodle 2.9
604afeff 221 * @throws moodle_exception
5f2406c9
CC
222 */
223 public static function get_activities_completion_status($courseid, $userid) {
224 global $CFG, $USER;
225 require_once($CFG->libdir . '/grouplib.php');
9cd1093c 226
5f2406c9
CC
227 $warnings = array();
228 $arrayparams = array(
229 'courseid' => $courseid,
230 'userid' => $userid,
231 );
232
233 $params = self::validate_parameters(self::get_activities_completion_status_parameters(), $arrayparams);
234
235 $course = get_course($params['courseid']);
4485f7c5
JL
236 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
237 core_user::require_active_user($user);
5f2406c9
CC
238
239 $context = context_course::instance($course->id);
240 self::validate_context($context);
241
242 // Check that current user have permissions to see this user's activities.
243 if ($user->id != $USER->id) {
244 require_capability('report/progress:view', $context);
9cd1093c
JL
245 if (!groups_user_groups_visible($course, $user->id)) {
246 // We are not in the same group!
247 throw new moodle_exception('accessdenied', 'admin');
5f2406c9
CC
248 }
249 }
250
251 $completion = new completion_info($course);
252 $activities = $completion->get_activities();
5f2406c9
CC
253
254 $results = array();
255 foreach ($activities as $activity) {
256
257 // Check if current user has visibility on this activity.
9cd1093c 258 if (!$activity->uservisible) {
5f2406c9
CC
259 continue;
260 }
261
0e8b3d92
JL
262 // Get progress information and state (we must use get_data because it works for all user roles in course).
263 $activitycompletiondata = $completion->get_data($activity, true, $user->id);
5f2406c9
CC
264
265 $results[] = array(
266 'cmid' => $activity->id,
267 'modname' => $activity->modname,
268 'instance' => $activity->instance,
0e8b3d92
JL
269 'state' => $activitycompletiondata->completionstate,
270 'timecompleted' => $activitycompletiondata->timemodified,
15ead7a1 271 'tracking' => $activity->completion,
76724712
MJ
272 'overrideby' => $activitycompletiondata->overrideby,
273 'valueused' => core_availability\info::completion_value_used($course, $activity->id)
5f2406c9
CC
274 );
275 }
276
277 $results = array(
278 'statuses' => $results,
279 'warnings' => $warnings
280 );
281 return $results;
282 }
283
284 /**
285 * Returns description of method result value
286 *
287 * @return external_description
288 * @since Moodle 2.9
289 */
290 public static function get_activities_completion_status_returns() {
291 return new external_single_structure(
292 array(
293 'statuses' => new external_multiple_structure(
294 new external_single_structure(
295 array(
9cd1093c
JL
296 'cmid' => new external_value(PARAM_INT, 'comment ID'),
297 'modname' => new external_value(PARAM_PLUGIN, 'activity module name'),
298 'instance' => new external_value(PARAM_INT, 'instance ID'),
299 'state' => new external_value(PARAM_INT, 'completion state value:
300 0 means incomplete, 1 complete,
301 2 complete pass, 3 complete fail'),
302 'timecompleted' => new external_value(PARAM_INT, 'timestamp for completed activity'),
303 'tracking' => new external_value(PARAM_INT, 'type of tracking:
304 0 means none, 1 manual, 2 automatic'),
15ead7a1
PFO
305 'overrideby' => new external_value(PARAM_INT, 'The user id who has overriden the status, or null',
306 VALUE_OPTIONAL),
76724712
MJ
307 'valueused' => new external_value(PARAM_BOOL, 'Whether the completion status affects the availability
308 of another activity.', VALUE_OPTIONAL),
5f2406c9
CC
309 ), 'Activity'
310 ), 'List of activities status'
311 ),
312 'warnings' => new external_warnings()
313 )
314 );
315 }
90c32664
CC
316
317 /**
318 * Returns description of method parameters
319 *
320 * @return external_function_parameters
321 * @since Moodle 2.9
322 */
323 public static function get_course_completion_status_parameters() {
324 return new external_function_parameters(
325 array(
326 'courseid' => new external_value(PARAM_INT, 'Course ID'),
327 'userid' => new external_value(PARAM_INT, 'User ID'),
328 )
329 );
330 }
331 /**
332 * Get Course completion status
333 *
334 * @param int $courseid ID of the Course
335 * @param int $userid ID of the User
336 * @return array of course completion status and warnings
337 * @since Moodle 2.9
338 * @throws moodle_exception
339 */
340 public static function get_course_completion_status($courseid, $userid) {
341 global $CFG, $USER;
342 require_once($CFG->libdir . '/grouplib.php');
343
344 $warnings = array();
345 $arrayparams = array(
346 'courseid' => $courseid,
347 'userid' => $userid,
348 );
349 $params = self::validate_parameters(self::get_course_completion_status_parameters(), $arrayparams);
350
351 $course = get_course($params['courseid']);
4485f7c5
JL
352 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
353 core_user::require_active_user($user);
354
90c32664
CC
355 $context = context_course::instance($course->id);
356 self::validate_context($context);
357
358 // Can current user see user's course completion status?
359 // This check verifies if completion is enabled because $course is mandatory.
360 if (!completion_can_view_data($user->id, $course)) {
361 throw new moodle_exception('cannotviewreport');
362 }
363
364 // The previous function doesn't check groups.
365 if ($user->id != $USER->id) {
366 if (!groups_user_groups_visible($course, $user->id)) {
367 // We are not in the same group!
368 throw new moodle_exception('accessdenied', 'admin');
369 }
370 }
371
372 $info = new completion_info($course);
373
374 // Check this user is enroled.
375 if (!$info->is_tracked_user($user->id)) {
376 if ($USER->id == $user->id) {
377 throw new moodle_exception('notenroled', 'completion');
378 } else {
379 throw new moodle_exception('usernotenroled', 'completion');
380 }
381 }
382
383 $completions = $info->get_completions($user->id);
384 if (empty($completions)) {
03f3f718 385 throw new moodle_exception('nocriteriaset', 'completion');
90c32664
CC
386 }
387
388 // Load course completion.
389 $completionparams = array(
390 'userid' => $user->id,
391 'course' => $course->id,
392 );
393 $ccompletion = new completion_completion($completionparams);
394
395 $completionrows = array();
396 // Loop through course criteria.
397 foreach ($completions as $completion) {
398 $criteria = $completion->get_criteria();
399
400 $completionrow = array();
401 $completionrow['type'] = $criteria->criteriatype;
402 $completionrow['title'] = $criteria->get_title();
403 $completionrow['status'] = $completion->get_status();
404 $completionrow['complete'] = $completion->is_complete();
405 $completionrow['timecompleted'] = $completion->timecompleted;
406 $completionrow['details'] = $criteria->get_details($completion);
407 $completionrows[] = $completionrow;
408 }
409
410 $result = array(
411 'completed' => $info->is_course_complete($user->id),
412 'aggregation' => $info->get_aggregation_method(),
413 'completions' => $completionrows
414 );
415
416 $results = array(
417 'completionstatus' => $result,
418 'warnings' => $warnings
419 );
420 return $results;
421
422 }
423 /**
424 * Returns description of method result value
425 *
426 * @return external_description
427 * @since Moodle 2.9
428 */
429 public static function get_course_completion_status_returns() {
430 return new external_single_structure(
431 array(
432 'completionstatus' => new external_single_structure(
433 array(
434 'completed' => new external_value(PARAM_BOOL, 'true if the course is complete, false otherwise'),
435 'aggregation' => new external_value(PARAM_INT, 'aggregation method 1 means all, 2 means any'),
436 'completions' => new external_multiple_structure(
437 new external_single_structure(
438 array(
439 'type' => new external_value(PARAM_INT, 'Completion criteria type'),
440 'title' => new external_value(PARAM_TEXT, 'Completion criteria Title'),
441 'status' => new external_value(PARAM_NOTAGS, 'Completion status (Yes/No) a % or number'),
442 'complete' => new external_value(PARAM_BOOL, 'Completion status (true/false)'),
443 'timecompleted' => new external_value(PARAM_INT, 'Timestamp for criteria completetion'),
444 'details' => new external_single_structure(
445 array(
446 'type' => new external_value(PARAM_TEXT, 'Type description'),
447 'criteria' => new external_value(PARAM_RAW, 'Criteria description'),
448 'requirement' => new external_value(PARAM_TEXT, 'Requirement description'),
edf6db65 449 'status' => new external_value(PARAM_RAW, 'Status description, can be anything'),
90c32664
CC
450 ), 'details'),
451 ), 'Completions'
452 ), ''
453 )
454 ), 'Course status'
455 ),
456 'warnings' => new external_warnings()
457 ), 'Course completion status'
458 );
459 }
460
23b398fc
JL
461 /**
462 * Describes the parameters for mark_course_self_completed.
463 *
9db43c73 464 * @return external_function_parameters
23b398fc
JL
465 * @since Moodle 3.0
466 */
467 public static function mark_course_self_completed_parameters() {
468 return new external_function_parameters (
469 array(
470 'courseid' => new external_value(PARAM_INT, 'Course ID')
471 )
472 );
473 }
474
475 /**
476 * Update the course completion status for the current user (if course self-completion is enabled).
477 *
478 * @param int $courseid Course id
479 * @return array Result and possible warnings
480 * @since Moodle 3.0
481 * @throws moodle_exception
482 */
483 public static function mark_course_self_completed($courseid) {
484 global $USER;
485
486 $warnings = array();
487 $params = self::validate_parameters(self::mark_course_self_completed_parameters(),
488 array('courseid' => $courseid));
489
490 $course = get_course($params['courseid']);
491 $context = context_course::instance($course->id);
492 self::validate_context($context);
493
494 // Set up completion object and check it is enabled.
495 $completion = new completion_info($course);
496 if (!$completion->is_enabled()) {
497 throw new moodle_exception('completionnotenabled', 'completion');
498 }
499
500 if (!$completion->is_tracked_user($USER->id)) {
501 throw new moodle_exception('nottracked', 'completion');
502 }
503
504 $completion = $completion->get_completion($USER->id, COMPLETION_CRITERIA_TYPE_SELF);
505
506 // Self completion criteria not enabled.
507 if (!$completion) {
508 throw new moodle_exception('noselfcompletioncriteria', 'completion');
509 }
510
511 // Check if the user has already marked himself as complete.
512 if ($completion->is_complete()) {
513 throw new moodle_exception('useralreadymarkedcomplete', 'completion');
514 }
515
516 // Mark the course complete.
517 $completion->mark_complete();
518
519 $result = array();
520 $result['status'] = true;
521 $result['warnings'] = $warnings;
522 return $result;
523 }
524
525 /**
526 * Describes the mark_course_self_completed return value.
527 *
528 * @return external_single_structure
529 * @since Moodle 3.0
530 */
531 public static function mark_course_self_completed_returns() {
532
533 return new external_single_structure(
534 array(
535 'status' => new external_value(PARAM_BOOL, 'status, true if success'),
536 'warnings' => new external_warnings(),
537 )
538 );
539 }
540
b9d17109 541}