MDL-57557 theme_boost: tweak js popover settings
[moodle.git] / lib / classes / user.php
CommitLineData
3bcf6b3c
RT
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 * User class
19 *
20 * @package core
21 * @copyright 2013 Rajesh Taneja <rajesh@moodle.com>
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25defined('MOODLE_INTERNAL') || die();
26
27/**
28 * User class to access user details.
29 *
30 * @todo move api's from user/lib.php and depreciate old ones.
31 * @package core
32 * @copyright 2013 Rajesh Taneja <rajesh@moodle.com>
33 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34 */
35class core_user {
36 /**
37 * No reply user id.
38 */
39 const NOREPLY_USER = -10;
40
41 /**
6c3ad77e 42 * Support user id.
3bcf6b3c
RT
43 */
44 const SUPPORT_USER = -20;
45
9715f61a
AG
46 /**
47 * Hide email address from everyone.
48 */
49 const MAILDISPLAY_HIDE = 0;
50
51 /**
52 * Display email address to everyone.
53 */
54 const MAILDISPLAY_EVERYONE = 1;
55
56 /**
57 * Display email address to course members only.
58 */
59 const MAILDISPLAY_COURSE_MEMBERS_ONLY = 2;
60
3bcf6b3c
RT
61 /** @var stdClass keep record of noreply user */
62 public static $noreplyuser = false;
63
64 /** @var stdClass keep record of support user */
65 public static $supportuser = false;
66
dccf9ca3
SL
67 /** @var array store user fields properties cache. */
68 protected static $propertiescache = null;
69
3bcf6b3c
RT
70 /**
71 * Return user object from db or create noreply or support user,
72 * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
73 * respectively. If userid is not found, then return false.
74 *
75 * @param int $userid user id
76 * @param string $fields A comma separated list of user fields to be returned, support and noreply user
77 * will not be filtered by this.
78 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
79 * IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
80 * MUST_EXIST means throw an exception if no user record or multiple records found.
81 * @return stdClass|bool user record if found, else false.
82 * @throws dml_exception if user record not found and respective $strictness is set.
83 */
84 public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
85 global $DB;
86
87 // If noreply user then create fake record and return.
88 switch ($userid) {
89 case self::NOREPLY_USER:
d1b30757 90 return self::get_noreply_user();
3bcf6b3c
RT
91 break;
92 case self::SUPPORT_USER:
d1b30757 93 return self::get_support_user();
3bcf6b3c
RT
94 break;
95 default:
96 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
97 }
98 }
99
2d35b7d3
GPL
100
101 /**
102 * Return user object from db based on their username.
103 *
104 * @param string $username The username of the user searched.
105 * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
106 * @param int $mnethostid The id of the remote host.
107 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
108 * IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
109 * MUST_EXIST means throw an exception if no user record or multiple records found.
110 * @return stdClass|bool user record if found, else false.
111 * @throws dml_exception if user record not found and respective $strictness is set.
112 */
113 public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
114 global $DB, $CFG;
115
116 // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
117 if (empty($mnethostid)) {
118 // If empty, we restrict to local users.
119 $mnethostid = $CFG->mnet_localhost_id;
120 }
121
122 return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
123 }
124
3bcf6b3c
RT
125 /**
126 * Helper function to return dummy noreply user record.
127 *
128 * @return stdClass
129 */
130 protected static function get_dummy_user_record() {
131 global $CFG;
132
133 $dummyuser = new stdClass();
134 $dummyuser->id = self::NOREPLY_USER;
135 $dummyuser->email = $CFG->noreplyaddress;
136 $dummyuser->firstname = get_string('noreplyname');
137 $dummyuser->username = 'noreply';
138 $dummyuser->lastname = '';
139 $dummyuser->confirmed = 1;
140 $dummyuser->suspended = 0;
141 $dummyuser->deleted = 0;
142 $dummyuser->picture = 0;
143 $dummyuser->auth = 'manual';
144 $dummyuser->firstnamephonetic = '';
145 $dummyuser->lastnamephonetic = '';
146 $dummyuser->middlename = '';
147 $dummyuser->alternatename = '';
148 $dummyuser->imagealt = '';
149 return $dummyuser;
150 }
151
152 /**
153 * Return noreply user record, this is currently used in messaging
154 * system only for sending messages from noreply email.
155 * It will return record of $CFG->noreplyuserid if set else return dummy
156 * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
157 *
158 * @return stdClass user record.
159 */
160 public static function get_noreply_user() {
161 global $CFG;
162
163 if (!empty(self::$noreplyuser)) {
164 return self::$noreplyuser;
165 }
166
167 // If noreply user is set then use it, else create one.
168 if (!empty($CFG->noreplyuserid)) {
169 self::$noreplyuser = self::get_user($CFG->noreplyuserid);
ec907228
SL
170 self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
171 return self::$noreplyuser;
172 } else {
173 // Do not cache the dummy user record to avoid language internationalization issues.
174 $noreplyuser = self::get_dummy_user_record();
175 $noreplyuser->maildisplay = '1'; // Show to all.
176 $noreplyuser->emailstop = 1;
177 return $noreplyuser;
3bcf6b3c 178 }
3bcf6b3c
RT
179 }
180
181 /**
182 * Return support user record, this is currently used in messaging
183 * system only for sending messages to support email.
184 * $CFG->supportuserid is set then returns user record
185 * $CFG->supportemail is set then return dummy record with $CFG->supportemail
186 * else return admin user record with hard-coded $user->emailstop = 0, so user
187 * gets support message.
188 *
189 * @return stdClass user record.
190 */
191 public static function get_support_user() {
192 global $CFG;
193
194 if (!empty(self::$supportuser)) {
195 return self::$supportuser;
196 }
197
198 // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
199 if (!empty($CFG->supportuserid)) {
200 self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
ec907228
SL
201 } else if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
202 // Try sending it to support email if support user is not set.
203 $supportuser = self::get_dummy_user_record();
204 $supportuser->id = self::SUPPORT_USER;
205 $supportuser->email = $CFG->supportemail;
6c3ad77e 206 if ($CFG->supportname) {
ec907228 207 $supportuser->firstname = $CFG->supportname;
6c3ad77e 208 }
ec907228
SL
209 $supportuser->username = 'support';
210 $supportuser->maildisplay = '1'; // Show to all.
211 // Unset emailstop to make sure support message is sent.
212 $supportuser->emailstop = 0;
213 return $supportuser;
3bcf6b3c
RT
214 }
215
216 // Send support msg to admin user if nothing is set above.
217 if (empty(self::$supportuser)) {
218 self::$supportuser = get_admin();
219 }
220
221 // Unset emailstop to make sure support message is sent.
222 self::$supportuser->emailstop = 0;
223 return self::$supportuser;
224 }
225
226 /**
227 * Reset self::$noreplyuser and self::$supportuser.
228 * This is only used by phpunit, and there is no other use case for this function.
229 * Please don't use it outside phpunit.
230 */
231 public static function reset_internal_users() {
232 if (PHPUNIT_TEST) {
233 self::$noreplyuser = false;
234 self::$supportuser = false;
235 } else {
236 debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
237 }
238 }
239
240 /**
241 * Return true is user id is greater than self::NOREPLY_USER and
6c3ad77e 242 * alternatively check db.
3bcf6b3c
RT
243 *
244 * @param int $userid user id.
245 * @param bool $checkdb if true userid will be checked in db. By default it's false, and
246 * userid is compared with NOREPLY_USER for performance.
247 * @return bool true is real user else false.
248 */
249 public static function is_real_user($userid, $checkdb = false) {
6c3ad77e
PS
250 global $DB;
251
3bcf6b3c
RT
252 if ($userid < 0) {
253 return false;
254 }
255 if ($checkdb) {
256 return $DB->record_exists('user', array('id' => $userid));
257 } else {
258 return true;
259 }
260 }
3961ebfb
JL
261
262 /**
263 * Check if the given user is an active user in the site.
264 *
265 * @param stdClass $user user object
266 * @param boolean $checksuspended whether to check if the user has the account suspended
267 * @param boolean $checknologin whether to check if the user uses the nologin auth method
268 * @throws moodle_exception
269 * @since Moodle 3.0
270 */
271 public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
272
273 if (!self::is_real_user($user->id)) {
274 throw new moodle_exception('invaliduser', 'error');
275 }
276
277 if ($user->deleted) {
278 throw new moodle_exception('userdeleted');
279 }
280
281 if (empty($user->confirmed)) {
282 throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
283 }
284
285 if (isguestuser($user)) {
286 throw new moodle_exception('guestsarenotallowed', 'error');
287 }
288
289 if ($checksuspended and $user->suspended) {
290 throw new moodle_exception('suspended', 'auth');
291 }
292
293 if ($checknologin and $user->auth == 'nologin') {
294 throw new moodle_exception('suspended', 'auth');
295 }
296 }
dccf9ca3 297
5407c5b0
RS
298 /**
299 * Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.
300 *
301 * @param stdClass $usernew An object that contains some information about the user being updated
302 * @param array $filemanageroptions
303 * @return bool True if the user was updated, false if it stayed the same.
304 */
305 public static function update_picture(stdClass $usernew, $filemanageroptions = array()) {
306 global $CFG, $DB;
307 require_once("$CFG->libdir/gdlib.php");
308
309 $context = context_user::instance($usernew->id, MUST_EXIST);
310 $user = core_user::get_user($usernew->id, 'id, picture', MUST_EXIST);
311
312 $newpicture = $user->picture;
313 // Get file_storage to process files.
314 $fs = get_file_storage();
315 if (!empty($usernew->deletepicture)) {
316 // The user has chosen to delete the selected users picture.
317 $fs->delete_area_files($context->id, 'user', 'icon'); // Drop all images in area.
318 $newpicture = 0;
319
320 } else {
321 // Save newly uploaded file, this will avoid context mismatch for newly created users.
322 file_save_draft_area_files($usernew->imagefile, $context->id, 'user', 'newicon', 0, $filemanageroptions);
323 if (($iconfiles = $fs->get_area_files($context->id, 'user', 'newicon')) && count($iconfiles) == 2) {
324 // Get file which was uploaded in draft area.
325 foreach ($iconfiles as $file) {
326 if (!$file->is_directory()) {
327 break;
328 }
329 }
330 // Copy file to temporary location and the send it for processing icon.
331 if ($iconfile = $file->copy_content_to_temp()) {
332 // There is a new image that has been uploaded.
333 // Process the new image and set the user to make use of it.
334 // NOTE: Uploaded images always take over Gravatar.
335 $newpicture = (int)process_new_icon($context, 'user', 'icon', 0, $iconfile);
336 // Delete temporary file.
337 @unlink($iconfile);
338 // Remove uploaded file.
339 $fs->delete_area_files($context->id, 'user', 'newicon');
340 } else {
341 // Something went wrong while creating temp file.
342 // Remove uploaded file.
343 $fs->delete_area_files($context->id, 'user', 'newicon');
344 return false;
345 }
346 }
347 }
348
349 if ($newpicture != $user->picture) {
350 $DB->set_field('user', 'picture', $newpicture, array('id' => $user->id));
351 return true;
352 } else {
353 return false;
354 }
355 }
356
357
358
dccf9ca3
SL
359 /**
360 * Definition of user profile fields and the expected parameter type for data validation.
361 *
4ce09314
SL
362 * array(
363 * 'property_name' => array( // The user property to be checked. Should match the field on the user table.
364 * 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
365 * 'type' => PARAM_TYPE, // Expected parameter type of the user field.
366 * 'choices' => array(1, 2..) // An array of accepted values of the user field.
367 * 'default' => $CFG->setting // An default value for the field.
368 * )
369 * )
370 *
371 * The fields choices and default are optional.
372 *
dccf9ca3
SL
373 * @return void
374 */
375 protected static function fill_properties_cache() {
4ce09314 376 global $CFG;
dccf9ca3
SL
377 if (self::$propertiescache !== null) {
378 return;
379 }
380
381 // Array of user fields properties and expected parameters.
382 // Every new field on the user table should be added here otherwise it won't be validated.
383 $fields = array();
4ce09314
SL
384 $fields['id'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
385 $fields['auth'] = array('type' => PARAM_AUTH, 'null' => NULL_NOT_ALLOWED);
386 $fields['confirmed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
387 $fields['policyagreed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
388 $fields['deleted'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
389 $fields['suspended'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
390 $fields['mnethostid'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
391 $fields['username'] = array('type' => PARAM_USERNAME, 'null' => NULL_NOT_ALLOWED);
392 $fields['password'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
393 $fields['idnumber'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
394 $fields['firstname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
395 $fields['lastname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
396 $fields['surname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
397 $fields['email'] = array('type' => PARAM_RAW_TRIMMED, 'null' => NULL_NOT_ALLOWED);
398 $fields['emailstop'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
399 $fields['icq'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
400 $fields['skype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
401 $fields['aim'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
402 $fields['yahoo'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
403 $fields['msn'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
404 $fields['phone1'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
405 $fields['phone2'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
406 $fields['institution'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
407 $fields['department'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
408 $fields['address'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
409 $fields['city'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->defaultcity);
410 $fields['country'] = array('type' => PARAM_ALPHA, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->country,
411 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_countries(true, true)));
412 $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->lang,
aa788b3c 413 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
4ce09314
SL
414 $fields['calendartype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
415 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
416 $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
417 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
16825c4e
FM
418 $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
419 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
4ce09314
SL
420 $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
421 $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
422 $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
423 $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
424 $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
425 $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
426 $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
427 $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
428 $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
429 $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
430 $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
431 'default' => $CFG->defaultpreference_mailformat);
432 $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
433 'default' => $CFG->defaultpreference_maildigest);
434 $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
435 'default' => $CFG->defaultpreference_maildisplay);
436 $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
437 'default' => $CFG->defaultpreference_autosubscribe);
438 $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
439 'default' => $CFG->defaultpreference_trackforums);
440 $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
441 $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
442 $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
443 $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
444 $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
445 $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
446 $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
447 $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
dccf9ca3
SL
448
449 self::$propertiescache = $fields;
450 }
451
452 /**
453 * Get properties of a user field.
454 *
455 * @param string $property property name to be retrieved.
456 * @throws coding_exception if the requested property name is invalid.
457 * @return array the property definition.
458 */
459 public static function get_property_definition($property) {
460
461 self::fill_properties_cache();
462
463 if (!array_key_exists($property, self::$propertiescache)) {
464 throw new coding_exception('Invalid property requested.');
465 }
466
467 return self::$propertiescache[$property];
468 }
469
4ce09314
SL
470 /**
471 * Validate user data.
472 *
473 * This method just validates each user field and return an array of errors. It doesn't clean the data,
474 * the methods clean() and clean_field() should be used for this purpose.
475 *
476 * @param stdClass|array $data user data object or array to be validated.
477 * @return array|true $errors array of errors found on the user object, true if the validation passed.
478 */
479 public static function validate($data) {
480 // Get all user profile fields definition.
481 self::fill_properties_cache();
482
483 foreach ($data as $property => $value) {
484 try {
485 if (isset(self::$propertiescache[$property])) {
486 validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
487 }
488 // Check that the value is part of a list of allowed values.
489 if (!empty(self::$propertiescache[$property]['choices']) &&
aa788b3c 490 !isset(self::$propertiescache[$property]['choices'][$value])) {
4ce09314
SL
491 throw new invalid_parameter_exception($value);
492 }
493 } catch (invalid_parameter_exception $e) {
494 $errors[$property] = $e->getMessage();
495 }
496 }
497
498 return empty($errors) ? true : $errors;
499 }
500
dccf9ca3
SL
501 /**
502 * Clean the properties cache.
503 *
504 * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
505 * Intended for use only for testing, phpunit calls this before every test.
506 */
507 public static function reset_caches() {
508 self::$propertiescache = null;
509 }
4ce09314
SL
510
511 /**
512 * Clean the user data.
513 *
514 * @param stdClass|array $user the user data to be validated against properties definition.
515 * @return stdClass $user the cleaned user data.
516 */
517 public static function clean_data($user) {
518 if (empty($user)) {
519 return $user;
520 }
521
522 foreach ($user as $field => $value) {
523 // Get the property parameter type and do the cleaning.
524 try {
aa788b3c 525 $user->$field = core_user::clean_field($value, $field);
4ce09314
SL
526 } catch (coding_exception $e) {
527 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
528 }
529 }
530
531 return $user;
532 }
533
534 /**
535 * Clean a specific user field.
536 *
537 * @param string $data the user field data to be cleaned.
538 * @param string $field the user field name on the property definition cache.
539 * @return string the cleaned user data.
540 */
541 public static function clean_field($data, $field) {
542 if (empty($data) || empty($field)) {
543 return $data;
544 }
545
546 try {
547 $type = core_user::get_property_type($field);
548
549 if (isset(self::$propertiescache[$field]['choices'])) {
550 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
551 if (isset(self::$propertiescache[$field]['default'])) {
552 $data = self::$propertiescache[$field]['default'];
553 } else {
554 $data = '';
555 }
aa788b3c
SL
556 } else {
557 return $data;
4ce09314
SL
558 }
559 } else {
560 $data = clean_param($data, $type);
561 }
562 } catch (coding_exception $e) {
563 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
564 }
565
566 return $data;
567 }
568
569 /**
570 * Get the parameter type of the property.
571 *
572 * @param string $property property name to be retrieved.
573 * @throws coding_exception if the requested property name is invalid.
574 * @return int the property parameter type.
575 */
576 public static function get_property_type($property) {
577
578 self::fill_properties_cache();
579
580 if (!array_key_exists($property, self::$propertiescache)) {
581 throw new coding_exception('Invalid property requested: ' . $property);
582 }
583
584 return self::$propertiescache[$property]['type'];
585 }
586
587 /**
588 * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
589 *
590 * @param string $property property name to be retrieved.
591 * @throws coding_exception if the requested property name is invalid.
592 * @return bool true if the property is NULL_ALLOWED, false otherwise.
593 */
594 public static function get_property_null($property) {
595
596 self::fill_properties_cache();
597
598 if (!array_key_exists($property, self::$propertiescache)) {
599 throw new coding_exception('Invalid property requested: ' . $property);
600 }
601
602 return self::$propertiescache[$property]['null'];
603 }
604
605 /**
606 * Get the choices of the property.
607 *
608 * This is a helper method to validate a value against a list of acceptable choices.
16825c4e 609 * For instance: country, language, themes and etc.
4ce09314
SL
610 *
611 * @param string $property property name to be retrieved.
612 * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
613 * @return array the property parameter type.
614 */
615 public static function get_property_choices($property) {
616
617 self::fill_properties_cache();
618
619 if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
620 self::$propertiescache[$property])) {
621
622 throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
623 }
624
625 return self::$propertiescache[$property]['choices'];
626 }
627
628 /**
629 * Get the property default.
630 *
631 * This method gets the default value of a field (if exists).
632 *
633 * @param string $property property name to be retrieved.
634 * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
635 * @return string the property default value.
636 */
637 public static function get_property_default($property) {
638
639 self::fill_properties_cache();
640
641 if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
642 throw new coding_exception('Invalid property requested, or the property does not has a default value.');
643 }
644
645 return self::$propertiescache[$property]['default'];
646 }
3bcf6b3c 647}