<?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/>.
/**
* External user API
*
* @package moodlecore
* @subpackage webservice
* @copyright 2009 Moodle Pty Ltd (http://moodle.com)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once("$CFG->libdir/externallib.php");
class moodle_user_external extends external_api {
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function create_users_parameters() {
global $CFG;
return new external_function_parameters(
array(
'users' => new external_multiple_structure(
new external_single_structure(
array(
'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user'),
'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
'auth' => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT, 'manual', NULL_NOT_ALLOWED),
'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT, ''),
'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_DEFAULT, $CFG->lang, NULL_NOT_ALLOWED),
'theme' => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
'value' => new external_value(PARAM_RAW, 'The value of the preference')
)
), 'User preferences', VALUE_OPTIONAL),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL)
)
)
)
)
);
}
/**
* Create one or more users
*
* @param array $users An array of users to create.
* @return array An array of arrays
*/
public static function create_users($users) {
global $CFG, $DB;
require_once($CFG->dirroot."/user/lib.php");
require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
//TODO: move the functions somewhere else as
//they are "user" related
// Ensure the current user is allowed to run this function
$context = get_context_instance(CONTEXT_SYSTEM);
self::validate_context($context);
require_capability('moodle/user:create', $context);
// Do basic automatic PARAM checks on incoming data, using params description
// If any problems are found then exceptions are thrown with helpful error messages
$params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));
$availableauths = get_plugin_list('auth');
unset($availableauths['mnet']); // these would need mnethostid too
unset($availableauths['webservice']); // we do not want new webservice users for now
$availablethemes = get_plugin_list('theme');
$availablelangs = get_string_manager()->get_list_of_translations();
$transaction = $DB->start_delegated_transaction();
$userids = array();
foreach ($params['users'] as $user) {
// Make sure that the username doesn't already exist
if ($DB->record_exists('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id))) {
throw new invalid_parameter_exception('Username already exists: '.$user['username']);
}
// Make sure auth is valid
if (empty($availableauths[$user['auth']])) {
throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
}
// Make sure lang is valid
if (empty($availablelangs[$user['lang']])) {
throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
}
// Make sure lang is valid
if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { //theme is VALUE_OPTIONAL,
// so no default value.
// We need to test if the client sent it
// => !empty($user['theme'])
throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
}
// make sure there is no data loss during truncation
$truncated = truncate_userinfo($user);
foreach ($truncated as $key=>$value) {
if ($truncated[$key] !== $user[$key]) {
throw new invalid_parameter_exception('Property: '.$key.' is too long: '.$user[$key]);
}
}
$user['confirmed'] = true;
$user['mnethostid'] = $CFG->mnet_localhost_id;
$user['id'] = user_create_user($user);
// custom fields
if(!empty($user['customfields'])) {
foreach($user['customfields'] as $customfield) {
$user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
//it's expecting a user with the correct id,
//and custom field to be named profile_field_"shortname"
}
profile_save_data((object) $user);
}
//preferences
if (!empty($user['preferences'])) {
foreach($user['preferences'] as $preference) {
set_user_preference($preference['type'], $preference['value'],$user['id']);
}
}
$userids[] = array('id'=>$user['id'], 'username'=>$user['username']);
}
$transaction->allow_commit();
return $userids;
}
/**
* Returns description of method result value
* @return external_description
*/
public static function create_users_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'user id'),
'username' => new external_value(PARAM_RAW, 'user name'),
)
)
);
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function delete_users_parameters() {
return new external_function_parameters(
array(
'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
)
);
}
public static function delete_users($userids) {
global $CFG, $DB, $USER;
require_once($CFG->dirroot."/user/lib.php");
// Ensure the current user is allowed to run this function
$context = get_context_instance(CONTEXT_SYSTEM);
require_capability('moodle/user:delete', $context);
self::validate_context($context);
$params = self::validate_parameters(self::delete_users_parameters(), array('userids'=>$userids));
$transaction = $DB->start_delegated_transaction();
foreach ($params['userids'] as $userid) {
$user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST);
// must not allow deleting of admins or self!!!
if (is_siteadmin($user)) {
throw new moodle_exception('useradminodelete', 'error');
}
if ($USER->id == $user->id) {
throw new moodle_exception('usernotdeletederror', 'error');
}
user_delete_user($user);
}
$transaction->allow_commit();
return null;
}
/**
* Returns description of method result value
* @return external_description
*/
public static function delete_users_returns() {
return null;
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function update_users_parameters() {
global $CFG;
return new external_function_parameters(
array(
'users' => new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_NUMBER, 'ID of the user'),
'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
'auth' => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
'theme' => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
'value' => new external_value(PARAM_RAW, 'The value of the preference')
)
), 'User preferences', VALUE_OPTIONAL),
)
)
)
)
);
}
public static function update_users($users) {
global $CFG, $DB;
require_once($CFG->dirroot."/user/lib.php");
require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
//TODO: move the functions somewhere else as
//they are "user" related
// Ensure the current user is allowed to run this function
$context = get_context_instance(CONTEXT_SYSTEM);
require_capability('moodle/user:update', $context);
self::validate_context($context);
$params = self::validate_parameters(self::update_users_parameters(), array('users'=>$users));
$transaction = $DB->start_delegated_transaction();
foreach ($params['users'] as $user) {
user_update_user($user);
//update user custom fields
if(!empty($user['customfields'])) {
foreach($user['customfields'] as $customfield) {
$user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
//it's expecting a user with the correct id,
//and custom field to be named profile_field_"shortname"
}
profile_save_data((object) $user);
}
//preferences
if (!empty($user['preferences'])) {
foreach($user['preferences'] as $preference) {
set_user_preference($preference['type'], $preference['value'],$user['id']);
}
}
}
$transaction->allow_commit();
return null;
}
/**
* Returns description of method result value
* @return external_description
*/
public static function update_users_returns() {
return null;
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function get_users_by_id_parameters() {
return new external_function_parameters(
array(
'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
)
);
}
/**
* Get user information
* - This function is matching the permissions of /user/profil.php
* - It is also matching some permissions from /user/editadvanced.php for the following fields:
* auth, confirmed, idnumber, lang, theme, timezone, mailformat
* @param array $userids array of user ids
* @return array An array of arrays describing users
*/
public static function get_users_by_id($userids) {
global $CFG, $USER, $DB;
require_once($CFG->dirroot . "/user/lib.php");
$params = self::validate_parameters(self::get_users_by_id_parameters(),
array('userids'=>$userids));
list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
list($sqluserids, $params) = $DB->get_in_or_equal($userids);
$usersql = "SELECT u.* $uselect
FROM {user} u $ujoin
WHERE u.id $sqluserids";
$users = $DB->get_recordset_sql($usersql, $params);
$result = array();
$hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
foreach ($users as $user) {
if (!empty($user->deleted)) {
continue;
}
context_instance_preload($user);
$usercontext = get_context_instance(CONTEXT_USER, $user->id);
self::validate_context($usercontext);
$currentuser = ($user->id == $USER->id);
if ($userarray = user_get_user_details($user)) {
//fields matching permissions from /user/editadvanced.php
if ($currentuser or $hasuserupdatecap) {
$userarray['auth'] = $user->auth;
$userarray['confirmed'] = $user->confirmed;
$userarray['idnumber'] = $user->idnumber;
$userarray['lang'] = $user->lang;
$userarray['theme'] = $user->theme;
$userarray['timezone'] = $user->timezone;
$userarray['mailformat'] = $user->mailformat;
}
$result[] = $userarray;
}
}
$users->close();
return $result;
}
/**
* Returns description of method result value
* @return external_description
*/
public static function get_users_by_id_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_NUMBER, 'ID of the user'),
'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
'address' => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
'auth' => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
'confirmed' => new external_value(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
'theme' => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
)
), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
)
), 'User preferences', VALUE_OPTIONAL),
'enrolledcourses' => new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'Id of the course'),
'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
)
), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
)
)
);
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function get_course_participants_by_id_parameters() {
return new external_function_parameters(
array(
'userlist' => new external_multiple_structure(
new external_single_structure(
array(
'userid' => new external_value(PARAM_INT, 'userid'),
'courseid' => new external_value(PARAM_INT, 'courseid'),
)
)
)
)
);
}
/**
* Get course participant's details
* @param array $userlist array of user ids and according course ids
* @return array An array of arrays describing course participants
*/
public static function get_course_participants_by_id($userlist) {
global $CFG, $USER, $DB;
require_once($CFG->dirroot . "/user/lib.php");
$params = self::validate_parameters(self::get_course_participants_by_id_parameters(), array('userlist'=>$userlist));
$userids = array();
$courseids = array();
foreach ($params['userlist'] as $value) {
$userids[] = $value['userid'];
$courseids[$value['userid']] = $value['courseid'];
}
// cache all courses
$courses = array();
list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
$coursesql = "SELECT c.* $uselect
FROM {course} c $cjoin
WHERE c.id $sqlcourseids";
$rs = $DB->get_recordset_sql($coursesql, $params);
foreach ($rs as $course) {
// adding course contexts to cache
context_instance_preload($course);
// cache courses
$courses[$course->id] = $course;
}
$rs->close();
list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
list($sqluserids, $params) = $DB->get_in_or_equal($userids);
$usersql = "SELECT u.* $uselect
FROM {user} u $ujoin
WHERE u.id $sqluserids";
$users = $DB->get_recordset_sql($usersql, $params);
$result = array();
foreach ($users as $user) {
if (!empty($user->deleted)) {
continue;
}
context_instance_preload($user);
$course = $courses[$courseids[$user->id]];
$context = get_context_instance(CONTEXT_COURSE, $courseids[$user->id]);
self::validate_context($context);
if ($userarray = user_get_user_details($user, $course)) {
$result[] = $userarray;
}
}
$users->close();
return $result;
}
/**
* Returns description of method result value
* @return external_description
*/
public static function get_course_participants_by_id_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_NUMBER, 'ID of the user'),
'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
'address' => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
)
), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'group id'),
'name' => new external_value(PARAM_RAW, 'group name'),
'description' => new external_value(PARAM_RAW, 'group description'),
)
), 'user groups', VALUE_OPTIONAL),
'roles' => new external_multiple_structure(
new external_single_structure(
array(
'roleid' => new external_value(PARAM_INT, 'role id'),
'name' => new external_value(PARAM_RAW, 'role name'),
'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
'sortorder' => new external_value(PARAM_INT, 'role sortorder')
)
), 'user roles', VALUE_OPTIONAL),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
)
), 'User preferences', VALUE_OPTIONAL),
'enrolledcourses' => new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'Id of the course'),
'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
)
), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
)
)
);
}
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function get_users_by_courseid_parameters() {
return new external_function_parameters(
array(
'courseid' => new external_value(PARAM_INT, 'course id'),
'options' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_ALPHANUMEXT, 'option name'),
'value' => new external_value(PARAM_RAW, 'option value')
)
), 'method options'),
)
);
}
/**
* Get course participants details
* @param int $courseid course id
* @param array $options options {
* 'name' => option name
* 'value' => option value
* }
* @return array An array of users
*/
public static function get_users_by_courseid($courseid, $options) {
global $CFG, $USER, $DB;
require_once($CFG->dirroot . "/user/lib.php");
$params = self::validate_parameters(
self::get_users_by_courseid_parameters(),
array(
'courseid'=>$courseid,
'options'=>$options
)
);
$withcapability = '';
$groupid = 0;
$onlyactive = false;
foreach ($options as $option) {
switch ($option['name']) {
case 'withcapability':
$withcapability = $option['value'];
break;
case 'groupid':
$groupid = (int)$option['value'];
break;
case 'onlyactive':
$onlyactive = !empty($option['value']);
break;
}
}
// to overwrite this parameter, you need role:review capability
if ($withcapability) {
require_capability('moodle/role:review', $coursecontext);
}
// need accessallgroups capability if you want to overwrite this option
if (!empty($groupid) && groups_is_member($groupid)) {
require_capability('moodle/site:accessallgroups', $context);
}
// to overwrite this option, you need course:enrolereview permission
if ($onlyactive) {
require_capability('moodle/course:enrolreview', $coursecontext);
}
list($coursectxselect, $coursectxjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
$coursesql = "SELECT c.* $coursectxselect
FROM {course} c $coursectxjoin
WHERE c.id = $courseid";
$course = $DB->get_record_sql($coursesql);
context_instance_preload($course);
$coursecontext = get_context_instance(CONTEXT_COURSE, $params['courseid']);
if ($courseid == SITEID) {
$context = get_system_context();
} else {
$context = $coursecontext;
}
try {
self::validate_context($context);
} catch (Exception $e) {
$exceptionparam = new stdClass();
$exceptionparam->message = $e->getMessage();
$exceptionparam->courseid = $params['courseid'];
throw new moodle_exception(get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
}
list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
list($ctxselect, $ctxjoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
$records = $DB->get_records_sql($enrolledsql, $enrolledparams);
$sqlparams['courseid'] = $courseid;
$sql = "SELECT u.* $ctxselect
FROM {user} u $ctxjoin
WHERE u.id IN ($enrolledsql)
ORDER BY u.id ASC";
$enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams);
$users = array();
foreach ($enrolledusers as $user) {
if (!empty($user->deleted)) {
continue;
}
context_instance_preload($user);
if ($userdetails = user_get_user_details($user, $course)) {
$users[] = $userdetails;
}
}
$enrolledusers->close();
return $users;
}
/**
* Returns description of method result value
* @return external_description
*/
public static function get_users_by_courseid_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_NUMBER, 'ID of the user'),
'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
'address' => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
)
), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'group id'),
'name' => new external_value(PARAM_RAW, 'group name'),
'description' => new external_value(PARAM_RAW, 'group description'),
)
), 'user groups', VALUE_OPTIONAL),
'roles' => new external_multiple_structure(
new external_single_structure(
array(
'roleid' => new external_value(PARAM_INT, 'role id'),
'name' => new external_value(PARAM_RAW, 'role name'),
'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
'sortorder' => new external_value(PARAM_INT, 'role sortorder')
)
), 'user roles', VALUE_OPTIONAL),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
)
), 'User preferences', VALUE_OPTIONAL),
'enrolledcourses' => new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'Id of the course'),
'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
)
), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
)
)
);
}
}