user/profile/lib.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  * Profile field API library file.
  19  *
  20  * @package core_user
  21  * @copyright  2007 onwards Shane Elliot {@link http://pukunui.com}
  22  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 /**
  26  * Visible to anyone who has the moodle/site:viewuseridentity permission.
  27  * Editable by the profile owner if they have the moodle/user:editownprofile capability
  28  * or any user with the moodle/user:update capability.
  29  */
  30 define('PROFILE_VISIBLE_TEACHERS', '3');
  31
  32 /**
  33  * Visible to anyone who can view the user.
  34  * Editable by the profile owner if they have the moodle/user:editownprofile capability
  35  * or any user with the moodle/user:update capability.
  36  */
  37 define('PROFILE_VISIBLE_ALL', '2');
  38 /**
  39  * Visible to the profile owner or anyone with the moodle/user:viewalldetails capability.
  40  * Editable by the profile owner if they have the moodle/user:editownprofile capability
  41  * or any user with moodle/user:viewalldetails and moodle/user:update capabilities.
  42  */
  43 define('PROFILE_VISIBLE_PRIVATE', '1');
  44 /**
  45  * Only visible to users with the moodle/user:viewalldetails capability.
  46  * Only editable by users with the moodle/user:viewalldetails and moodle/user:update capabilities.
  47  */
  48 define('PROFILE_VISIBLE_NONE', '0');
  49
  50 /**
  51  * Base class for the customisable profile fields.
  52  *
  53  * @package core_user
  54  * @copyright  2007 onwards Shane Elliot {@link http://pukunui.com}
  55  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  56  */
  57 class profile_field_base {
  58
  59     // These 2 variables are really what we're interested in.
  60     // Everything else can be extracted from them.
  61
  62     /** @var int */
  63     public $fieldid;
  64
  65     /** @var int */
  66     public $userid;
  67
  68     /** @var stdClass */
  69     public $field;
  70
  71     /** @var string */
  72     public $inputname;
  73
  74     /** @var mixed */
  75     public $data;
  76
  77     /** @var string */
  78     public $dataformat;
  79
  80     /** @var string name of the user profile category */
  81     protected $categoryname;
  82
  83     /**
  84      * Constructor method.
  85      * @param int $fieldid id of the profile from the user_info_field table
  86      * @param int $userid id of the user for whom we are displaying data
  87      * @param stdClass $fielddata optional data for the field object plus additional fields 'hasuserdata', 'data' and 'dataformat'
  88      *    with user data. (If $fielddata->hasuserdata is empty, user data is not available and we should use default data).
  89      *    If this parameter is passed, constructor will not call load_data() at all.
  90      */
  91     public function __construct($fieldid=0, $userid=0, $fielddata=null) {
  92         global $CFG;
  93
  94         if ($CFG->debugdeveloper) {
  95             // In Moodle 3.4 the new argument $fielddata was added to the constructor. Make sure that
  96             // plugin constructor properly passes this argument.
  97             $backtrace = debug_backtrace();
  98             if (isset($backtrace[1]['class']) && $backtrace[1]['function'] === '__construct' &&
  99                     in_array(self::class, class_parents($backtrace[1]['class']))) {
 100                 // If this constructor is called from the constructor of the plugin make sure that the third argument was passed through.
 101                 if (count($backtrace[1]['args']) >= 3 && count($backtrace[0]['args']) < 3) {
 102                     debugging($backtrace[1]['class'].'::__construct() must support $fielddata as the third argument ' .
 103                         'and pass it to the parent constructor', DEBUG_DEVELOPER);
 104                 }
 105             }
 106         }
 107
 108         $this->set_fieldid($fieldid);
 109         $this->set_userid($userid);
 110         if ($fielddata) {
 111             $this->set_field($fielddata);
 112             if ($userid > 0 && !empty($fielddata->hasuserdata)) {
 113                 $this->set_user_data($fielddata->data, $fielddata->dataformat);
 114             }
 115         } else {
 116             $this->load_data();
 117         }
 118     }
 119
 120     /**
 121      * Old syntax of class constructor. Deprecated in PHP7.
 122      *
 123      * @deprecated since Moodle 3.1
 124      */
 125     public function profile_field_base($fieldid=0, $userid=0) {
 126         debugging('Use of class name as constructor is deprecated', DEBUG_DEVELOPER);
 127         self::__construct($fieldid, $userid);
 128     }
 129
 130     /**
 131      * Abstract method: Adds the profile field to the moodle form class
 132      * @abstract The following methods must be overwritten by child classes
 133      * @param MoodleQuickForm $mform instance of the moodleform class
 134      */
 135     public function edit_field_add($mform) {
 136         throw new \moodle_exception('mustbeoveride', 'debug', '', 'edit_field_add');
 137     }
 138
 139     /**
 140      * Display the data for this field
 141      * @return string
 142      */
 143     public function display_data() {
 144         $options = new stdClass();
 145         $options->para = false;
 146         return format_text($this->data, FORMAT_MOODLE, $options);
 147     }
 148
 149     /**
 150      * Print out the form field in the edit profile page
 151      * @param MoodleQuickForm $mform instance of the moodleform class
 152      * @return bool
 153      */
 154     public function edit_field($mform) {
 155         if (!$this->is_editable()) {
 156             return false;
 157         }
 158
 159         $this->edit_field_add($mform);
 160         $this->edit_field_set_default($mform);
 161         $this->edit_field_set_required($mform);
 162         return true;
 163     }
 164
 165     /**
 166      * Tweaks the edit form
 167      * @param MoodleQuickForm $mform instance of the moodleform class
 168      * @return bool
 169      */
 170     public function edit_after_data($mform) {
 171         if (!$this->is_editable()) {
 172             return false;
 173         }
 174
 175         $this->edit_field_set_locked($mform);
 176         return true;
 177     }
 178
 179     /**
 180      * Saves the data coming from form
 181      * @param stdClass $usernew data coming from the form
 182      */
 183     public function edit_save_data($usernew) {
 184         global $DB;
 185
 186         if (!isset($usernew->{$this->inputname})) {
 187             // Field not present in form, probably locked and invisible - skip it.
 188             return;
 189         }
 190
 191         $data = new stdClass();
 192
 193         $usernew->{$this->inputname} = $this->edit_save_data_preprocess($usernew->{$this->inputname}, $data);
 194         if (!isset($usernew->{$this->inputname})) {
 195             // Field cannot be set to null, set the default value.
 196             $usernew->{$this->inputname} = $this->field->defaultdata;
 197         }
 198
 199         $data->userid  = $usernew->id;
 200         $data->fieldid = $this->field->id;
 201         $data->data    = $usernew->{$this->inputname};
 202
 203         if ($dataid = $DB->get_field('user_info_data', 'id', array('userid' => $data->userid, 'fieldid' => $data->fieldid))) {
 204             $data->id = $dataid;
 205             $DB->update_record('user_info_data', $data);
 206         } else {
 207             $DB->insert_record('user_info_data', $data);
 208         }
 209     }
 210
 211     /**
 212      * Validate the form field from profile page
 213      *
 214      * @param stdClass $usernew
 215      * @return  array  error messages for the form validation
 216      */
 217     public function edit_validate_field($usernew) {
 218         global $DB;
 219
 220         $errors = array();
 221         // Get input value.
 222         if (isset($usernew->{$this->inputname})) {
 223             if (is_array($usernew->{$this->inputname}) && isset($usernew->{$this->inputname}['text'])) {
 224                 $value = $usernew->{$this->inputname}['text'];
 225             } else {
 226                 $value = $usernew->{$this->inputname};
 227             }
 228         } else {
 229             $value = '';
 230         }
 231
 232         // Check for uniqueness of data if required.
 233         if ($this->is_unique() && (($value !== '') || $this->is_required())) {
 234             $data = $DB->get_records_sql('
 235                     SELECT id, userid
 236                       FROM {user_info_data}
 237                      WHERE fieldid = ?
 238                        AND ' . $DB->sql_compare_text('data', 255) . ' = ' . $DB->sql_compare_text('?', 255),
 239                     array($this->field->id, $value));
 240             if ($data) {
 241                 $existing = false;
 242                 foreach ($data as $v) {
 243                     if ($v->userid == $usernew->id) {
 244                         $existing = true;
 245                         break;
 246                     }
 247                 }
 248                 if (!$existing) {
 249                     $errors[$this->inputname] = get_string('valuealreadyused');
 250                 }
 251             }
 252         }
 253         return $errors;
 254     }
 255
 256     /**
 257      * Sets the default data for the field in the form object
 258      * @param MoodleQuickForm $mform instance of the moodleform class
 259      */
 260     public function edit_field_set_default($mform) {
 261         if (isset($this->field->defaultdata)) {
 262             $mform->setDefault($this->inputname, $this->field->defaultdata);
 263         }
 264     }
 265
 266     /**
 267      * Sets the required flag for the field in the form object
 268      *
 269      * @param MoodleQuickForm $mform instance of the moodleform class
 270      */
 271     public function edit_field_set_required($mform) {
 272         global $USER;
 273         if ($this->is_required() && ($this->userid == $USER->id || isguestuser())) {
 274             $mform->addRule($this->inputname, get_string('required'), 'required', null, 'client');
 275         }
 276     }
 277
 278     /**
 279      * HardFreeze the field if locked.
 280      * @param MoodleQuickForm $mform instance of the moodleform class
 281      */
 282     public function edit_field_set_locked($mform) {
 283         if (!$mform->elementExists($this->inputname)) {
 284             return;
 285         }
 286         if ($this->is_locked() and !has_capability('moodle/user:update', context_system::instance())) {
 287             $mform->hardFreeze($this->inputname);
 288             $mform->setConstant($this->inputname, $this->data);
 289         }
 290     }
 291
 292     /**
 293      * Hook for child classess to process the data before it gets saved in database
 294      * @param stdClass $data
 295      * @param stdClass $datarecord The object that will be used to save the record
 296      * @return  mixed
 297      */
 298     public function edit_save_data_preprocess($data, $datarecord) {
 299         return $data;
 300     }
 301
 302     /**
 303      * Loads a user object with data for this field ready for the edit profile
 304      * form
 305      * @param stdClass $user a user object
 306      */
 307     public function edit_load_user_data($user) {
 308         if ($this->data !== null) {
 309             $user->{$this->inputname} = $this->data;
 310         }
 311     }
 312
 313     /**
 314      * Check if the field data should be loaded into the user object
 315      * By default it is, but for field types where the data may be potentially
 316      * large, the child class should override this and return false
 317      * @return bool
 318      */
 319     public function is_user_object_data() {
 320         return true;
 321     }
 322
 323     /**
 324      * Accessor method: set the userid for this instance
 325      * @internal This method should not generally be overwritten by child classes.
 326      * @param integer $userid id from the user table
 327      */
 328     public function set_userid($userid) {
 329         $this->userid = $userid;
 330     }
 331
 332     /**
 333      * Accessor method: set the fieldid for this instance
 334      * @internal This method should not generally be overwritten by child classes.
 335      * @param integer $fieldid id from the user_info_field table
 336      */
 337     public function set_fieldid($fieldid) {
 338         $this->fieldid = $fieldid;
 339     }
 340
 341     /**
 342      * Sets the field object and default data and format into $this->data and $this->dataformat
 343      *
 344      * This method should be called before {@link self::set_user_data}
 345      *
 346      * @param stdClass $field
 347      * @throws coding_exception
 348      */
 349     public function set_field($field) {
 350         global $CFG;
 351         if ($CFG->debugdeveloper) {
 352             $properties = ['id', 'shortname', 'name', 'datatype', 'description', 'descriptionformat', 'categoryid', 'sortorder',
 353                 'required', 'locked', 'visible', 'forceunique', 'signup', 'defaultdata', 'defaultdataformat', 'param1', 'param2',
 354                 'param3', 'param4', 'param5'];
 355             foreach ($properties as $property) {
 356                 if (!property_exists($field, $property)) {
 357                     debugging('The \'' . $property . '\' property must be set.', DEBUG_DEVELOPER);
 358                 }
 359             }
 360         }
 361         if ($this->fieldid && $this->fieldid != $field->id) {
 362             throw new coding_exception('Can not set field object after a different field id was set');
 363         }
 364         $this->fieldid = $field->id;
 365         $this->field = $field;
 366         $this->inputname = 'profile_field_' . $this->field->shortname;
 367         $this->data = $this->field->defaultdata;
 368         $this->dataformat = FORMAT_HTML;
 369     }
 370
 371     /**
 372      * Sets user id and user data for the field
 373      *
 374      * @param mixed $data
 375      * @param int $dataformat
 376      */
 377     public function set_user_data($data, $dataformat) {
 378         $this->data = $data;
 379         $this->dataformat = $dataformat;
 380     }
 381
 382     /**
 383      * Set the name for the profile category where this field is
 384      *
 385      * @param string $categoryname
 386      */
 387     public function set_category_name($categoryname) {
 388         $this->categoryname = $categoryname;
 389     }
 390
 391     /**
 392      * Return field short name
 393      *
 394      * @return string
 395      */
 396     public function get_shortname(): string {
 397         return $this->field->shortname;
 398     }
 399
 400     /**
 401      * Returns the name of the profile category where this field is
 402      *
 403      * @return string
 404      */
 405     public function get_category_name() {
 406         global $DB;
 407         if ($this->categoryname === null) {
 408             $this->categoryname = $DB->get_field('user_info_category', 'name', ['id' => $this->field->categoryid]);
 409         }
 410         return $this->categoryname;
 411     }
 412
 413     /**
 414      * Accessor method: Load the field record and user data associated with the
 415      * object's fieldid and userid
 416      *
 417      * @internal This method should not generally be overwritten by child classes.
 418      */
 419     public function load_data() {
 420         global $DB;
 421
 422         // Load the field object.
 423         if (($this->fieldid == 0) or (!($field = $DB->get_record('user_info_field', array('id' => $this->fieldid))))) {
 424             $this->field = null;
 425             $this->inputname = '';
 426         } else {
 427             $this->set_field($field);
 428         }
 429
 430         if (!empty($this->field) && $this->userid > 0) {
 431             $params = array('userid' => $this->userid, 'fieldid' => $this->fieldid);
 432             if ($data = $DB->get_record('user_info_data', $params, 'data, dataformat')) {
 433                 $this->set_user_data($data->data, $data->dataformat);
 434             }
 435         } else {
 436             $this->data = null;
 437         }
 438     }
 439
 440     /**
 441      * Check if the field data is visible to the current user
 442      * @internal This method should not generally be overwritten by child classes.
 443      *
 444      * @param context|null $context
 445      * @return bool
 446      */
 447     public function is_visible(?context $context = null): bool {
 448         global $USER, $COURSE;
 449
 450         if ($context === null) {
 451             $context = ($this->userid > 0) ? context_user::instance($this->userid) : context_system::instance();
 452         }
 453
 454         switch ($this->field->visible) {
 455             case PROFILE_VISIBLE_TEACHERS:
 456                 if ($this->is_signup_field() && (empty($this->userid) || isguestuser($this->userid))) {
 457                     return true;
 458                 } else if ($this->userid == $USER->id) {
 459                     return true;
 460                 } else if ($this->userid > 0) {
 461                     return has_capability('moodle/user:viewalldetails', $context);
 462                 } else {
 463                     $coursecontext = context_course::instance($COURSE->id);
 464                     return has_capability('moodle/site:viewuseridentity', $coursecontext);
 465                 }
 466             case PROFILE_VISIBLE_ALL:
 467                 return true;
 468             case PROFILE_VISIBLE_PRIVATE:
 469                 if ($this->is_signup_field() && (empty($this->userid) || isguestuser($this->userid))) {
 470                     return true;
 471                 } else if ($this->userid == $USER->id) {
 472                     return true;
 473                 } else {
 474                     return has_capability('moodle/user:viewalldetails', $context);
 475                 }
 476             default:
 477                 // PROFILE_VISIBLE_NONE, so let's check capabilities at system level.
 478                 if ($this->userid > 0) {
 479                     $context = context_system::instance();
 480                 }
 481                 return has_capability('moodle/user:viewalldetails', $context);
 482         }
 483     }
 484
 485     /**
 486      * Check if the field data is editable for the current user
 487      * This method should not generally be overwritten by child classes.
 488      * @return bool
 489      */
 490     public function is_editable() {
 491         global $USER;
 492
 493         if (!$this->is_visible()) {
 494             return false;
 495         }
 496
 497         if ($this->is_signup_field() && (empty($this->userid) || isguestuser($this->userid))) {
 498             // Allow editing the field on the signup page.
 499             return true;
 500         }
 501
 502         $systemcontext = context_system::instance();
 503
 504         if ($this->userid == $USER->id && has_capability('moodle/user:editownprofile', $systemcontext)) {
 505             return true;
 506         }
 507
 508         if (has_capability('moodle/user:update', $systemcontext)) {
 509             return true;
 510         }
 511
 512         // Checking for mentors have capability to edit user's profile.
 513         if ($this->userid > 0) {
 514             $usercontext = context_user::instance($this->userid);
 515             if ($this->userid != $USER->id && has_capability('moodle/user:editprofile', $usercontext, $USER->id)) {
 516                 return true;
 517             }
 518         }
 519
 520         return false;
 521     }
 522
 523     /**
 524      * Check if the field data is considered empty
 525      * @internal This method should not generally be overwritten by child classes.
 526      * @return boolean
 527      */
 528     public function is_empty() {
 529         return ( ($this->data != '0') and empty($this->data));
 530     }
 531
 532     /**
 533      * Check if the field is required on the edit profile page
 534      * @internal This method should not generally be overwritten by child classes.
 535      * @return bool
 536      */
 537     public function is_required() {
 538         return (boolean)$this->field->required;
 539     }
 540
 541     /**
 542      * Check if the field is locked on the edit profile page
 543      * @internal This method should not generally be overwritten by child classes.
 544      * @return bool
 545      */
 546     public function is_locked() {
 547         return (boolean)$this->field->locked;
 548     }
 549
 550     /**
 551      * Check if the field data should be unique
 552      * @internal This method should not generally be overwritten by child classes.
 553      * @return bool
 554      */
 555     public function is_unique() {
 556         return (boolean)$this->field->forceunique;
 557     }
 558
 559     /**
 560      * Check if the field should appear on the signup page
 561      * @internal This method should not generally be overwritten by child classes.
 562      * @return bool
 563      */
 564     public function is_signup_field() {
 565         return (boolean)$this->field->signup;
 566     }
 567
 568     /**
 569      * Return the field settings suitable to be exported via an external function.
 570      * By default it return all the field settings.
 571      *
 572      * @return array all the settings
 573      * @since Moodle 3.2
 574      */
 575     public function get_field_config_for_external() {
 576         return (array) $this->field;
 577     }
 578
 579     /**
 580      * Return the field type and null properties.
 581      * This will be used for validating the data submitted by a user.
 582      *
 583      * @return array the param type and null property
 584      * @since Moodle 3.2
 585      */
 586     public function get_field_properties() {
 587         return array(PARAM_RAW, NULL_NOT_ALLOWED);
 588     }
 589
 590     /**
 591      * Whether to display the field and content to the user
 592      *
 593      * @param context|null $context
 594      * @return bool
 595      */
 596     public function show_field_content(?context $context = null): bool {
 597         return $this->is_visible($context) && !$this->is_empty();
 598     }
 599
 600     /**
 601      * Check if the field should convert the raw data into user-friendly data when exporting
 602      *
 603      * @return bool
 604      */
 605     public function is_transform_supported(): bool {
 606         return false;
 607     }
 608 }
 609
 610 /**
 611  * Return profile field instance for given type
 612  *
 613  * @param string $type
 614  * @param int $fieldid
 615  * @param int $userid
 616  * @param stdClass|null $fielddata
 617  * @return profile_field_base
 618  */
 619 function profile_get_user_field(string $type, int $fieldid = 0, int $userid = 0, ?stdClass $fielddata = null): profile_field_base {
 620     global $CFG;
 621
 622     require_once("{$CFG->dirroot}/user/profile/field/{$type}/field.class.php");
 623
 624     // Return instance of profile field type.
 625     $profilefieldtype = "profile_field_{$type}";
 626     return new $profilefieldtype($fieldid, $userid, $fielddata);
 627 }
 628
 629 /**
 630  * Returns an array of all custom field records with any defined data (or empty data), for the specified user id.
 631  * @param int $userid
 632  * @return profile_field_base[]
 633  */
 634 function profile_get_user_fields_with_data(int $userid): array {
 635     global $DB;
 636
 637     // Join any user info data present with each user info field for the user object.
 638     $sql = 'SELECT uif.*, uic.name AS categoryname ';
 639     if ($userid > 0) {
 640         $sql .= ', uind.id AS hasuserdata, uind.data, uind.dataformat ';
 641     }
 642     $sql .= 'FROM {user_info_field} uif ';
 643     $sql .= 'LEFT JOIN {user_info_category} uic ON uif.categoryid = uic.id ';
 644     if ($userid > 0) {
 645         $sql .= 'LEFT JOIN {user_info_data} uind ON uif.id = uind.fieldid AND uind.userid = :userid ';
 646     }
 647     $sql .= 'ORDER BY uic.sortorder ASC, uif.sortorder ASC ';
 648     $fields = $DB->get_records_sql($sql, ['userid' => $userid]);
 649     $data = [];
 650     foreach ($fields as $field) {
 651         $field->hasuserdata = !empty($field->hasuserdata);
 652         $fieldobject = profile_get_user_field($field->datatype, $field->id, $userid, $field);
 653         $fieldobject->set_category_name($field->categoryname);
 654         unset($field->categoryname);
 655         $data[] = $fieldobject;
 656     }
 657     return $data;
 658 }
 659
 660 /**
 661  * Returns an array of all custom field records with any defined data (or empty data), for the specified user id, by category.
 662  * @param int $userid
 663  * @return profile_field_base[][]
 664  */
 665 function profile_get_user_fields_with_data_by_category(int $userid): array {
 666     $fields = profile_get_user_fields_with_data($userid);
 667     $data = [];
 668     foreach ($fields as $field) {
 669         $data[$field->field->categoryid][] = $field;
 670     }
 671     return $data;
 672 }
 673
 674 /**
 675  * Loads user profile field data into the user object.
 676  * @param stdClass $user
 677  */
 678 function profile_load_data(stdClass $user): void {
 679     $fields = profile_get_user_fields_with_data($user->id);
 680     foreach ($fields as $formfield) {
 681         $formfield->edit_load_user_data($user);
 682     }
 683 }
 684
 685 /**
 686  * Print out the customisable categories and fields for a users profile
 687  *
 688  * @param MoodleQuickForm $mform instance of the moodleform class
 689  * @param int $userid id of user whose profile is being edited or 0 for the new user
 690  */
 691 function profile_definition(MoodleQuickForm $mform, int $userid = 0): void {
 692     $categories = profile_get_user_fields_with_data_by_category($userid);
 693     foreach ($categories as $categoryid => $fields) {
 694         // Check first if *any* fields will be displayed.
 695         $fieldstodisplay = [];
 696
 697         foreach ($fields as $formfield) {
 698             if ($formfield->is_editable()) {
 699                 $fieldstodisplay[] = $formfield;
 700             }
 701         }
 702
 703         if (empty($fieldstodisplay)) {
 704             continue;
 705         }
 706
 707         // Display the header and the fields.
 708         $mform->addElement('header', 'category_'.$categoryid, format_string($fields[0]->get_category_name()));
 709         foreach ($fieldstodisplay as $formfield) {
 710             $formfield->edit_field($mform);
 711         }
 712     }
 713 }
 714
 715 /**
 716  * Adds profile fields to user edit forms.
 717  * @param MoodleQuickForm $mform
 718  * @param int $userid
 719  */
 720 function profile_definition_after_data(MoodleQuickForm $mform, int $userid): void {
 721     $userid = ($userid < 0) ? 0 : (int)$userid;
 722
 723     $fields = profile_get_user_fields_with_data($userid);
 724     foreach ($fields as $formfield) {
 725         $formfield->edit_after_data($mform);
 726     }
 727 }
 728
 729 /**
 730  * Validates profile data.
 731  * @param stdClass $usernew
 732  * @param array $files
 733  * @return array array of errors, same as in {@see moodleform::validation()}
 734  */
 735 function profile_validation(stdClass $usernew, array $files): array {
 736     $err = array();
 737     $fields = profile_get_user_fields_with_data($usernew->id);
 738     foreach ($fields as $formfield) {
 739         $err += $formfield->edit_validate_field($usernew, $files);
 740     }
 741     return $err;
 742 }
 743
 744 /**
 745  * Saves profile data for a user.
 746  * @param stdClass $usernew
 747  */
 748 function profile_save_data(stdClass $usernew): void {
 749     global $CFG;
 750
 751     $fields = profile_get_user_fields_with_data($usernew->id);
 752     foreach ($fields as $formfield) {
 753         $formfield->edit_save_data($usernew);
 754     }
 755 }
 756
 757 /**
 758  * Retrieves a list of profile fields that must be displayed in the sign-up form.
 759  *
 760  * @return array list of profile fields info
 761  * @since Moodle 3.2
 762  */
 763 function profile_get_signup_fields(): array {
 764     $profilefields = array();
 765     $fieldobjects = profile_get_user_fields_with_data(0);
 766     foreach ($fieldobjects as $fieldobject) {
 767         $field = (object)$fieldobject->get_field_config_for_external();
 768         if ($fieldobject->get_category_name() !== null && $fieldobject->is_signup_field() && $field->visible <> 0) {
 769             $profilefields[] = (object) array(
 770                 'categoryid' => $field->categoryid,
 771                 'categoryname' => $fieldobject->get_category_name(),
 772                 'fieldid' => $field->id,
 773                 'datatype' => $field->datatype,
 774                 'object' => $fieldobject
 775             );
 776         }
 777     }
 778     return $profilefields;
 779 }
 780
 781 /**
 782  * Adds code snippet to a moodle form object for custom profile fields that
 783  * should appear on the signup page
 784  * @param MoodleQuickForm $mform moodle form object
 785  */
 786 function profile_signup_fields(MoodleQuickForm $mform): void {
 787
 788     if ($fields = profile_get_signup_fields()) {
 789         foreach ($fields as $field) {
 790             // Check if we change the categories.
 791             if (!isset($currentcat) || $currentcat != $field->categoryid) {
 792                  $currentcat = $field->categoryid;
 793                  $mform->addElement('header', 'category_'.$field->categoryid, format_string($field->categoryname));
 794             };
 795             $field->object->edit_field($mform);
 796         }
 797     }
 798 }
 799
 800 /**
 801  * Returns an object with the custom profile fields set for the given user
 802  * @param int $userid
 803  * @param bool $onlyinuserobject True if you only want the ones in $USER.
 804  * @return stdClass object where properties names are shortnames of custom profile fields
 805  */
 806 function profile_user_record(int $userid, bool $onlyinuserobject = true): stdClass {
 807     $usercustomfields = new stdClass();
 808
 809     $fields = profile_get_user_fields_with_data($userid);
 810     foreach ($fields as $formfield) {
 811         if (!$onlyinuserobject || $formfield->is_user_object_data()) {
 812             $usercustomfields->{$formfield->field->shortname} = $formfield->data;
 813         }
 814     }
 815
 816     return $usercustomfields;
 817 }
 818
 819 /**
 820  * Obtains a list of all available custom profile fields, indexed by id.
 821  *
 822  * Some profile fields are not included in the user object data (see
 823  * profile_user_record function above). Optionally, you can obtain only those
 824  * fields that are included in the user object.
 825  *
 826  * To be clear, this function returns the available fields, and does not
 827  * return the field values for a particular user.
 828  *
 829  * @param bool $onlyinuserobject True if you only want the ones in $USER
 830  * @return array Array of field objects from database (indexed by id)
 831  * @since Moodle 2.7.1
 832  */
 833 function profile_get_custom_fields(bool $onlyinuserobject = false): array {
 834     $fieldobjects = profile_get_user_fields_with_data(0);
 835     $fields = [];
 836     foreach ($fieldobjects as $fieldobject) {
 837         if (!$onlyinuserobject || $fieldobject->is_user_object_data()) {
 838             $fields[$fieldobject->fieldid] = (object)$fieldobject->get_field_config_for_external();
 839         }
 840     }
 841     ksort($fields);
 842     return $fields;
 843 }
 844
 845 /**
 846  * Load custom profile fields into user object
 847  *
 848  * @param stdClass $user user object
 849  */
 850 function profile_load_custom_fields($user) {
 851     $user->profile = (array)profile_user_record($user->id);
 852 }
 853
 854 /**
 855  * Save custom profile fields for a user.
 856  *
 857  * @param int $userid The user id
 858  * @param array $profilefields The fields to save
 859  */
 860 function profile_save_custom_fields($userid, $profilefields) {
 861     global $DB;
 862
 863     $fields = profile_get_user_fields_with_data(0);
 864     if ($fields) {
 865         foreach ($fields as $fieldobject) {
 866             $field = (object)$fieldobject->get_field_config_for_external();
 867             if (isset($profilefields[$field->shortname])) {
 868                 $conditions = array('fieldid' => $field->id, 'userid' => $userid);
 869                 $id = $DB->get_field('user_info_data', 'id', $conditions);
 870                 $data = $profilefields[$field->shortname];
 871                 if ($id) {
 872                     $DB->set_field('user_info_data', 'data', $data, array('id' => $id));
 873                 } else {
 874                     $record = array('fieldid' => $field->id, 'userid' => $userid, 'data' => $data);
 875                     $DB->insert_record('user_info_data', $record);
 876                 }
 877             }
 878         }
 879     }
 880 }
 881
 882 /**
 883  * Gets basic data about custom profile fields. This is minimal data that is cached within the
 884  * current request for all fields so that it can be used quickly.
 885  *
 886  * @param string $shortname Shortname of custom profile field
 887  * @param bool $casesensitive Whether to perform case-sensitive matching of shortname. Note current limitations of custom profile
 888  *  fields allow the same shortname to exist differing only by it's case
 889  * @return stdClass|null Object with properties id, shortname, name, visible, datatype, categoryid, etc
 890  */
 891 function profile_get_custom_field_data_by_shortname(string $shortname, bool $casesensitive = true): ?stdClass {
 892     $cache = \cache::make_from_params(cache_store::MODE_REQUEST, 'core_profile', 'customfields',
 893             [], ['simplekeys' => true, 'simpledata' => true]);
 894     $data = $cache->get($shortname);
 895     if ($data === false) {
 896         // If we don't have data, we get and cache it for all fields to avoid multiple DB requests.
 897         $fields = profile_get_custom_fields();
 898         $data = null;
 899         foreach ($fields as $field) {
 900             $cache->set($field->shortname, $field);
 901
 902             // Perform comparison according to case sensitivity parameter.
 903             $shortnamematch = $casesensitive
 904                 ? strcmp($field->shortname, $shortname) === 0
 905                 : strcasecmp($field->shortname, $shortname) === 0;
 906
 907             if ($shortnamematch) {
 908                 $data = $field;
 909             }
 910         }
 911     }
 912
 913     return $data;
 914 }
 915
 916 /**
 917  * Trigger a user profile viewed event.
 918  *
 919  * @param stdClass  $user user  object
 920  * @param stdClass  $context  context object (course or user)
 921  * @param stdClass  $course course  object
 922  * @since Moodle 2.9
 923  */
 924 function profile_view($user, $context, $course = null) {
 925
 926     $eventdata = array(
 927         'objectid' => $user->id,
 928         'relateduserid' => $user->id,
 929         'context' => $context
 930     );
 931
 932     if (!empty($course)) {
 933         $eventdata['courseid'] = $course->id;
 934         $eventdata['other'] = array(
 935             'courseid' => $course->id,
 936             'courseshortname' => $course->shortname,
 937             'coursefullname' => $course->fullname
 938         );
 939     }
 940
 941     $event = \core\event\user_profile_viewed::create($eventdata);
 942     $event->add_record_snapshot('user', $user);
 943     $event->trigger();
 944 }
 945
 946 /**
 947  * Does the user have all required custom fields set?
 948  *
 949  * Internal, to be exclusively used by {@link user_not_fully_set_up()} only.
 950  *
 951  * Note that if users have no way to fill a required field via editing their
 952  * profiles (e.g. the field is not visible or it is locked), we still return true.
 953  * So this is actually checking if we should redirect the user to edit their
 954  * profile, rather than whether there is a value in the database.
 955  *
 956  * @param int $userid
 957  * @return bool
 958  */
 959 function profile_has_required_custom_fields_set($userid) {
 960     $profilefields = profile_get_user_fields_with_data($userid);
 961     foreach ($profilefields as $profilefield) {
 962         if ($profilefield->is_required() && !$profilefield->is_locked() &&
 963             $profilefield->is_empty() && $profilefield->get_field_config_for_external()['visible']) {
 964             return false;
 965         }
 966     }
 967
 968     return true;
 969 }
 970
 971 /**
 972  * Return the list of valid custom profile user fields.
 973  *
 974  * @return array array of profile field names
 975  */
 976 function get_profile_field_names(): array {
 977     $profilefields = profile_get_user_fields_with_data(0);
 978     $profilefieldnames = [];
 979     foreach ($profilefields as $field) {
 980         $profilefieldnames[] = $field->inputname;
 981     }
 982     return $profilefieldnames;
 983 }
 984
 985 /**
 986  * Return the list of profile fields
 987  * in a format they can be used for choices in a group select menu.
 988  *
 989  * @return array array of category name with its profile fields
 990  */
 991 function get_profile_field_list(): array {
 992     $customfields = profile_get_user_fields_with_data_by_category(0);
 993     $data = [];
 994     foreach ($customfields as $category) {
 995         foreach ($category as $field) {
 996             $categoryname = $field->get_category_name();
 997             if (!isset($data[$categoryname])) {
 998                 $data[$categoryname] = [];
 999             }
1000             $data[$categoryname][$field->inputname] = $field->field->name;
1001         }
1002     }
1003     return $data;
1004 }