en_utf8 MDL-19468 Copied auth_* language strings back into auth.php to maintain backw...
[moodle.git] / user / externallib.php
CommitLineData
ef22c1b6 1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * External user API
20 *
21 * @package moodlecore
22 * @subpackage webservice
551f4420 23 * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
ef22c1b6 24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27require_once("$CFG->libdir/externallib.php");
28
29class moodle_user_external extends external_api {
30
d4e13355 31 public static function create_users_parameters() {
32
33//TODO: the format of the description is not decided yet
34
625f0a24 35 $userpreference = array();
36 $userpreference->name = array(PARAM_ALPHANUMEXT, 'The name of the preference to set');
37 $userpreference->value = array(PARAM_RAW, 'The value of the preference');
d4e13355 38
625f0a24 39 $usercustomfields = new object();
40 $usercustomfields->name = array(PARAM_ALPHANUMEXT, 'The name of the custom field (must exist)');
41 $usercustomfields->value = array(PARAM_RAW, 'The value of the custom field');
d4e13355 42
43 $usertocreate = new object();
625f0a24 44 $usertocreate->username = array(PARAM_USERNAME, 'Username policy is defined in Moodle security config', REQUIRED);
45 $usertocreate->password = array(PARAM_RAW, 'Moodle passwords can consist of any character', REQUIRED);
46 $usertocreate->firstname = array(PARAM_NOTAGS, 'The first name(s) of the user', REQUIRED);
47 $usertocreate->lastname = array(PARAM_NOTAGS, 'The family name of the user', REQUIRED);
48 $usertocreate->email = array(PARAM_EMAIL, 'A valid and unique email address', REQUIRED);
49 $usertocreate->auth = array(PARAM_AUTH, 'Auth plugins include manual, ldap, imap, etc');
50 $usertocreate->confirmed = array(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise');
51 $usertocreate->idnumber = array(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution');
52 $usertocreate->emailstop = array(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise');
53 $usertocreate->lang = array(PARAM_LANG, 'Language code such as "en_utf8", must exist on server');
54 $usertocreate->theme = array(PARAM_THEME, 'Theme name such as "standard", must exist on server');
55 $usertocreate->timezone = array(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default');
56 $usertocreate->mailformat = array(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc');
57 $usertocreate->description = array(PARAM_TEXT, 'User profile description, as HTML');
58 $usertocreate->city = array(PARAM_NOTAGS, 'Home city of the user');
59 $usertocreate->country = array(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ');
60 $usertocreate->preferences = array('multiple' => $userpreference);
61 $usertocreate->custom = array('multiple' => $usercustomfields);
d4e13355 62
625f0a24 63 $createusersparams = new object();
64 $createusersparams->users = array('multiple' => $usertocreate);
65
66 return $createusersparams;
67 }
68
d4e13355 69 /**
5de592b1 70 * Create one or more users
71 *
72 * @param $params An array of users to create. Each user is defined by $usertocreate above.
d4e13355 73 *
5de592b1 74 * @return $return An array of userids, one for each user that was created
75 */
ef22c1b6 76 public static function create_users($params) {
77 global $CFG, $DB;
78
5de592b1 79 // Ensure the current user is allowed to run this function
ef22c1b6 80 $context = get_context_instance(CONTEXT_SYSTEM);
5de592b1 81 require_capability('moodle/user:create', $context);
ef22c1b6 82 self::validate_context($context);
83
5de592b1 84 // Do basic automatic PARAM checks on incoming data, using params description
85 // This checks to make sure that:
86 // 1) No extra data was sent
d4e13355 87 // 2) All required items were sent
5de592b1 88 // 3) All data passes clean_param without changes (yes this is strict)
89 // If any problems are found then exceptions are thrown with helpful error messages
c9c5cc81 90 $params = self::validate_parameters(self::create_users_parameters(), $params);
5de592b1 91
92
93 // Perform further checks and build up a clean array of user data
94 // Nothing is actually performed until the whole dataset is checked
ef22c1b6 95 $users = array();
d4e13355 96 foreach ($params['users'] as $user) {
5de592b1 97
98 // Empty or no auth is assumed to be manual
d4e13355 99 if (empty($user['auth'])) {
ef22c1b6 100 $user['auth'] = 'manual';
101 }
ef22c1b6 102
5de592b1 103 // Lang must be a real code, not empty string
104 if (isset($user['lang']) && empty($user['lang'])) {
ef22c1b6 105 unset($user['lang']);
106 }
107
5de592b1 108 // Make sure that the username doesn't already exist
ef22c1b6 109 if ($DB->get_record('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id))) {
110 throw new invalid_parameter_exception($user['username']." username is already taken, sorry");
111 }
112
5de592b1 113 // Make sure that incoming data doesn't contain duplicate usernames
ef22c1b6 114 if (isset($users[$user['username']])) {
115 throw new invalid_parameter_exception("multiple users with the same username requested");
116 }
5de592b1 117
118 // TODO: More checks here?
119
120 $users[$user['username']] = $user; // Add this data to an array (mem overflows?)
ef22c1b6 121 }
122
123 $result = array();
124
5de592b1 125 foreach ($users as $user) { // Actually create the user accounts now
ef22c1b6 126 $record = create_user_record($user['username'], $user['password'], $user['auth']);
127 unset($user['username']);
128 unset($user['password']);
129 unset($user['auth']);
130
131 // now override the default (or external) values
132 foreach ($user as $key=>$value) {
133 $record->$key = $value;
134 }
135 $DB->update_record('user', $record);
136
d4e13355 137 //TODO: preferences and custom fields
138
5de592b1 139 $result[] = $record->id;
140
141 // TODO: Save all the preferences and custom fields here
142
ef22c1b6 143 }
144
145 return $result;
146 }
d4e13355 147 public static function create_users_returns() {
ef22c1b6 148
d4e13355 149//TODO: the format of the description is not decided yet
ef22c1b6 150
d4e13355 151 $createusersreturn = new object();
152 $createusersreturn->userids = array('multiple' => PARAM_NUMBER);
153
154 return $createusersreturn;
155 }
156
157
158 public static function delete_users_parameters() {
159 //TODO
160 }
ef22c1b6 161 public static function delete_users($params) {
162 //TODO
163 }
d4e13355 164 public static function delete_users_returns() {
165 //TODO
166 }
ef22c1b6 167
168
d4e13355 169 public static function update_users_parameters() {
170 //TODO
171 }
ef22c1b6 172 public static function update_users($params) {
173 //TODO
174 }
d4e13355 175 public static function update_users_returns() {
176 //TODO
177 }
178
179 public static function get_users_parameters() {
5de592b1 180
d4e13355 181 }
5de592b1 182 public static function get_users($params) {
183 $context = get_context_instance(CONTEXT_SYSTEM);
184 require_capability('moodle/user:viewdetails', $context);
185 self::validate_context($context);
186
c9c5cc81 187 $params = self::validate_parameters(self::get_users_parameters(), $params);
5de592b1 188
189 //TODO: this search is probably useless for external systems because it is not exact
190 // 1/ we should specify multiple search parameters including the mnet host id
d4e13355 191 // 2/ custom profile fileds not included
192
193 $result = array();
194
195 $users = get_users(true, $params['search'], false, null, 'firstname ASC','', '', '', 1000, 'id, mnethostid, auth, confirmed, username, idnumber, firstname, lastname, email, emailstop, lang, theme, timezone, mailformat, city, description, country');
196 foreach ($users as $user) {
197 $result[] = (array)$user;
198 }
199 }
200 public static function get_users_returns() {
5de592b1 201
5de592b1 202 }
203
204}