user/externallib.php

   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
  23  * @copyright  2009 Moodle Pty Ltd (http://moodle.com)
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 require_once("$CFG->libdir/externallib.php");
  28
  29 class moodle_user_external extends external_api {
  30
  31     /**
  32      * Returns description of method parameters
  33      * @return external_function_parameters
  34      */
  35     public static function create_users_parameters() {
  36         global $CFG;
  37
  38         return new external_function_parameters(
  39             array(
  40                 'users' => new external_multiple_structure(
  41                     new external_single_structure(
  42                         array(
  43                             'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
  44                             'password'    => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
  45                             'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
  46                             'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user'),
  47                             'email'       => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
  48                             'auth'        => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT, 'manual', NULL_NOT_ALLOWED),
  49                             'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT, ''),
  50                             'emailstop'   => new external_value(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', VALUE_DEFAULT, 0),
  51                             'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_DEFAULT, $CFG->lang, NULL_NOT_ALLOWED),
  52                             'theme'       => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
  53                             'timezone'    => new external_value(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
  54                             'mailformat'  => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
  55                             'description' => new external_value(PARAM_TEXT, 'User profile description, as HTML', VALUE_OPTIONAL),
  56                             'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
  57                             'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
  58                             'preferences' => new external_multiple_structure(
  59                                 new external_single_structure(
  60                                     array(
  61                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
  62                                         'value' => new external_value(PARAM_RAW, 'The value of the preference')
  63                                     )
  64                                 ), 'User preferences', VALUE_OPTIONAL),
  65                             'customfields' => new external_multiple_structure(
  66                                 new external_single_structure(
  67                                     array(
  68                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
  69                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
  70                                     )
  71                                 ), 'User custom fields', VALUE_OPTIONAL)
  72                         )
  73                     )
  74                 )
  75             )
  76         );
  77     }
  78
  79     /**
  80      * Create one or more users
  81      *
  82      * @param array $users  An array of users to create.
  83      * @return array An array of arrays
  84      */
  85     public static function create_users($users) {
  86         global $CFG, $DB;
  87         require_once($CFG->dirroot."/user/lib.php");
  88
  89         // Ensure the current user is allowed to run this function
  90         $context = get_context_instance(CONTEXT_SYSTEM);
  91         self::validate_context($context);
  92         require_capability('moodle/user:create', $context);
  93
  94         // Do basic automatic PARAM checks on incoming data, using params description
  95         // If any problems are found then exceptions are thrown with helpful error messages
  96         $params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));
  97
  98         $availableauths  = get_plugin_list('auth');
  99         unset($availableauths['mnet']);       // these would need mnethostid too
 100         unset($availableauths['webservice']); // we do not want new webservice users for now
 101
 102         $availablethemes = get_plugin_list('theme');
 103         $availablelangs  = get_string_manager()->get_list_of_translations();
 104
 105         $transaction = $DB->start_delegated_transaction();
 106
 107         $userids = array();
 108         foreach ($params['users'] as $user) {
 109             // Make sure that the username doesn't already exist
 110             if ($DB->record_exists('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id))) {
 111                 throw new invalid_parameter_exception('Username already exists: '.$user['username']);
 112             }
 113
 114             // Make sure auth is valid
 115             if (empty($availableauths[$user['auth']])) {
 116                 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
 117             }
 118
 119             // Make sure lang is valid
 120             if (empty($availablelangs[$user['lang']])) {
 121                 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
 122             }
 123
 124             // Make sure lang is valid
 125             if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { //theme is VALUE_OPTIONAL,
 126                                                                                      // so no default value.
 127                                                                                      // We need to test if the client sent it
 128                                                                                      // => !empty($user['theme'])
 129                 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
 130             }
 131
 132             // make sure there is no data loss during truncation
 133             $truncated = truncate_userinfo($user);
 134             foreach ($truncated as $key=>$value) {
 135                     if ($truncated[$key] !== $user[$key]) {
 136                         throw new invalid_parameter_exception('Property: '.$key.' is too long: '.$user[$key]);
 137                     }
 138             }
 139
 140             $user['confirmed'] = true;
 141             $newuserid = user_create_user($user);
 142
 143             //TODO: preferences and custom fields
 144
 145             $userids[] = array('id'=>$newuserid, 'username'=>$user['username']);
 146         }
 147
 148         $transaction->allow_commit();
 149
 150         return $userids;
 151     }
 152
 153    /**
 154      * Returns description of method result value
 155      * @return external_description
 156      */
 157     public static function create_users_returns() {
 158         return new external_multiple_structure(
 159             new external_single_structure(
 160                 array(
 161                     'id'       => new external_value(PARAM_INT, 'user id'),
 162                     'username' => new external_value(PARAM_RAW, 'user name'),
 163                 )
 164             )
 165         );
 166     }
 167
 168
 169     /**
 170      * Returns description of method parameters
 171      * @return external_function_parameters
 172      */
 173     public static function delete_users_parameters() {
 174         return new external_function_parameters(
 175             array(
 176                 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
 177             )
 178         );
 179     }
 180
 181     public static function delete_users($userids) {
 182         global $CFG, $DB;
 183         require_once($CFG->dirroot."/user/lib.php");
 184
 185         // Ensure the current user is allowed to run this function
 186         $context = get_context_instance(CONTEXT_SYSTEM);
 187         require_capability('moodle/user:delete', $context);
 188         self::validate_context($context);
 189
 190         $params = self::validate_parameters(self::delete_users_parameters(), array('userids'=>$userids));
 191
 192         $transaction = $DB->start_delegated_transaction();
 193         // TODO: this is problematic because the DB rollback does not handle rollbacking of deleted user images!
 194
 195         foreach ($params['userids'] as $userid) {
 196             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST);
 197             user_delete_user($user);
 198         }
 199
 200         $transaction->allow_commit();
 201
 202         return null;
 203     }
 204
 205    /**
 206      * Returns description of method result value
 207      * @return external_description
 208      */
 209     public static function delete_users_returns() {
 210         return null;
 211     }
 212
 213
 214     /**
 215      * Returns description of method parameters
 216      * @return external_function_parameters
 217      */
 218     public static function update_users_parameters() {
 219         global $CFG;
 220        return new external_function_parameters(
 221             array(
 222                 'users' => new external_multiple_structure(
 223                     new external_single_structure(
 224                         array(
 225                             'id'    => new external_value(PARAM_NUMBER, 'ID of the user'),
 226                             'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 227                             'password'    => new external_value(PARAM_RAW, 'Plain text password consisting of any characters', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 228                             'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 229                             'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 230                             'email'       => new external_value(PARAM_EMAIL, 'A valid and unique email address', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 231                             'auth'        => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 232                             'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 233                             'emailstop'   => new external_value(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', VALUE_OPTIONAL),
 234                             'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 235                             'theme'       => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
 236                             'timezone'    => new external_value(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
 237                             'mailformat'  => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
 238                             'description' => new external_value(PARAM_TEXT, 'User profile description, as HTML', VALUE_OPTIONAL),
 239                             'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 240                             'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 241                             'customfields' => new external_multiple_structure(
 242                                 new external_single_structure(
 243                                     array(
 244                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
 245                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
 246                                     )
 247                                 ), 'User custom fields', VALUE_OPTIONAL)
 248                         )
 249                     )
 250                 )
 251             )
 252         );
 253     }
 254
 255     public static function update_users($users) {
 256         global $CFG, $DB;
 257         require_once($CFG->dirroot."/user/lib.php");
 258         require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
 259                                                              //TODO: move the functions somewhere else as
 260                                                              //they are "user" related
 261
 262         // Ensure the current user is allowed to run this function
 263         $context = get_context_instance(CONTEXT_SYSTEM);
 264         require_capability('moodle/user:update', $context);
 265         self::validate_context($context);
 266
 267         $params = self::validate_parameters(self::update_users_parameters(), array('users'=>$users));
 268
 269         $transaction = $DB->start_delegated_transaction();
 270
 271         foreach ($params['users'] as $user) {
 272             user_update_user($user);
 273             //update user custom fields
 274             if(!empty($user['customfields'])) {
 275
 276                 foreach($user['customfields'] as $customfield) {
 277                     $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
 278                                                                                             //it's expecting a user with the correct id,
 279                                                                                             //and custom field to be named profile_field_"shortname"
 280                 }
 281                 profile_save_data((object) $user);
 282             }
 283         }
 284
 285
 286
 287
 288         $transaction->allow_commit();
 289
 290         return null;
 291     }
 292
 293    /**
 294      * Returns description of method result value
 295      * @return external_description
 296      */
 297     public static function update_users_returns() {
 298         return null;
 299     }
 300
 301     /**
 302      * Returns description of method parameters
 303      * @return external_function_parameters
 304      */
 305     public static function get_users_by_id_parameters() {
 306         return new external_function_parameters(
 307             array(
 308                 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
 309                  )
 310         );
 311     }
 312
 313
 314     /**
 315      * Get user information
 316      *
 317      * @param array $userids  array of user ids
 318      * @return array An array of arrays describing users
 319      */
 320     public static function get_users_by_id($userids) {
 321         global $CFG;
 322         require_once($CFG->dirroot."/user/lib.php");
 323         require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
 324                                                              //TODO: move the functions somewhere else as
 325                                                              //they are "user" related
 326
 327         $context = get_context_instance(CONTEXT_SYSTEM);
 328         require_capability('moodle/user:viewdetails', $context);
 329         self::validate_context($context);
 330
 331         $params = self::validate_parameters(self::get_users_by_id_parameters(), array('userids'=>$userids));
 332
 333         //TODO: check if there is any performance issue: we do one DB request to retrieve  all user,
 334         // then for each user the profile_load_data does at least two DB requests
 335
 336         $users = user_get_users_by_id($params['userids']);
 337         $result =array();
 338         foreach ($users as $user) {
 339             if (empty($user->deleted)) {
 340
 341                 $userarray = (array) $user; //we want to return an array not an object
 342                 /// now we transfert all profile_field_xxx into the customfields external_multiple_structure required by description
 343                 $userarray['customfields'] = null;
 344                 $customfields = profile_user_record($user->id);
 345                 $customfields = (array) $customfields;
 346                 foreach ($customfields as $key => $value) {
 347                     $userarray['customfields'][] = array('type' => $key, 'value' => $value);
 348                 }
 349
 350                 $result[] = $userarray;
 351             }
 352
 353         }
 354
 355         return $result;
 356     }
 357
 358    /**
 359      * Returns description of method result value
 360      * @return external_description
 361      */
 362     public static function get_users_by_id_returns() {
 363         return new external_multiple_structure(
 364             new external_single_structure(
 365                 array(
 366                     'id'    => new external_value(PARAM_NUMBER, 'ID of the user'),
 367                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
 368                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
 369                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user'),
 370                     'email'       => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
 371                     'auth'        => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc'),
 372                     'confirmed'   => new external_value(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise'),
 373                     'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution'),
 374                     'emailstop'   => new external_value(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise'),
 375                     'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server'),
 376                     'theme'       => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server'),
 377                     'timezone'    => new external_value(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default'),
 378                     'mailformat'  => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc'),
 379                     'description' => new external_value(PARAM_TEXT, 'User profile description, as HTML'),
 380                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user'),
 381                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ'),
 382                     'customfields' => new external_multiple_structure(
 383                         new external_single_structure(
 384                             array(
 385                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
 386                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field')
 387                             )
 388                         ), 'User custom fields')
 389                 )
 390             )
 391         );
 392     }
 393 }