2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
19 * External course participation api.
21 * This api is mostly read only, the actual enrol and unenrol
22 * support is in each enrol plugin.
26 * @copyright 2010 Jerome Mouneyrac
27 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
30 defined('MOODLE_INTERNAL') ||
die();
32 require_once("$CFG->libdir/externallib.php");
35 * Enrol external functions
39 * @copyright 2011 Jerome Mouneyrac
40 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43 class core_enrol_external
extends external_api
{
46 * Returns description of method parameters
48 * @return external_function_parameters
51 public static function get_enrolled_users_with_capability_parameters() {
52 return new external_function_parameters(
54 'coursecapabilities' => new external_multiple_structure(
55 new external_single_structure(
57 'courseid' => new external_value(PARAM_INT
, 'Course ID number in the Moodle course table'),
58 'capabilities' => new external_multiple_structure(
59 new external_value(PARAM_CAPABILITY
, 'Capability name, such as mod/forum:viewdiscussion')),
62 , 'course id and associated capability name'),
63 'options' => new external_multiple_structure(
64 new external_single_structure(
66 'name' => new external_value(PARAM_ALPHANUMEXT
, 'option name'),
67 'value' => new external_value(PARAM_RAW
, 'option value')
70 * groupid (integer) return only users in this group id. Requires \'moodle/site:accessallgroups\' .
71 * onlyactive (integer) only users with active enrolments. Requires \'moodle/course:enrolreview\' .
72 * userfields (\'string, string, ...\') return only the values of these user fields.
73 * limitfrom (integer) sql limit from.
74 * limitnumber (integer) max number of users per course and capability.', VALUE_DEFAULT
, array())
80 * Return users that have the capabilities for each course specified. For each course and capability specified,
81 * a list of the users that are enrolled in the course and have that capability are returned.
83 * @param array $coursecapabilities array of course ids and associated capability names {courseid, {capabilities}}
84 * @return array An array of arrays describing users for each associated courseid and capability
87 public static function get_enrolled_users_with_capability($coursecapabilities, $options) {
89 require_once($CFG->dirroot
. "/user/lib.php");
91 if (empty($coursecapabilities)) {
92 throw new invalid_parameter_exception('Parameter can not be empty');
94 $params = self
::validate_parameters(self
::get_enrolled_users_with_capability_parameters(),
95 array ('coursecapabilities' => $coursecapabilities, 'options'=>$options));
100 $userfields = array();
103 foreach ($params['options'] as $option) {
104 switch ($option['name']) {
106 $groupid = (int)$option['value'];
109 $onlyactive = !empty($option['value']);
112 $thefields = explode(',', $option['value']);
113 foreach ($thefields as $f) {
114 $userfields[] = clean_param($f, PARAM_ALPHANUMEXT
);
118 $limitfrom = clean_param($option['value'], PARAM_INT
);
121 $limitnumber = clean_param($option['value'], PARAM_INT
);
126 foreach ($params['coursecapabilities'] as $coursecapability) {
127 $courseid = $coursecapability['courseid'];
128 $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST
);
129 $coursecontext = context_course
::instance($courseid);
130 if (!$coursecontext) {
131 throw new moodle_exception('cannotfindcourse', 'error', '', null,
132 'The course id ' . $courseid . ' doesn\'t exist.');
134 if ($courseid == SITEID
) {
135 $context = context_system
::instance();
137 $context = $coursecontext;
140 self
::validate_context($context);
141 } catch (Exception
$e) {
142 $exceptionparam = new stdClass();
143 $exceptionparam->message
= $e->getMessage();
144 $exceptionparam->courseid
= $params['courseid'];
145 throw new moodle_exception(get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
148 if ($courseid == SITEID
) {
149 require_capability('moodle/site:viewparticipants', $context);
151 require_capability('moodle/course:viewparticipants', $context);
153 // The accessallgroups capability is needed to use this option.
154 if (!empty($groupid) && groups_is_member($groupid)) {
155 require_capability('moodle/site:accessallgroups', $coursecontext);
157 // The course:enrolereview capability is needed to use this option.
159 require_capability('moodle/course:enrolreview', $coursecontext);
162 // To see the permissions of others role:review capability is required.
163 require_capability('moodle/role:review', $coursecontext);
164 foreach ($coursecapability['capabilities'] as $capability) {
165 $courseusers['courseid'] = $courseid;
166 $courseusers['capability'] = $capability;
168 list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $capability, $groupid, $onlyactive);
170 $sql = "SELECT u.* FROM {user} u WHERE u.id IN ($enrolledsql) ORDER BY u.id ASC";
172 $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams, $limitfrom, $limitnumber);
174 foreach ($enrolledusers as $courseuser) {
175 if ($userdetails = user_get_user_details($courseuser, $course, $userfields)) {
176 $users[] = $userdetails;
179 $enrolledusers->close();
180 $courseusers['users'] = $users;
181 $result[] = $courseusers;
188 * Returns description of method result value
190 * @return external_multiple_structure
193 public static function get_enrolled_users_with_capability_returns() {
194 return new external_multiple_structure( new external_single_structure (
196 'courseid' => new external_value(PARAM_INT
, 'Course ID number in the Moodle course table'),
197 'capability' => new external_value(PARAM_CAPABILITY
, 'Capability name'),
198 'users' => new external_multiple_structure(
199 new external_single_structure(
201 'id' => new external_value(PARAM_INT
, 'ID of the user'),
202 'username' => new external_value(PARAM_RAW
, 'Username', VALUE_OPTIONAL
),
203 'firstname' => new external_value(PARAM_NOTAGS
, 'The first name(s) of the user', VALUE_OPTIONAL
),
204 'lastname' => new external_value(PARAM_NOTAGS
, 'The family name of the user', VALUE_OPTIONAL
),
205 'fullname' => new external_value(PARAM_NOTAGS
, 'The fullname of the user'),
206 'email' => new external_value(PARAM_TEXT
, 'Email address', VALUE_OPTIONAL
),
207 'address' => new external_value(PARAM_MULTILANG
, 'Postal address', VALUE_OPTIONAL
),
208 'phone1' => new external_value(PARAM_NOTAGS
, 'Phone 1', VALUE_OPTIONAL
),
209 'phone2' => new external_value(PARAM_NOTAGS
, 'Phone 2', VALUE_OPTIONAL
),
210 'icq' => new external_value(PARAM_NOTAGS
, 'icq number', VALUE_OPTIONAL
),
211 'skype' => new external_value(PARAM_NOTAGS
, 'skype id', VALUE_OPTIONAL
),
212 'yahoo' => new external_value(PARAM_NOTAGS
, 'yahoo id', VALUE_OPTIONAL
),
213 'aim' => new external_value(PARAM_NOTAGS
, 'aim id', VALUE_OPTIONAL
),
214 'msn' => new external_value(PARAM_NOTAGS
, 'msn number', VALUE_OPTIONAL
),
215 'department' => new external_value(PARAM_TEXT
, 'department', VALUE_OPTIONAL
),
216 'institution' => new external_value(PARAM_TEXT
, 'institution', VALUE_OPTIONAL
),
217 'interests' => new external_value(PARAM_TEXT
, 'user interests (separated by commas)', VALUE_OPTIONAL
),
218 'firstaccess' => new external_value(PARAM_INT
, 'first access to the site (0 if never)', VALUE_OPTIONAL
),
219 'lastaccess' => new external_value(PARAM_INT
, 'last access to the site (0 if never)', VALUE_OPTIONAL
),
220 'description' => new external_value(PARAM_RAW
, 'User profile description', VALUE_OPTIONAL
),
221 'descriptionformat' => new external_value(PARAM_INT
, 'User profile description format', VALUE_OPTIONAL
),
222 'city' => new external_value(PARAM_NOTAGS
, 'Home city of the user', VALUE_OPTIONAL
),
223 'url' => new external_value(PARAM_URL
, 'URL of the user', VALUE_OPTIONAL
),
224 'country' => new external_value(PARAM_ALPHA
, 'Country code of the user, such as AU or CZ', VALUE_OPTIONAL
),
225 'profileimageurlsmall' => new external_value(PARAM_URL
, 'User image profile URL - small', VALUE_OPTIONAL
),
226 'profileimageurl' => new external_value(PARAM_URL
, 'User image profile URL - big', VALUE_OPTIONAL
),
227 'customfields' => new external_multiple_structure(
228 new external_single_structure(
230 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The type of the custom field'),
231 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
232 'name' => new external_value(PARAM_RAW
, 'The name of the custom field'),
233 'shortname' => new external_value(PARAM_RAW
, 'The shortname of the custom field'),
235 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL
),
236 'groups' => new external_multiple_structure(
237 new external_single_structure(
239 'id' => new external_value(PARAM_INT
, 'group id'),
240 'name' => new external_value(PARAM_RAW
, 'group name'),
241 'description' => new external_value(PARAM_RAW
, 'group description'),
243 ), 'user groups', VALUE_OPTIONAL
),
244 'roles' => new external_multiple_structure(
245 new external_single_structure(
247 'roleid' => new external_value(PARAM_INT
, 'role id'),
248 'name' => new external_value(PARAM_RAW
, 'role name'),
249 'shortname' => new external_value(PARAM_ALPHANUMEXT
, 'role shortname'),
250 'sortorder' => new external_value(PARAM_INT
, 'role sortorder')
252 ), 'user roles', VALUE_OPTIONAL
),
253 'preferences' => new external_multiple_structure(
254 new external_single_structure(
256 'name' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the preferences'),
257 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
259 ), 'User preferences', VALUE_OPTIONAL
),
260 'enrolledcourses' => new external_multiple_structure(
261 new external_single_structure(
263 'id' => new external_value(PARAM_INT
, 'Id of the course'),
264 'fullname' => new external_value(PARAM_RAW
, 'Fullname of the course'),
265 'shortname' => new external_value(PARAM_RAW
, 'Shortname of the course')
267 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL
)
269 ), 'List of users that are enrolled in the course and have the specified capability'),
276 * Returns description of method parameters
278 * @return external_function_parameters
280 public static function get_users_courses_parameters() {
281 return new external_function_parameters(
283 'userid' => new external_value(PARAM_INT
, 'user id'),
289 * Get list of courses user is enrolled in (only active enrolments are returned).
290 * Please note the current user must be able to access the course, otherwise the course is not included.
293 * @return array of courses
295 public static function get_users_courses($userid) {
298 // Do basic automatic PARAM checks on incoming data, using params description
299 // If any problems are found then exceptions are thrown with helpful error messages
300 $params = self
::validate_parameters(self
::get_users_courses_parameters(), array('userid'=>$userid));
302 $courses = enrol_get_users_courses($params['userid'], true, 'id, shortname, fullname, idnumber, visible,
303 summary, summaryformat, format, showgrades, lang, enablecompletion, category');
306 foreach ($courses as $course) {
307 $context = context_course
::instance($course->id
, IGNORE_MISSING
);
309 self
::validate_context($context);
310 } catch (Exception
$e) {
311 // current user can not access this course, sorry we can not disclose who is enrolled in this course!
315 if ($userid != $USER->id
and !has_capability('moodle/course:viewparticipants', $context)) {
316 // we need capability to view participants
320 list($enrolledsqlselect, $enrolledparams) = get_enrolled_sql($context);
321 $enrolledsql = "SELECT COUNT('x') FROM ($enrolledsqlselect) enrolleduserids";
322 $enrolledusercount = $DB->count_records_sql($enrolledsql, $enrolledparams);
324 list($course->summary
, $course->summaryformat
) =
325 external_format_text($course->summary
, $course->summaryformat
, $context->id
, 'course', 'summary', null);
326 $course->fullname
= external_format_string($course->fullname
, $context->id
);
327 $course->shortname
= external_format_string($course->shortname
, $context->id
);
331 'shortname' => $course->shortname
,
332 'fullname' => $course->fullname
,
333 'idnumber' => $course->idnumber
,
334 'visible' => $course->visible
,
335 'enrolledusercount' => $enrolledusercount,
336 'summary' => $course->summary
,
337 'summaryformat' => $course->summaryformat
,
338 'format' => $course->format
,
339 'showgrades' => $course->showgrades
,
340 'lang' => $course->lang
,
341 'enablecompletion' => $course->enablecompletion
,
342 'category' => $course->category
350 * Returns description of method result value
352 * @return external_description
354 public static function get_users_courses_returns() {
355 return new external_multiple_structure(
356 new external_single_structure(
358 'id' => new external_value(PARAM_INT
, 'id of course'),
359 'shortname' => new external_value(PARAM_RAW
, 'short name of course'),
360 'fullname' => new external_value(PARAM_RAW
, 'long name of course'),
361 'enrolledusercount' => new external_value(PARAM_INT
, 'Number of enrolled users in this course'),
362 'idnumber' => new external_value(PARAM_RAW
, 'id number of course'),
363 'visible' => new external_value(PARAM_INT
, '1 means visible, 0 means hidden course'),
364 'summary' => new external_value(PARAM_RAW
, 'summary', VALUE_OPTIONAL
),
365 'summaryformat' => new external_format_value('summary', VALUE_OPTIONAL
),
366 'format' => new external_value(PARAM_PLUGIN
, 'course format: weeks, topics, social, site', VALUE_OPTIONAL
),
367 'showgrades' => new external_value(PARAM_BOOL
, 'true if grades are shown, otherwise false', VALUE_OPTIONAL
),
368 'lang' => new external_value(PARAM_LANG
, 'forced course language', VALUE_OPTIONAL
),
369 'enablecompletion' => new external_value(PARAM_BOOL
, 'true if completion is enabled, otherwise false',
371 'category' => new external_value(PARAM_INT
, 'course category id', VALUE_OPTIONAL
),
378 * Returns description of method parameters
380 * @return external_function_parameters
382 public static function get_enrolled_users_parameters() {
383 return new external_function_parameters(
385 'courseid' => new external_value(PARAM_INT
, 'course id'),
386 'options' => new external_multiple_structure(
387 new external_single_structure(
389 'name' => new external_value(PARAM_ALPHANUMEXT
, 'option name'),
390 'value' => new external_value(PARAM_RAW
, 'option value')
393 * withcapability (string) return only users with this capability. This option requires \'moodle/role:review\' on the course context.
394 * groupid (integer) return only users in this group id. If the course has groups enabled and this param
395 isn\'t defined, returns all the viewable users.
396 This option requires \'moodle/site:accessallgroups\' on the course context if the
397 user doesn\'t belong to the group.
398 * onlyactive (integer) return only users with active enrolments and matching time restrictions. This option requires \'moodle/course:enrolreview\' on the course context.
399 * userfields (\'string, string, ...\') return only the values of these user fields.
400 * limitfrom (integer) sql limit from.
401 * limitnumber (integer) maximum number of returned users.
402 * sortby (string) sort by id, firstname or lastname. For ordering like the site does, use siteorder.
403 * sortdirection (string) ASC or DESC',
404 VALUE_DEFAULT
, array()),
410 * Get course participants details
412 * @param int $courseid course id
413 * @param array $options options {
414 * 'name' => option name
415 * 'value' => option value
417 * @return array An array of users
419 public static function get_enrolled_users($courseid, $options = array()) {
420 global $CFG, $USER, $DB;
421 require_once($CFG->dirroot
. "/user/lib.php");
423 $params = self
::validate_parameters(
424 self
::get_enrolled_users_parameters(),
426 'courseid'=>$courseid,
430 $withcapability = '';
433 $userfields = array();
437 $sortparams = array();
438 $sortdirection = 'ASC';
439 foreach ($options as $option) {
440 switch ($option['name']) {
441 case 'withcapability':
442 $withcapability = $option['value'];
445 $groupid = (int)$option['value'];
448 $onlyactive = !empty($option['value']);
451 $thefields = explode(',', $option['value']);
452 foreach ($thefields as $f) {
453 $userfields[] = clean_param($f, PARAM_ALPHANUMEXT
);
457 $limitfrom = clean_param($option['value'], PARAM_INT
);
460 $limitnumber = clean_param($option['value'], PARAM_INT
);
463 $sortallowedvalues = array('id', 'firstname', 'lastname', 'siteorder');
464 if (!in_array($option['value'], $sortallowedvalues)) {
465 throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $option['value'] . '),' .
466 'allowed values are: ' . implode(',', $sortallowedvalues));
468 if ($option['value'] == 'siteorder') {
469 list($sortby, $sortparams) = users_order_by_sql('us');
471 $sortby = 'us.' . $option['value'];
474 case 'sortdirection':
475 $sortdirection = strtoupper($option['value']);
476 $directionallowedvalues = array('ASC', 'DESC');
477 if (!in_array($sortdirection, $directionallowedvalues)) {
478 throw new invalid_parameter_exception('Invalid value for sortdirection parameter
479 (value: ' . $sortdirection . '),' . 'allowed values are: ' . implode(',', $directionallowedvalues));
485 $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST
);
486 $coursecontext = context_course
::instance($courseid, IGNORE_MISSING
);
487 if ($courseid == SITEID
) {
488 $context = context_system
::instance();
490 $context = $coursecontext;
493 self
::validate_context($context);
494 } catch (Exception
$e) {
495 $exceptionparam = new stdClass();
496 $exceptionparam->message
= $e->getMessage();
497 $exceptionparam->courseid
= $params['courseid'];
498 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
501 if ($courseid == SITEID
) {
502 require_capability('moodle/site:viewparticipants', $context);
504 require_capability('moodle/course:viewparticipants', $context);
506 // to overwrite this parameter, you need role:review capability
507 if ($withcapability) {
508 require_capability('moodle/role:review', $coursecontext);
510 // need accessallgroups capability if you want to overwrite this option
511 if (!empty($groupid) && !groups_is_member($groupid)) {
512 require_capability('moodle/site:accessallgroups', $coursecontext);
514 // to overwrite this option, you need course:enrolereview permission
516 require_capability('moodle/course:enrolreview', $coursecontext);
519 list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
520 $ctxselect = ', ' . context_helper
::get_preload_record_columns_sql('ctx');
521 $ctxjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)";
522 $enrolledparams['contextlevel'] = CONTEXT_USER
;
525 if (empty($groupid) && groups_get_course_groupmode($course) == SEPARATEGROUPS
&&
526 !has_capability('moodle/site:accessallgroups', $coursecontext)) {
527 // Filter by groups the user can view.
528 $usergroups = groups_get_user_groups($course->id
);
529 if (!empty($usergroups['0'])) {
530 list($groupsql, $groupparams) = $DB->get_in_or_equal($usergroups['0'], SQL_PARAMS_NAMED
);
531 $groupjoin = "JOIN {groups_members} gm ON (u.id = gm.userid AND gm.groupid $groupsql)";
532 $enrolledparams = array_merge($enrolledparams, $groupparams);
534 // User doesn't belong to any group, so he can't see any user. Return an empty array.
541 SELECT DISTINCT u.id $ctxselect
542 FROM {user} u $ctxjoin $groupjoin
543 WHERE u.id IN ($enrolledsql)
545 ORDER BY $sortby $sortdirection";
546 $enrolledparams = array_merge($enrolledparams, $sortparams);
547 $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams, $limitfrom, $limitnumber);
549 foreach ($enrolledusers as $user) {
550 context_helper
::preload_from_record($user);
551 if ($userdetails = user_get_user_details($user, $course, $userfields)) {
552 $users[] = $userdetails;
555 $enrolledusers->close();
561 * Returns description of method result value
563 * @return external_description
565 public static function get_enrolled_users_returns() {
566 return new external_multiple_structure(
567 new external_single_structure(
569 'id' => new external_value(PARAM_INT
, 'ID of the user'),
570 'username' => new external_value(PARAM_RAW
, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL
),
571 'firstname' => new external_value(PARAM_NOTAGS
, 'The first name(s) of the user', VALUE_OPTIONAL
),
572 'lastname' => new external_value(PARAM_NOTAGS
, 'The family name of the user', VALUE_OPTIONAL
),
573 'fullname' => new external_value(PARAM_NOTAGS
, 'The fullname of the user'),
574 'email' => new external_value(PARAM_TEXT
, 'An email address - allow email as root@localhost', VALUE_OPTIONAL
),
575 'address' => new external_value(PARAM_TEXT
, 'Postal address', VALUE_OPTIONAL
),
576 'phone1' => new external_value(PARAM_NOTAGS
, 'Phone 1', VALUE_OPTIONAL
),
577 'phone2' => new external_value(PARAM_NOTAGS
, 'Phone 2', VALUE_OPTIONAL
),
578 'icq' => new external_value(PARAM_NOTAGS
, 'icq number', VALUE_OPTIONAL
),
579 'skype' => new external_value(PARAM_NOTAGS
, 'skype id', VALUE_OPTIONAL
),
580 'yahoo' => new external_value(PARAM_NOTAGS
, 'yahoo id', VALUE_OPTIONAL
),
581 'aim' => new external_value(PARAM_NOTAGS
, 'aim id', VALUE_OPTIONAL
),
582 'msn' => new external_value(PARAM_NOTAGS
, 'msn number', VALUE_OPTIONAL
),
583 'department' => new external_value(PARAM_TEXT
, 'department', VALUE_OPTIONAL
),
584 'institution' => new external_value(PARAM_TEXT
, 'institution', VALUE_OPTIONAL
),
585 'idnumber' => new external_value(PARAM_RAW
, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL
),
586 'interests' => new external_value(PARAM_TEXT
, 'user interests (separated by commas)', VALUE_OPTIONAL
),
587 'firstaccess' => new external_value(PARAM_INT
, 'first access to the site (0 if never)', VALUE_OPTIONAL
),
588 'lastaccess' => new external_value(PARAM_INT
, 'last access to the site (0 if never)', VALUE_OPTIONAL
),
589 'description' => new external_value(PARAM_RAW
, 'User profile description', VALUE_OPTIONAL
),
590 'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL
),
591 'city' => new external_value(PARAM_NOTAGS
, 'Home city of the user', VALUE_OPTIONAL
),
592 'url' => new external_value(PARAM_URL
, 'URL of the user', VALUE_OPTIONAL
),
593 'country' => new external_value(PARAM_ALPHA
, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL
),
594 'profileimageurlsmall' => new external_value(PARAM_URL
, 'User image profile URL - small version', VALUE_OPTIONAL
),
595 'profileimageurl' => new external_value(PARAM_URL
, 'User image profile URL - big version', VALUE_OPTIONAL
),
596 'customfields' => new external_multiple_structure(
597 new external_single_structure(
599 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The type of the custom field - text field, checkbox...'),
600 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
601 'name' => new external_value(PARAM_RAW
, 'The name of the custom field'),
602 'shortname' => new external_value(PARAM_RAW
, 'The shortname of the custom field - to be able to build the field class in the code'),
604 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL
),
605 'groups' => new external_multiple_structure(
606 new external_single_structure(
608 'id' => new external_value(PARAM_INT
, 'group id'),
609 'name' => new external_value(PARAM_RAW
, 'group name'),
610 'description' => new external_value(PARAM_RAW
, 'group description'),
611 'descriptionformat' => new external_format_value('description'),
613 ), 'user groups', VALUE_OPTIONAL
),
614 'roles' => new external_multiple_structure(
615 new external_single_structure(
617 'roleid' => new external_value(PARAM_INT
, 'role id'),
618 'name' => new external_value(PARAM_RAW
, 'role name'),
619 'shortname' => new external_value(PARAM_ALPHANUMEXT
, 'role shortname'),
620 'sortorder' => new external_value(PARAM_INT
, 'role sortorder')
622 ), 'user roles', VALUE_OPTIONAL
),
623 'preferences' => new external_multiple_structure(
624 new external_single_structure(
626 'name' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the preferences'),
627 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
629 ), 'User preferences', VALUE_OPTIONAL
),
630 'enrolledcourses' => new external_multiple_structure(
631 new external_single_structure(
633 'id' => new external_value(PARAM_INT
, 'Id of the course'),
634 'fullname' => new external_value(PARAM_RAW
, 'Fullname of the course'),
635 'shortname' => new external_value(PARAM_RAW
, 'Shortname of the course')
637 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL
)
644 * Returns description of get_course_enrolment_methods() parameters
646 * @return external_function_parameters
648 public static function get_course_enrolment_methods_parameters() {
649 return new external_function_parameters(
651 'courseid' => new external_value(PARAM_INT
, 'Course id')
657 * Get list of active course enrolment methods for current user.
659 * @param int $courseid
660 * @return array of course enrolment methods
661 * @throws moodle_exception
663 public static function get_course_enrolment_methods($courseid) {
666 $params = self
::validate_parameters(self
::get_course_enrolment_methods_parameters(), array('courseid' => $courseid));
667 self
::validate_context(context_system
::instance());
669 $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST
);
670 $context = context_course
::instance($course->id
);
671 if (!$course->visible
and !has_capability('moodle/course:viewhiddencourses', $context)) {
672 throw new moodle_exception('coursehidden');
676 $enrolinstances = enrol_get_instances($params['courseid'], true);
677 foreach ($enrolinstances as $enrolinstance) {
678 if ($enrolplugin = enrol_get_plugin($enrolinstance->enrol
)) {
679 if ($instanceinfo = $enrolplugin->get_enrol_info($enrolinstance)) {
680 $result[] = (array) $instanceinfo;
688 * Returns description of get_course_enrolment_methods() result value
690 * @return external_description
692 public static function get_course_enrolment_methods_returns() {
693 return new external_multiple_structure(
694 new external_single_structure(
696 'id' => new external_value(PARAM_INT
, 'id of course enrolment instance'),
697 'courseid' => new external_value(PARAM_INT
, 'id of course'),
698 'type' => new external_value(PARAM_PLUGIN
, 'type of enrolment plugin'),
699 'name' => new external_value(PARAM_RAW
, 'name of enrolment plugin'),
700 'status' => new external_value(PARAM_RAW
, 'status of enrolment plugin'),
701 'wsfunction' => new external_value(PARAM_ALPHANUMEXT
, 'webservice function to get more information', VALUE_OPTIONAL
),
709 * Role external functions
713 * @copyright 2011 Jerome Mouneyrac
714 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
717 class core_role_external
extends external_api
{
720 * Returns description of method parameters
722 * @return external_function_parameters
724 public static function assign_roles_parameters() {
725 return new external_function_parameters(
727 'assignments' => new external_multiple_structure(
728 new external_single_structure(
730 'roleid' => new external_value(PARAM_INT
, 'Role to assign to the user'),
731 'userid' => new external_value(PARAM_INT
, 'The user that is going to be assigned'),
732 'contextid' => new external_value(PARAM_INT
, 'The context to assign the user role in', VALUE_OPTIONAL
),
733 'contextlevel' => new external_value(PARAM_ALPHA
, 'The context level to assign the user role in
734 (block, course, coursecat, system, user, module)', VALUE_OPTIONAL
),
735 'instanceid' => new external_value(PARAM_INT
, 'The Instance id of item where the role needs to be assigned', VALUE_OPTIONAL
),
744 * Manual role assignments to users
746 * @param array $assignments An array of manual role assignment
748 public static function assign_roles($assignments) {
751 // Do basic automatic PARAM checks on incoming data, using params description
752 // If any problems are found then exceptions are thrown with helpful error messages
753 $params = self
::validate_parameters(self
::assign_roles_parameters(), array('assignments'=>$assignments));
755 $transaction = $DB->start_delegated_transaction();
757 foreach ($params['assignments'] as $assignment) {
758 // Ensure correct context level with a instance id or contextid is passed.
759 $context = self
::get_context_from_params($assignment);
761 // Ensure the current user is allowed to run this function in the enrolment context.
762 self
::validate_context($context);
763 require_capability('moodle/role:assign', $context);
765 // throw an exception if user is not able to assign the role in this context
766 $roles = get_assignable_roles($context, ROLENAME_SHORT
);
768 if (!array_key_exists($assignment['roleid'], $roles)) {
769 throw new invalid_parameter_exception('Can not assign roleid='.$assignment['roleid'].' in contextid='.$assignment['contextid']);
772 role_assign($assignment['roleid'], $assignment['userid'], $context->id
);
775 $transaction->allow_commit();
779 * Returns description of method result value
783 public static function assign_roles_returns() {
789 * Returns description of method parameters
791 * @return external_function_parameters
793 public static function unassign_roles_parameters() {
794 return new external_function_parameters(
796 'unassignments' => new external_multiple_structure(
797 new external_single_structure(
799 'roleid' => new external_value(PARAM_INT
, 'Role to assign to the user'),
800 'userid' => new external_value(PARAM_INT
, 'The user that is going to be assigned'),
801 'contextid' => new external_value(PARAM_INT
, 'The context to unassign the user role from', VALUE_OPTIONAL
),
802 'contextlevel' => new external_value(PARAM_ALPHA
, 'The context level to unassign the user role in
803 + (block, course, coursecat, system, user, module)', VALUE_OPTIONAL
),
804 'instanceid' => new external_value(PARAM_INT
, 'The Instance id of item where the role needs to be unassigned', VALUE_OPTIONAL
),
813 * Unassign roles from users
815 * @param array $unassignments An array of unassignment
817 public static function unassign_roles($unassignments) {
820 // Do basic automatic PARAM checks on incoming data, using params description
821 // If any problems are found then exceptions are thrown with helpful error messages
822 $params = self
::validate_parameters(self
::unassign_roles_parameters(), array('unassignments'=>$unassignments));
824 $transaction = $DB->start_delegated_transaction();
826 foreach ($params['unassignments'] as $unassignment) {
827 // Ensure the current user is allowed to run this function in the unassignment context
828 $context = self
::get_context_from_params($unassignment);
829 self
::validate_context($context);
830 require_capability('moodle/role:assign', $context);
832 // throw an exception if user is not able to unassign the role in this context
833 $roles = get_assignable_roles($context, ROLENAME_SHORT
);
834 if (!array_key_exists($unassignment['roleid'], $roles)) {
835 throw new invalid_parameter_exception('Can not unassign roleid='.$unassignment['roleid'].' in contextid='.$unassignment['contextid']);
838 role_unassign($unassignment['roleid'], $unassignment['userid'], $context->id
);
841 $transaction->allow_commit();
845 * Returns description of method result value
849 public static function unassign_roles_returns() {