2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Profile field API library file.
21 * @copyright 2007 onwards Shane Elliot {@link http://pukunui.com}
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 * Visible to anyone who can view the user.
27 * Editable by the profile owner if they have the moodle/user:editownprofile capability
28 * or any user with the moodle/user:update capability.
30 define('PROFILE_VISIBLE_ALL', '2');
32 * Visible to the profile owner or anyone with the moodle/user:viewalldetails capability.
33 * Editable by the profile owner if they have the moodle/user:editownprofile capability
34 * or any user with moodle/user:viewalldetails and moodle/user:update capabilities.
36 define('PROFILE_VISIBLE_PRIVATE', '1');
38 * Only visible to users with the moodle/user:viewalldetails capability.
39 * Only editable by users with the moodle/user:viewalldetails and moodle/user:update capabilities.
41 define('PROFILE_VISIBLE_NONE', '0');
44 * Base class for the customisable profile fields.
47 * @copyright 2007 onwards Shane Elliot {@link http://pukunui.com}
48 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
50 class profile_field_base
{
52 // These 2 variables are really what we're interested in.
53 // Everything else can be extracted from them.
73 /** @var string name of the user profile category */
74 protected $categoryname;
78 * @param int $fieldid id of the profile from the user_info_field table
79 * @param int $userid id of the user for whom we are displaying data
80 * @param object $fielddata optional data for the field object plus additional fields 'hasuserdata', 'data' and 'dataformat'
81 * with user data. (If $fielddata->hasuserdata is empty, user data is not available and we should use default data).
82 * If this parameter is passed, constructor will not call load_data() at all.
84 public function __construct($fieldid=0, $userid=0, $fielddata=null) {
87 if ($CFG->debugdeveloper
) {
88 // In Moodle 3.4 the new argument $fielddata was added to the constructor. Make sure that
89 // plugin constructor properly passes this argument.
90 $backtrace = debug_backtrace();
91 if (isset($backtrace[1]['class']) && $backtrace[1]['function'] === '__construct' &&
92 in_array(self
::class, class_parents($backtrace[1]['class']))) {
93 // If this constructor is called from the constructor of the plugin make sure that the third argument was passed through.
94 if (count($backtrace[1]['args']) >= 3 && count($backtrace[0]['args']) < 3) {
95 debugging($backtrace[1]['class'].'::__construct() must support $fielddata as the third argument ' .
96 'and pass it to the parent constructor', DEBUG_DEVELOPER
);
101 $this->set_fieldid($fieldid);
102 $this->set_userid($userid);
104 $this->set_field($fielddata);
105 if ($userid > 0 && !empty($fielddata->hasuserdata
)) {
106 $this->set_user_data($fielddata->data
, $fielddata->dataformat
);
114 * Old syntax of class constructor. Deprecated in PHP7.
116 * @deprecated since Moodle 3.1
118 public function profile_field_base($fieldid=0, $userid=0) {
119 debugging('Use of class name as constructor is deprecated', DEBUG_DEVELOPER
);
120 self
::__construct($fieldid, $userid);
124 * Abstract method: Adds the profile field to the moodle form class
125 * @abstract The following methods must be overwritten by child classes
126 * @param moodleform $mform instance of the moodleform class
128 public function edit_field_add($mform) {
129 print_error('mustbeoveride', 'debug', '', 'edit_field_add');
133 * Display the data for this field
136 public function display_data() {
137 $options = new stdClass();
138 $options->para
= false;
139 return format_text($this->data
, FORMAT_MOODLE
, $options);
143 * Print out the form field in the edit profile page
144 * @param moodleform $mform instance of the moodleform class
147 public function edit_field($mform) {
148 if (!$this->is_editable()) {
152 $this->edit_field_add($mform);
153 $this->edit_field_set_default($mform);
154 $this->edit_field_set_required($mform);
159 * Tweaks the edit form
160 * @param moodleform $mform instance of the moodleform class
163 public function edit_after_data($mform) {
164 if (!$this->is_editable()) {
168 $this->edit_field_set_locked($mform);
173 * Saves the data coming from form
174 * @param stdClass $usernew data coming from the form
175 * @return mixed returns data id if success of db insert/update, false on fail, 0 if not permitted
177 public function edit_save_data($usernew) {
180 if (!isset($usernew->{$this->inputname
})) {
181 // Field not present in form, probably locked and invisible - skip it.
185 $data = new stdClass();
187 $usernew->{$this->inputname
} = $this->edit_save_data_preprocess($usernew->{$this->inputname
}, $data);
189 $data->userid
= $usernew->id
;
190 $data->fieldid
= $this->field
->id
;
191 $data->data
= $usernew->{$this->inputname
};
193 if ($dataid = $DB->get_field('user_info_data', 'id', array('userid' => $data->userid
, 'fieldid' => $data->fieldid
))) {
195 $DB->update_record('user_info_data', $data);
197 $DB->insert_record('user_info_data', $data);
202 * Validate the form field from profile page
204 * @param stdClass $usernew
205 * @return string contains error message otherwise null
207 public function edit_validate_field($usernew) {
212 if (isset($usernew->{$this->inputname
})) {
213 if (is_array($usernew->{$this->inputname
}) && isset($usernew->{$this->inputname
}['text'])) {
214 $value = $usernew->{$this->inputname
}['text'];
216 $value = $usernew->{$this->inputname
};
222 // Check for uniqueness of data if required.
223 if ($this->is_unique() && (($value !== '') ||
$this->is_required())) {
224 $data = $DB->get_records_sql('
226 FROM {user_info_data}
228 AND ' . $DB->sql_compare_text('data', 255) . ' = ' . $DB->sql_compare_text('?', 255),
229 array($this->field
->id
, $value));
232 foreach ($data as $v) {
233 if ($v->userid
== $usernew->id
) {
239 $errors[$this->inputname
] = get_string('valuealreadyused');
247 * Sets the default data for the field in the form object
248 * @param moodleform $mform instance of the moodleform class
250 public function edit_field_set_default($mform) {
251 if (!empty($this->field
->defaultdata
)) {
252 $mform->setDefault($this->inputname
, $this->field
->defaultdata
);
257 * Sets the required flag for the field in the form object
259 * @param moodleform $mform instance of the moodleform class
261 public function edit_field_set_required($mform) {
263 if ($this->is_required() && ($this->userid
== $USER->id ||
isguestuser())) {
264 $mform->addRule($this->inputname
, get_string('required'), 'required', null, 'client');
269 * HardFreeze the field if locked.
270 * @param moodleform $mform instance of the moodleform class
272 public function edit_field_set_locked($mform) {
273 if (!$mform->elementExists($this->inputname
)) {
276 if ($this->is_locked() and !has_capability('moodle/user:update', context_system
::instance())) {
277 $mform->hardFreeze($this->inputname
);
278 $mform->setConstant($this->inputname
, $this->data
);
283 * Hook for child classess to process the data before it gets saved in database
284 * @param stdClass $data
285 * @param stdClass $datarecord The object that will be used to save the record
288 public function edit_save_data_preprocess($data, $datarecord) {
293 * Loads a user object with data for this field ready for the edit profile
295 * @param stdClass $user a user object
297 public function edit_load_user_data($user) {
298 if ($this->data
!== null) {
299 $user->{$this->inputname
} = $this->data
;
304 * Check if the field data should be loaded into the user object
305 * By default it is, but for field types where the data may be potentially
306 * large, the child class should override this and return false
309 public function is_user_object_data() {
314 * Accessor method: set the userid for this instance
315 * @internal This method should not generally be overwritten by child classes.
316 * @param integer $userid id from the user table
318 public function set_userid($userid) {
319 $this->userid
= $userid;
323 * Accessor method: set the fieldid for this instance
324 * @internal This method should not generally be overwritten by child classes.
325 * @param integer $fieldid id from the user_info_field table
327 public function set_fieldid($fieldid) {
328 $this->fieldid
= $fieldid;
332 * Sets the field object and default data and format into $this->data and $this->dataformat
334 * This method should be called before {@link self::set_user_data}
336 * @param stdClass $field
337 * @throws coding_exception
339 public function set_field($field) {
341 if ($CFG->debugdeveloper
) {
342 $properties = ['id', 'shortname', 'name', 'datatype', 'description', 'descriptionformat', 'categoryid', 'sortorder',
343 'required', 'locked', 'visible', 'forceunique', 'signup', 'defaultdata', 'defaultdataformat', 'param1', 'param2',
344 'param3', 'param4', 'param5'];
345 foreach ($properties as $property) {
346 if (!property_exists($field, $property)) {
347 debugging('The \'' . $property . '\' property must be set.', DEBUG_DEVELOPER
);
351 if ($this->fieldid
&& $this->fieldid
!= $field->id
) {
352 throw new coding_exception('Can not set field object after a different field id was set');
354 $this->fieldid
= $field->id
;
355 $this->field
= $field;
356 $this->inputname
= 'profile_field_' . $this->field
->shortname
;
357 $this->data
= $this->field
->defaultdata
;
358 $this->dataformat
= FORMAT_HTML
;
362 * Sets user id and user data for the field
365 * @param int $dataformat
367 public function set_user_data($data, $dataformat) {
369 $this->dataformat
= $dataformat;
373 * Set the name for the profile category where this field is
375 * @param string $categoryname
377 public function set_category_name($categoryname) {
378 $this->categoryname
= $categoryname;
382 * Returns the name of the profile category where this field is
386 public function get_category_name() {
388 if ($this->categoryname
=== null) {
389 $this->categoryname
= $DB->get_field('user_info_category', 'name', ['id' => $this->field
->categoryid
]);
391 return $this->categoryname
;
395 * Accessor method: Load the field record and user data associated with the
396 * object's fieldid and userid
398 * @internal This method should not generally be overwritten by child classes.
400 public function load_data() {
403 // Load the field object.
404 if (($this->fieldid
== 0) or (!($field = $DB->get_record('user_info_field', array('id' => $this->fieldid
))))) {
406 $this->inputname
= '';
408 $this->set_field($field);
411 if (!empty($this->field
) && $this->userid
> 0) {
412 $params = array('userid' => $this->userid
, 'fieldid' => $this->fieldid
);
413 if ($data = $DB->get_record('user_info_data', $params, 'data, dataformat')) {
414 $this->set_user_data($data->data
, $data->dataformat
);
422 * Check if the field data is visible to the current user
423 * @internal This method should not generally be overwritten by child classes.
426 public function is_visible() {
429 $context = ($this->userid
> 0) ? context_user
::instance($this->userid
) : context_system
::instance();
431 switch ($this->field
->visible
) {
432 case PROFILE_VISIBLE_ALL
:
434 case PROFILE_VISIBLE_PRIVATE
:
435 if ($this->is_signup_field() && (empty($this->userid
) ||
isguestuser($this->userid
))) {
437 } else if ($this->userid
== $USER->id
) {
440 return has_capability('moodle/user:viewalldetails', $context);
443 return has_capability('moodle/user:viewalldetails', $context);
448 * Check if the field data is editable for the current user
449 * This method should not generally be overwritten by child classes.
452 public function is_editable() {
455 if (!$this->is_visible()) {
459 if ($this->is_signup_field() && (empty($this->userid
) ||
isguestuser($this->userid
))) {
460 // Allow editing the field on the signup page.
464 $systemcontext = context_system
::instance();
466 if ($this->userid
== $USER->id
&& has_capability('moodle/user:editownprofile', $systemcontext)) {
470 if (has_capability('moodle/user:update', $systemcontext)) {
478 * Check if the field data is considered empty
479 * @internal This method should not generally be overwritten by child classes.
482 public function is_empty() {
483 return ( ($this->data
!= '0') and empty($this->data
));
487 * Check if the field is required on the edit profile page
488 * @internal This method should not generally be overwritten by child classes.
491 public function is_required() {
492 return (boolean
)$this->field
->required
;
496 * Check if the field is locked on the edit profile page
497 * @internal This method should not generally be overwritten by child classes.
500 public function is_locked() {
501 return (boolean
)$this->field
->locked
;
505 * Check if the field data should be unique
506 * @internal This method should not generally be overwritten by child classes.
509 public function is_unique() {
510 return (boolean
)$this->field
->forceunique
;
514 * Check if the field should appear on the signup page
515 * @internal This method should not generally be overwritten by child classes.
518 public function is_signup_field() {
519 return (boolean
)$this->field
->signup
;
523 * Return the field settings suitable to be exported via an external function.
524 * By default it return all the field settings.
526 * @return array all the settings
529 public function get_field_config_for_external() {
530 return (array) $this->field
;
534 * Return the field type and null properties.
535 * This will be used for validating the data submitted by a user.
537 * @return array the param type and null property
540 public function get_field_properties() {
541 return array(PARAM_RAW
, NULL_NOT_ALLOWED
);
546 * Returns an array of all custom field records with any defined data (or empty data), for the specified user id.
548 * @return profile_field_base[]
550 function profile_get_user_fields_with_data($userid) {
553 // Join any user info data present with each user info field for the user object.
554 $sql = 'SELECT uif.*, uic.name AS categoryname ';
556 $sql .= ', uind.id AS hasuserdata, uind.data, uind.dataformat ';
558 $sql .= 'FROM {user_info_field} uif ';
559 $sql .= 'LEFT JOIN {user_info_category} uic ON uif.categoryid = uic.id ';
561 $sql .= 'LEFT JOIN {user_info_data} uind ON uif.id = uind.fieldid AND uind.userid = :userid ';
563 $sql .= 'ORDER BY uic.sortorder ASC, uif.sortorder ASC ';
564 $fields = $DB->get_records_sql($sql, ['userid' => $userid]);
566 foreach ($fields as $field) {
567 require_once($CFG->dirroot
. '/user/profile/field/' . $field->datatype
. '/field.class.php');
568 $classname = 'profile_field_' . $field->datatype
;
569 $field->hasuserdata
= !empty($field->hasuserdata
);
570 /** @var profile_field_base $fieldobject */
571 $fieldobject = new $classname($field->id
, $userid, $field);
572 $fieldobject->set_category_name($field->categoryname
);
573 unset($field->categoryname
);
574 $data[] = $fieldobject;
580 * Returns an array of all custom field records with any defined data (or empty data), for the specified user id, by category.
582 * @return profile_field_base[][]
584 function profile_get_user_fields_with_data_by_category($userid) {
585 $fields = profile_get_user_fields_with_data($userid);
587 foreach ($fields as $field) {
588 $data[$field->field
->categoryid
][] = $field;
594 * Loads user profile field data into the user object.
595 * @param stdClass $user
597 function profile_load_data($user) {
600 $fields = profile_get_user_fields_with_data($user->id
);
601 foreach ($fields as $formfield) {
602 $formfield->edit_load_user_data($user);
607 * Print out the customisable categories and fields for a users profile
609 * @param moodleform $mform instance of the moodleform class
610 * @param int $userid id of user whose profile is being edited.
612 function profile_definition($mform, $userid = 0) {
613 $categories = profile_get_user_fields_with_data_by_category($userid);
614 foreach ($categories as $categoryid => $fields) {
615 // Check first if *any* fields will be displayed.
616 $fieldstodisplay = [];
618 foreach ($fields as $formfield) {
619 if ($formfield->is_editable()) {
620 $fieldstodisplay[] = $formfield;
624 if (empty($fieldstodisplay)) {
628 // Display the header and the fields.
629 $mform->addElement('header', 'category_'.$categoryid, format_string($fields[0]->get_category_name()));
630 foreach ($fieldstodisplay as $formfield) {
631 $formfield->edit_field($mform);
637 * Adds profile fields to user edit forms.
638 * @param moodleform $mform
641 function profile_definition_after_data($mform, $userid) {
644 $userid = ($userid < 0) ?
0 : (int)$userid;
646 $fields = profile_get_user_fields_with_data($userid);
647 foreach ($fields as $formfield) {
648 $formfield->edit_after_data($mform);
653 * Validates profile data.
654 * @param stdClass $usernew
655 * @param array $files
658 function profile_validation($usernew, $files) {
662 $fields = profile_get_user_fields_with_data($usernew->id
);
663 foreach ($fields as $formfield) {
664 $err +
= $formfield->edit_validate_field($usernew, $files);
670 * Saves profile data for a user.
671 * @param stdClass $usernew
673 function profile_save_data($usernew) {
676 $fields = profile_get_user_fields_with_data($usernew->id
);
677 foreach ($fields as $formfield) {
678 $formfield->edit_save_data($usernew);
683 * Display profile fields.
686 function profile_display_fields($userid) {
687 global $CFG, $USER, $DB;
689 $categories = profile_get_user_fields_with_data_by_category($userid);
690 foreach ($categories as $categoryid => $fields) {
691 foreach ($fields as $formfield) {
692 if ($formfield->is_visible() and !$formfield->is_empty()) {
693 echo html_writer
::tag('dt', format_string($formfield->field
->name
));
694 echo html_writer
::tag('dd', $formfield->display_data());
701 * Retrieves a list of profile fields that must be displayed in the sign-up form.
703 * @return array list of profile fields info
706 function profile_get_signup_fields() {
709 $profilefields = array();
710 // Only retrieve required custom fields (with category information)
711 // results are sort by categories, then by fields.
712 $sql = "SELECT uf.id as fieldid, ic.id as categoryid, ic.name as categoryname, uf.datatype
713 FROM {user_info_field} uf
714 JOIN {user_info_category} ic
715 ON uf.categoryid = ic.id AND uf.signup = 1 AND uf.visible<>0
716 ORDER BY ic.sortorder ASC, uf.sortorder ASC";
718 if ($fields = $DB->get_records_sql($sql)) {
719 foreach ($fields as $field) {
720 require_once($CFG->dirroot
.'/user/profile/field/'.$field->datatype
.'/field.class.php');
721 $newfield = 'profile_field_'.$field->datatype
;
722 $fieldobject = new $newfield($field->fieldid
);
724 $profilefields[] = (object) array(
725 'categoryid' => $field->categoryid
,
726 'categoryname' => $field->categoryname
,
727 'fieldid' => $field->fieldid
,
728 'datatype' => $field->datatype
,
729 'object' => $fieldobject
733 return $profilefields;
737 * Adds code snippet to a moodle form object for custom profile fields that
738 * should appear on the signup page
739 * @param moodleform $mform moodle form object
741 function profile_signup_fields($mform) {
743 if ($fields = profile_get_signup_fields()) {
744 foreach ($fields as $field) {
745 // Check if we change the categories.
746 if (!isset($currentcat) ||
$currentcat != $field->categoryid
) {
747 $currentcat = $field->categoryid
;
748 $mform->addElement('header', 'category_'.$field->categoryid
, format_string($field->categoryname
));
750 $field->object->edit_field($mform);
756 * Returns an object with the custom profile fields set for the given user
757 * @param integer $userid
758 * @param bool $onlyinuserobject True if you only want the ones in $USER.
761 function profile_user_record($userid, $onlyinuserobject = true) {
764 $usercustomfields = new stdClass();
766 $fields = profile_get_user_fields_with_data($userid);
767 foreach ($fields as $formfield) {
768 if (!$onlyinuserobject ||
$formfield->is_user_object_data()) {
769 $usercustomfields->{$formfield->field
->shortname
} = $formfield->data
;
773 return $usercustomfields;
777 * Obtains a list of all available custom profile fields, indexed by id.
779 * Some profile fields are not included in the user object data (see
780 * profile_user_record function above). Optionally, you can obtain only those
781 * fields that are included in the user object.
783 * To be clear, this function returns the available fields, and does not
784 * return the field values for a particular user.
786 * @param bool $onlyinuserobject True if you only want the ones in $USER
787 * @return array Array of field objects from database (indexed by id)
788 * @since Moodle 2.7.1
790 function profile_get_custom_fields($onlyinuserobject = false) {
793 // Get all the fields.
794 $fields = $DB->get_records('user_info_field', null, 'id ASC');
796 // If only doing the user object ones, unset the rest.
797 if ($onlyinuserobject) {
798 foreach ($fields as $id => $field) {
799 require_once($CFG->dirroot
. '/user/profile/field/' .
800 $field->datatype
. '/field.class.php');
801 $newfield = 'profile_field_' . $field->datatype
;
802 $formfield = new $newfield();
803 if (!$formfield->is_user_object_data()) {
813 * Load custom profile fields into user object
815 * @param stdClass $user user object
817 function profile_load_custom_fields($user) {
818 $user->profile
= (array)profile_user_record($user->id
);
822 * Save custom profile fields for a user.
824 * @param int $userid The user id
825 * @param array $profilefields The fields to save
827 function profile_save_custom_fields($userid, $profilefields) {
830 if ($fields = $DB->get_records('user_info_field')) {
831 foreach ($fields as $field) {
832 if (isset($profilefields[$field->shortname
])) {
833 $conditions = array('fieldid' => $field->id
, 'userid' => $userid);
834 $id = $DB->get_field('user_info_data', 'id', $conditions);
835 $data = $profilefields[$field->shortname
];
837 $DB->set_field('user_info_data', 'data', $data, array('id' => $id));
839 $record = array('fieldid' => $field->id
, 'userid' => $userid, 'data' => $data);
840 $DB->insert_record('user_info_data', $record);
848 * Trigger a user profile viewed event.
850 * @param stdClass $user user object
851 * @param stdClass $context context object (course or user)
852 * @param stdClass $course course object
855 function profile_view($user, $context, $course = null) {
858 'objectid' => $user->id
,
859 'relateduserid' => $user->id
,
860 'context' => $context
863 if (!empty($course)) {
864 $eventdata['courseid'] = $course->id
;
865 $eventdata['other'] = array(
866 'courseid' => $course->id
,
867 'courseshortname' => $course->shortname
,
868 'coursefullname' => $course->fullname
872 $event = \core\event\user_profile_viewed
::create($eventdata);
873 $event->add_record_snapshot('user', $user);
878 * Does the user have all required custom fields set?
880 * Internal, to be exclusively used by {@link user_not_fully_set_up()} only.
882 * Note that if users have no way to fill a required field via editing their
883 * profiles (e.g. the field is not visible or it is locked), we still return true.
884 * So this is actually checking if we should redirect the user to edit their
885 * profile, rather than whether there is a value in the database.
890 function profile_has_required_custom_fields_set($userid) {
894 FROM {user_info_field} f
895 LEFT JOIN {user_info_data} d ON (d.fieldid = f.id AND d.userid = ?)
896 WHERE f.required = 1 AND f.visible > 0 AND f.locked = 0 AND d.id IS NULL";
898 if ($DB->record_exists_sql($sql, [$userid])) {