MDL-67641 auth: Fix shortname type in get_signup_settings WS
[moodle.git] / 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/>.
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  */
27 defined('MOODLE_INTERNAL') || die;
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');
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 {
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;
54         if (empty($CFG->registerauth) or $CFG->registerauth != 'email') {
55             throw new moodle_exception('registrationdisabled', 'error');
56         }
57     }
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     }
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;
79         $context = context_system::instance();
80         // We need this to make work the format text functions.
81         $PAGE->set_context($context);
83         self::check_signup_enabled();
85         $result = array();
86         $result['namefields'] = useredit_get_required_name_fields();
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         }
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);
114                 $result['profilefields'][] = $fielddata;
115             }
116         }
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         }
123         $result['warnings'] = array();
124         return $result;
125     }
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() {
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     }
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     }
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;
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         );
256         // We need this to make work the format text functions.
257         $context = context_system::instance();
258         $PAGE->set_context($context);
260         self::check_signup_enabled();
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         }
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         }
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         }
309         $errors = signup_validate_data($data, array());
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         }
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);
338             $authplugin = get_auth_plugin('email');
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']);
346                 $confirmationurl = new moodle_url('/login/confirm.php', array('redirect' => $redirect->out()));
347             }
348             $authplugin->user_signup_with_confirmation($user, false, $confirmationurl);
350             $result = array(
351                 'success' => true,
352                 'warnings' => array(),
353             );
354         }
355         return $result;
356     }
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() {
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     }