auth/email/classes/external.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Auth e-mail external API
  19  *
  20  * @package    auth_email
  21  * @category   external
  22  * @copyright  2016 Juan Leyva <juan@moodle.com>
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  * @since      Moodle 3.2
  25  */
  26
  27 defined('MOODLE_INTERNAL') || die;
  28
  29 require_once($CFG->libdir . '/externallib.php');
  30 require_once($CFG->libdir . '/authlib.php');
  31 require_once($CFG->dirroot . '/user/editlib.php');
  32 require_once($CFG->dirroot . '/user/profile/lib.php');
  33
  34 /**
  35  * Auth e-mail external functions
  36  *
  37  * @package    auth_email
  38  * @category   external
  39  * @copyright  2016 Juan Leyva <juan@moodle.com>
  40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41  * @since      Moodle 3.2
  42  */
  43 class auth_email_external extends external_api {
  44
  45     /**
  46      * Check if registration is enabled in this site.
  47      *
  48      * @throws moodle_exception
  49      * @since Moodle 3.2
  50      */
  51     protected static function check_signup_enabled() {
  52         global $CFG;
  53
  54         if (empty($CFG->registerauth) or $CFG->registerauth != 'email') {
  55             throw new moodle_exception('registrationdisabled', 'error');
  56         }
  57     }
  58
  59     /**
  60      * Describes the parameters for get_signup_settings.
  61      *
  62      * @return external_function_parameters
  63      * @since Moodle 3.2
  64      */
  65     public static function get_signup_settings_parameters() {
  66         return new external_function_parameters(array());
  67     }
  68
  69     /**
  70      * Get the signup required settings and profile fields.
  71      *
  72      * @return array settings and possible warnings
  73      * @since Moodle 3.2
  74      * @throws moodle_exception
  75      */
  76     public static function get_signup_settings() {
  77         global $CFG, $PAGE;
  78
  79         $context = context_system::instance();
  80         // We need this to make work the format text functions.
  81         $PAGE->set_context($context);
  82
  83         self::check_signup_enabled();
  84
  85         $result = array();
  86         $result['namefields'] = useredit_get_required_name_fields();
  87
  88         if (!empty($CFG->passwordpolicy)) {
  89             $result['passwordpolicy'] = print_password_policy();
  90         }
  91         $manager = new \core_privacy\local\sitepolicy\manager();
  92         if ($sitepolicy = $manager->get_embed_url()) {
  93             $result['sitepolicy'] = $sitepolicy->out(false);
  94         }
  95         if (!empty($CFG->sitepolicyhandler)) {
  96             $result['sitepolicyhandler'] = $CFG->sitepolicyhandler;
  97         }
  98         if (!empty($CFG->defaultcity)) {
  99             $result['defaultcity'] = $CFG->defaultcity;
 100         }
 101         if (!empty($CFG->country)) {
 102             $result['country'] = $CFG->country;
 103         }
 104
 105         if ($fields = profile_get_signup_fields()) {
 106             $result['profilefields'] = array();
 107             foreach ($fields as $field) {
 108                 $fielddata = $field->object->get_field_config_for_external();
 109                 $fielddata['categoryname'] = external_format_string($field->categoryname, $context->id);
 110                 $fielddata['name'] = external_format_string($fielddata['name'], $context->id);
 111                 list($fielddata['defaultdata'], $fielddata['defaultdataformat']) =
 112                     external_format_text($fielddata['defaultdata'], $fielddata['defaultdataformat'], $context->id);
 113
 114                 $result['profilefields'][] = $fielddata;
 115             }
 116         }
 117
 118         if (signup_captcha_enabled()) {
 119             // With reCAPTCHA v2 the captcha will be rendered by the mobile client using just the publickey.
 120             $result['recaptchapublickey'] = $CFG->recaptchapublickey;
 121         }
 122
 123         $result['warnings'] = array();
 124         return $result;
 125     }
 126
 127     /**
 128      * Describes the get_signup_settings return value.
 129      *
 130      * @return external_single_structure
 131      * @since Moodle 3.2
 132      */
 133     public static function get_signup_settings_returns() {
 134
 135         return new external_single_structure(
 136             array(
 137                 'namefields' => new external_multiple_structure(
 138                      new external_value(PARAM_NOTAGS, 'The order of the name fields')
 139                 ),
 140                 'passwordpolicy' => new external_value(PARAM_RAW, 'Password policy', VALUE_OPTIONAL),
 141                 'sitepolicy' => new external_value(PARAM_RAW, 'Site policy', VALUE_OPTIONAL),
 142                 'sitepolicyhandler' => new external_value(PARAM_PLUGIN, 'Site policy handler', VALUE_OPTIONAL),
 143                 'defaultcity' => new external_value(PARAM_NOTAGS, 'Default city', VALUE_OPTIONAL),
 144                 'country' => new external_value(PARAM_ALPHA, 'Default country', VALUE_OPTIONAL),
 145                 'profilefields' => new external_multiple_structure(
 146                     new external_single_structure(
 147                         array(
 148                             'id' => new external_value(PARAM_INT, 'Profile field id', VALUE_OPTIONAL),
 149                             'shortname' => new external_value(PARAM_ALPHANUMEXT, 'Profile field shortname', VALUE_OPTIONAL),
 150                             'name' => new external_value(PARAM_TEXT, 'Profield field name', VALUE_OPTIONAL),
 151                             'datatype' => new external_value(PARAM_ALPHANUMEXT, 'Profield field datatype', VALUE_OPTIONAL),
 152                             'description' => new external_value(PARAM_RAW, 'Profield field description', VALUE_OPTIONAL),
 153                             'descriptionformat' => new external_format_value('description'),
 154                             'categoryid' => new external_value(PARAM_INT, 'Profield field category id', VALUE_OPTIONAL),
 155                             'categoryname' => new external_value(PARAM_TEXT, 'Profield field category name', VALUE_OPTIONAL),
 156                             'sortorder' => new external_value(PARAM_INT, 'Profield field sort order', VALUE_OPTIONAL),
 157                             'required' => new external_value(PARAM_INT, 'Profield field required', VALUE_OPTIONAL),
 158                             'locked' => new external_value(PARAM_INT, 'Profield field locked', VALUE_OPTIONAL),
 159                             'visible' => new external_value(PARAM_INT, 'Profield field visible', VALUE_OPTIONAL),
 160                             'forceunique' => new external_value(PARAM_INT, 'Profield field unique', VALUE_OPTIONAL),
 161                             'signup' => new external_value(PARAM_INT, 'Profield field in signup form', VALUE_OPTIONAL),
 162                             'defaultdata' => new external_value(PARAM_RAW, 'Profield field default data', VALUE_OPTIONAL),
 163                             'defaultdataformat' => new external_format_value('defaultdata'),
 164                             'param1' => new external_value(PARAM_RAW, 'Profield field settings', VALUE_OPTIONAL),
 165                             'param2' => new external_value(PARAM_RAW, 'Profield field settings', VALUE_OPTIONAL),
 166                             'param3' => new external_value(PARAM_RAW, 'Profield field settings', VALUE_OPTIONAL),
 167                             'param4' => new external_value(PARAM_RAW, 'Profield field settings', VALUE_OPTIONAL),
 168                             'param5' => new external_value(PARAM_RAW, 'Profield field settings', VALUE_OPTIONAL),
 169                         )
 170                     ), 'Required profile fields', VALUE_OPTIONAL
 171                 ),
 172                 'recaptchapublickey' => new external_value(PARAM_RAW, 'Recaptcha public key', VALUE_OPTIONAL),
 173                 'recaptchachallengehash' => new external_value(PARAM_RAW, 'Recaptcha challenge hash', VALUE_OPTIONAL),
 174                 'recaptchachallengeimage' => new external_value(PARAM_URL, 'Recaptcha challenge noscript image', VALUE_OPTIONAL),
 175                 'recaptchachallengejs' => new external_value(PARAM_URL, 'Recaptcha challenge js url', VALUE_OPTIONAL),
 176                 'warnings'  => new external_warnings(),
 177             )
 178         );
 179     }
 180
 181     /**
 182      * Describes the parameters for signup_user.
 183      *
 184      * @return external_function_parameters
 185      * @since Moodle 3.2
 186      */
 187     public static function signup_user_parameters() {
 188         return new external_function_parameters(
 189             array(
 190                 'username' => new external_value(core_user::get_property_type('username'), 'Username'),
 191                 'password' => new external_value(core_user::get_property_type('password'), 'Plain text password'),
 192                 'firstname' => new external_value(core_user::get_property_type('firstname'), 'The first name(s) of the user'),
 193                 'lastname' => new external_value(core_user::get_property_type('lastname'), 'The family name of the user'),
 194                 'email' => new external_value(core_user::get_property_type('email'), 'A valid and unique email address'),
 195                 'city' => new external_value(core_user::get_property_type('city'), 'Home city of the user', VALUE_DEFAULT, ''),
 196                 'country' => new external_value(core_user::get_property_type('country'), 'Home country code', VALUE_DEFAULT, ''),
 197                 'recaptchachallengehash' => new external_value(PARAM_RAW, 'Recaptcha challenge hash', VALUE_DEFAULT, ''),
 198                 'recaptcharesponse' => new external_value(PARAM_NOTAGS, 'Recaptcha response', VALUE_DEFAULT, ''),
 199                 'customprofilefields' => new external_multiple_structure(
 200                     new external_single_structure(
 201                         array(
 202                             'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field'),
 203                             'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
 204                             'value' => new external_value(PARAM_RAW, 'Custom field value, can be an encoded json if required')
 205                         )
 206                     ), 'User custom fields (also known as user profile fields)', VALUE_DEFAULT, array()
 207                 ),
 208                 'redirect' => new external_value(PARAM_LOCALURL, 'Redirect the user to this site url after confirmation.',
 209                                                     VALUE_DEFAULT, ''),
 210             )
 211         );
 212     }
 213
 214     /**
 215      * Get the signup required settings and profile fields.
 216      *
 217      * @param  string $username               username
 218      * @param  string $password               plain text password
 219      * @param  string $firstname              the first name(s) of the user
 220      * @param  string $lastname               the family name of the user
 221      * @param  string $email                  a valid and unique email address
 222      * @param  string $city                   home city of the user
 223      * @param  string $country                home country code
 224      * @param  string $recaptchachallengehash recaptcha challenge hash
 225      * @param  string $recaptcharesponse      recaptcha response
 226      * @param  array  $customprofilefields    user custom fields (also known as user profile fields)
 227      * @param  string $redirect               Site url to redirect the user after confirmation
 228      * @return array settings and possible warnings
 229      * @since Moodle 3.2
 230      * @throws moodle_exception
 231      * @throws invalid_parameter_exception
 232      */
 233     public static function signup_user($username, $password, $firstname, $lastname, $email, $city = '', $country = '',
 234                                         $recaptchachallengehash = '', $recaptcharesponse = '', $customprofilefields = array(),
 235                                         $redirect = '') {
 236         global $CFG, $PAGE;
 237
 238         $warnings = array();
 239         $params = self::validate_parameters(
 240             self::signup_user_parameters(),
 241             array(
 242                 'username' => $username,
 243                 'password' => $password,
 244                 'firstname' => $firstname,
 245                 'lastname' => $lastname,
 246                 'email' => $email,
 247                 'city' => $city,
 248                 'country' => $country,
 249                 'recaptchachallengehash' => $recaptchachallengehash,
 250                 'recaptcharesponse' => $recaptcharesponse,
 251                 'customprofilefields' => $customprofilefields,
 252                 'redirect' => $redirect,
 253             )
 254         );
 255
 256         // We need this to make work the format text functions.
 257         $context = context_system::instance();
 258         $PAGE->set_context($context);
 259
 260         self::check_signup_enabled();
 261
 262         // Validate profile fields param types.
 263         $allowedfields = profile_get_signup_fields();
 264         $fieldproperties = array();
 265         $fieldsrequired = array();
 266         foreach ($allowedfields as $field) {
 267             $fieldproperties[$field->object->inputname] = $field->object->get_field_properties();
 268             if ($field->object->is_required()) {
 269                 $fieldsrequired[$field->object->inputname] = true;
 270             }
 271         }
 272
 273         foreach ($params['customprofilefields'] as $profilefield) {
 274             if (!array_key_exists($profilefield['name'], $fieldproperties)) {
 275                 throw new invalid_parameter_exception('Invalid field' . $profilefield['name']);
 276             }
 277             list($type, $allownull) = $fieldproperties[$profilefield['name']];
 278             validate_param($profilefield['value'], $type, $allownull);
 279             // Remove from the potential required list.
 280             if (isset($fieldsrequired[$profilefield['name']])) {
 281                 unset($fieldsrequired[$profilefield['name']]);
 282             }
 283         }
 284         if (!empty($fieldsrequired)) {
 285             throw new invalid_parameter_exception('Missing required parameters: ' . implode(',', array_keys($fieldsrequired)));
 286         }
 287
 288         // Validate the data sent.
 289         $data = $params;
 290         $data['email2'] = $data['email'];
 291         // Force policy agreed if a site policy is set. The client is responsible of implementing the interface check.
 292         $manager = new \core_privacy\local\sitepolicy\manager();
 293         if ($manager->is_defined()) {
 294             $data['policyagreed'] = 1;
 295         }
 296         unset($data['recaptcharesponse']);
 297         unset($data['customprofilefields']);
 298         // Add profile fields data.
 299         foreach ($params['customprofilefields'] as $profilefield) {
 300             // First, check if the value is a json (some profile fields like text area uses an array for sending data).
 301             $datadecoded = json_decode($profilefield['value'], true);
 302             if (is_array($datadecoded) && (json_last_error() == JSON_ERROR_NONE)) {
 303                 $data[$profilefield['name']] = $datadecoded;
 304             } else {
 305                 $data[$profilefield['name']] = $profilefield['value'];
 306             }
 307         }
 308
 309         $errors = signup_validate_data($data, array());
 310
 311         // Validate recaptcha.
 312         if (signup_captcha_enabled()) {
 313             require_once($CFG->libdir . '/recaptchalib_v2.php');
 314             $response = recaptcha_check_response(RECAPTCHA_VERIFY_URL, $CFG->recaptchaprivatekey,
 315                                                  getremoteaddr(), $params['recaptcharesponse']);
 316             if (!$response['isvalid']) {
 317                 $errors['recaptcharesponse'] = $response['error'];
 318             }
 319         }
 320
 321         if (!empty($errors)) {
 322             foreach ($errors as $itemname => $message) {
 323                 $warnings[] = array(
 324                     'item' => $itemname,
 325                     'itemid' => 0,
 326                     'warningcode' => 'fielderror',
 327                     'message' => s($message)
 328                 );
 329             }
 330             $result = array(
 331                 'success' => false,
 332                 'warnings' => $warnings,
 333             );
 334         } else {
 335             // Save the user.
 336             $user = signup_setup_new_user((object) $data);
 337
 338             $authplugin = get_auth_plugin('email');
 339
 340             // Check if we should redirect the user once the user is confirmed.
 341             $confirmationurl = null;
 342             if (!empty($params['redirect'])) {
 343                 // Pass via moodle_url to fix thinks like admin links.
 344                 $redirect = new moodle_url($params['redirect']);
 345
 346                 $confirmationurl = new moodle_url('/login/confirm.php', array('redirect' => $redirect->out()));
 347             }
 348             $authplugin->user_signup_with_confirmation($user, false, $confirmationurl);
 349
 350             $result = array(
 351                 'success' => true,
 352                 'warnings' => array(),
 353             );
 354         }
 355         return $result;
 356     }
 357
 358     /**
 359      * Describes the signup_user return value.
 360      *
 361      * @return external_single_structure
 362      * @since Moodle 3.2
 363      */
 364     public static function signup_user_returns() {
 365
 366         return new external_single_structure(
 367             array(
 368                 'success' => new external_value(PARAM_BOOL, 'True if the user was created false otherwise'),
 369                 'warnings'  => new external_warnings(),
 370             )
 371         );
 372     }
 373 }