Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
core_user Class Reference

User class to access user details. More...

Static Public Member Functions

static awaiting_action (stdClass $user=null)
 Is the user expected to perform an action to start using Moodle properly?
 
static can_edit_preference ($preferencename, $user)
 Can current user edit preference of this/another user.
 
static clean_data ($user)
 Clean the user data.
 
static clean_field ($data, $field)
 Clean a specific user field.
 
static clean_preference ($value, $preferencename)
 Clean value of a user preference.
 
static get_initials (stdClass $user)
 Get initials for users.
 
static get_noreply_user ()
 Return noreply user record, this is currently used in messaging system only for sending messages from noreply email.
 
static get_property_choices ($property)
 Get the choices of the property.
 
static get_property_default ($property)
 Get the property default.
 
static get_property_definition ($property)
 Get properties of a user field.
 
static get_property_null ($property)
 Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
 
static get_property_type ($property)
 Get the parameter type of the property.
 
static get_support_user ()
 Return support user record, this is currently used in messaging system only for sending messages to support email.
 
static get_user ($userid, $fields=' *', $strictness=IGNORE_MISSING)
 Return user object from db or create noreply or support user, if userid matches corse_user\NOREPLY_USER or corse_user\SUPPORT_USER respectively.
 
static get_user_by_email ($email, $fields=' *', $mnethostid=null, $strictness=IGNORE_MISSING)
 Return user object from db based on their email.
 
static get_user_by_username ($username, $fields=' *', $mnethostid=null, $strictness=IGNORE_MISSING)
 Return user object from db based on their username.
 
static is_current_user (stdClass $user)
 Determine whether the given user ID is that of the current user.
 
static is_real_user ($userid, $checkdb=false)
 Return true if user id is greater than 0 and alternatively check db.
 
static require_active_user ($user, $checksuspended=false, $checknologin=false)
 Check if the given user is an active user in the site.
 
static reset_caches ()
 Clean the properties cache.
 
static reset_internal_users ()
 Reset self\$noreplyuser and self\$supportuser.
 
static search ($query, context_course $coursecontext=null, $max=30, $querylimit=5)
 Searches for users by name, possibly within a specified context, with current user's access.
 
static update_picture (stdClass $usernew, $filemanageroptions=array())
 Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.
 
static validate ($data)
 Validate user data.
 
static welcome_message ()
 Get welcome message.
 

Public Attributes

const AUTHSYNCFIELDS
 List of fields that can be synched/locked during authentication.
 
const MAILDISPLAY_COURSE_MEMBERS_ONLY = 2
 Display email address to course members only.
 
const MAILDISPLAY_EVERYONE = 1
 Display email address to everyone.
 
const MAILDISPLAY_HIDE = 0
 Hide email address from everyone.
 
const NOREPLY_USER = -10
 No reply user id.
 
const SUPPORT_USER = -20
 Support user id.
 
int const VIEWPROFILE_DO_NOT_PREVENT = 0
 Indicates that user profile view should not be prevented.
 
int const VIEWPROFILE_FORCE_ALLOW = 1
 Indicates that user profile view should be allowed even if Moodle would prevent it.
 
int const VIEWPROFILE_PREVENT = -1
 Indicates that user profile view should be prevented.
 

Static Public Attributes

static stdClass $noreplyuser = false
 keep record of noreply user
 
static stdClass $supportuser = false
 keep record of support user
 

Static Protected Member Functions

static default_preference_permission_check ($user, $preferencename)
 Default callback used for checking if current user is allowed to change permission of user $user.
 
static fill_preferences_cache ()
 Definition of updateable user preferences and rules for data and access validation.
 
static fill_properties_cache ()
 Definition of user profile fields and the expected parameter type for data validation.
 
static get_dummy_user_record ()
 Helper function to return dummy noreply user record.
 
static get_enrolled_sql_on_courses_with_capability ($capability)
 Gets an SQL query that lists all enrolled user ids on any course where the current user has the specified capability.
 
static get_preference_definition ($preferencename)
 Retrieves the preference definition.
 

Static Protected Attributes

static array $preferencescache = null
 store user preferences cache.
 
static array $propertiescache = null
 store user fields properties cache.
 

Detailed Description

User class to access user details.

Todo
move api's from user/lib.php and deprecate old ones.
License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ awaiting_action()

static core_user::awaiting_action ( stdClass $user = null)
static

Is the user expected to perform an action to start using Moodle properly?

This covers cases such as filling the profile, changing password or agreeing to the site policy.

Parameters
stdClass$userUser object, defaults to the current user.
Return values
bool

◆ can_edit_preference()

static core_user::can_edit_preference ( $preferencename,
$user )
static

Can current user edit preference of this/another user.

Parameters
string$preferencename
stdClass$user
Return values
bool

◆ clean_data()

static core_user::clean_data ( $user)
static

Clean the user data.

Parameters
stdClass | array$userthe user data to be validated against properties definition.
Return values
stdClass\$userthe cleaned user data.

◆ clean_field()

static core_user::clean_field ( $data,
$field )
static

Clean a specific user field.

Parameters
string$datathe user field data to be cleaned.
string$fieldthe user field name on the property definition cache.
Return values
stringthe cleaned user data.

◆ clean_preference()

static core_user::clean_preference ( $value,
$preferencename )
static

Clean value of a user preference.

Parameters
string$valuethe user preference value to be cleaned.
string$preferencenamethe user preference name
Return values
stringthe cleaned preference value

◆ default_preference_permission_check()

static core_user::default_preference_permission_check ( $user,
$preferencename )
staticprotected

Default callback used for checking if current user is allowed to change permission of user $user.

Parameters
stdClass$user
string$preferencename
Return values
bool

◆ fill_preferences_cache()

static core_user::fill_preferences_cache ( )
staticprotected

Definition of updateable user preferences and rules for data and access validation.

array( 'preferencename' => array( // Either exact preference name or a regular expression. 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED. 'type' => PARAM_TYPE, // Expected parameter type of the user field - mandatory 'choices' => array(1, 2..) // An array of accepted values of the user field - optional 'default' => $CFG->setting // An default value for the field - optional 'isregex' => false/true // Whether the name of the preference is a regular expression (default false). 'permissioncallback' => callable // Function accepting arguments ($user, $preferencename) that checks if current user // is allowed to modify this preference for given user. // If not specified core_user\default_preference_permission_check() will be assumed. 'cleancallback' => callable // Custom callback for cleaning value if something more difficult than just type/choices is needed // accepts arguments ($value, $preferencename) ) )

Return values
void

◆ fill_properties_cache()

static core_user::fill_properties_cache ( )
staticprotected

Definition of user profile fields and the expected parameter type for data validation.

array( 'property_name' => array( // The user property to be checked. Should match the field on the user table. 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED. 'type' => PARAM_TYPE, // Expected parameter type of the user field. 'choices' => array(1, 2..) // An array of accepted values of the user field. 'default' => $CFG->setting // An default value for the field. ) )

The fields choices and default are optional.

Return values
void

◆ get_dummy_user_record()

static core_user::get_dummy_user_record ( )
staticprotected

Helper function to return dummy noreply user record.

Return values
stdClass

◆ get_enrolled_sql_on_courses_with_capability()

static core_user::get_enrolled_sql_on_courses_with_capability ( $capability)
staticprotected

Gets an SQL query that lists all enrolled user ids on any course where the current user has the specified capability.

Helper function used for searching users.

Parameters
string$capabilityRequired capability
Return values
arrayArray containing SQL and params, or two nulls if there are no courses

◆ get_initials()

static core_user::get_initials ( stdClass $user)
static

Get initials for users.

Parameters
stdClass$user
Return values
string

◆ get_noreply_user()

static core_user::get_noreply_user ( )
static

Return noreply user record, this is currently used in messaging system only for sending messages from noreply email.

It will return record of $CFG->noreplyuserid if set else return dummy user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.

Return values
stdClassuser record.

◆ get_preference_definition()

static core_user::get_preference_definition ( $preferencename)
staticprotected

Retrieves the preference definition.

Parameters
string$preferencename
Return values
array

◆ get_property_choices()

static core_user::get_property_choices ( $property)
static

Get the choices of the property.

This is a helper method to validate a value against a list of acceptable choices. For instance: country, language, themes and etc.

Parameters
string$propertyproperty name to be retrieved.
Exceptions
coding_exceptionif the requested property name is invalid or if it does not has a list of choices.
Return values
arraythe property parameter type.

◆ get_property_default()

static core_user::get_property_default ( $property)
static

Get the property default.

This method gets the default value of a field (if exists).

Parameters
string$propertyproperty name to be retrieved.
Exceptions
coding_exceptionif the requested property name is invalid or if it does not has a default value.
Return values
stringthe property default value.

◆ get_property_definition()

static core_user::get_property_definition ( $property)
static

Get properties of a user field.

Parameters
string$propertyproperty name to be retrieved.
Exceptions
coding_exceptionif the requested property name is invalid.
Return values
arraythe property definition.

◆ get_property_null()

static core_user::get_property_null ( $property)
static

Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.

Parameters
string$propertyproperty name to be retrieved.
Exceptions
coding_exceptionif the requested property name is invalid.
Return values
booltrue if the property is NULL_ALLOWED, false otherwise.

◆ get_property_type()

static core_user::get_property_type ( $property)
static

Get the parameter type of the property.

Parameters
string$propertyproperty name to be retrieved.
Exceptions
coding_exceptionif the requested property name is invalid.
Return values
intthe property parameter type.

◆ get_support_user()

static core_user::get_support_user ( )
static

Return support user record, this is currently used in messaging system only for sending messages to support email.

$CFG->supportuserid is set then returns user record $CFG->supportemail is set then return dummy record with $CFG->supportemail else return admin user record with hard-coded $user->emailstop = 0, so user gets support message.

Return values
stdClassuser record.

◆ get_user()

static core_user::get_user ( $userid,
$fields = '*',
$strictness = IGNORE_MISSING )
static

Return user object from db or create noreply or support user, if userid matches corse_user\NOREPLY_USER or corse_user\SUPPORT_USER respectively.

If userid is not found, then return false.

Parameters
int$useriduser id
string$fieldsA comma separated list of user fields to be returned, support and noreply user will not be filtered by this.
int$strictnessIGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found; IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended); MUST_EXIST means throw an exception if no user record or multiple records found.
Return values
stdClass|booluser record if found, else false.
Exceptions
dml_exceptionif user record not found and respective $strictness is set.

◆ get_user_by_email()

static core_user::get_user_by_email ( $email,
$fields = '*',
$mnethostid = null,
$strictness = IGNORE_MISSING )
static

Return user object from db based on their email.

Parameters
string$emailThe email of the user searched.
string$fieldsA comma separated list of user fields to be returned, support and noreply user.
int$mnethostidThe id of the remote host.
int$strictnessIGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found; IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended); MUST_EXIST means throw an exception if no user record or multiple records found.
Return values
stdClass|booluser record if found, else false.
Exceptions
dml_exceptionif user record not found and respective $strictness is set.

◆ get_user_by_username()

static core_user::get_user_by_username ( $username,
$fields = '*',
$mnethostid = null,
$strictness = IGNORE_MISSING )
static

Return user object from db based on their username.

Parameters
string$usernameThe username of the user searched.
string$fieldsA comma separated list of user fields to be returned, support and noreply user.
int$mnethostidThe id of the remote host.
int$strictnessIGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found; IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended); MUST_EXIST means throw an exception if no user record or multiple records found.
Return values
stdClass|booluser record if found, else false.
Exceptions
dml_exceptionif user record not found and respective $strictness is set.

◆ is_current_user()

static core_user::is_current_user ( stdClass $user)
static

Determine whether the given user ID is that of the current user.

Useful for components implementing permission callbacks for preferences consumed by {

See also
fill_preferences_cache}
Parameters
stdClass$user
Return values
bool

◆ is_real_user()

static core_user::is_real_user ( $userid,
$checkdb = false )
static

Return true if user id is greater than 0 and alternatively check db.

Parameters
int$useriduser id.
bool$checkdbif true userid will be checked in db. By default it's false, and userid is compared with 0 for performance.
Return values
booltrue is real user else false.

◆ require_active_user()

static core_user::require_active_user ( $user,
$checksuspended = false,
$checknologin = false )
static

Check if the given user is an active user in the site.

Parameters
stdClass$useruser object
boolean$checksuspendedwhether to check if the user has the account suspended
boolean$checknologinwhether to check if the user uses the nologin auth method
Exceptions
moodle_exception
Since
Moodle 3.0

◆ reset_caches()

static core_user::reset_caches ( )
static

Clean the properties cache.

During unit tests we need to be able to reset all caches so that each new test starts in a known state. Intended for use only for testing, phpunit calls this before every test.

◆ reset_internal_users()

static core_user::reset_internal_users ( )
static

Reset self\$noreplyuser and self\$supportuser.

This is only used by phpunit, and there is no other use case for this function. Please don't use it outside phpunit.

◆ search()

static core_user::search ( $query,
context_course $coursecontext = null,
$max = 30,
$querylimit = 5 )
static

Searches for users by name, possibly within a specified context, with current user's access.

Deciding which users to search is complicated because it relies on user permissions; ideally, we shouldn't show names if you aren't allowed to see their profile. The permissions for seeing profile are really complicated.

Even if search is restricted to a course, it's possible that other people might have been able to contribute within the course (e.g. they were enrolled before and not now; or people with system-level roles) so if the user has permission we do want to include everyone. However, if there are multiple results then we prioritise the ones who are enrolled in the course.

If you have moodle/user:viewdetails at system level, you can search everyone. Otherwise we check which courses you do have that permission and search everyone who is enrolled on those courses.

Normally you can only search the user's name. If you have the moodle/site:viewuseridentity capability then we also let you search the fields which are listed as identity fields in the 'showuseridentity' config option. For example, this might include the user's ID number or email.

The $max parameter controls the maximum number of users returned. If users are restricted from view for some reason, multiple runs of the main query might be made; the $querylimit parameter allows this to be restricted. Both parameters can be zero to remove limits.

The returned user objects include id, username, all fields required for user pictures, and user identity fields.

Parameters
string$querySearch query text
context_course | null$coursecontextCourse context or null if system-wide
int$maxMax number of users to return, default 30 (zero = no limit)
int$querylimitMax number of database queries, default 5 (zero = no limit)
Return values
arrayArray of user objects with limited fields

◆ update_picture()

static core_user::update_picture ( stdClass $usernew,
$filemanageroptions = array() )
static

Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.

Parameters
stdClass$usernewAn object that contains some information about the user being updated
array$filemanageroptions
Return values
boolTrue if the user was updated, false if it stayed the same.

◆ validate()

static core_user::validate ( $data)
static

Validate user data.

This method just validates each user field and return an array of errors. It doesn't clean the data, the methods clean() and clean_field() should be used for this purpose.

Parameters
stdClass | array$datauser data object or array to be validated.
Return values
array|true\$errorsarray of errors found on the user object, true if the validation passed.

◆ welcome_message()

static core_user::welcome_message ( )
static

Get welcome message.

Return values
lang_stringwelcome message

Member Data Documentation

◆ AUTHSYNCFIELDS

const core_user::AUTHSYNCFIELDS
Initial value:
= [
'firstname',
'lastname',
'email',
'city',
'country',
'lang',
'description',
'idnumber',
'institution',
'department',
'phone1',
'phone2',
'address',
'firstnamephonetic',
'lastnamephonetic',
'middlename',
'alternatename'
]

List of fields that can be synched/locked during authentication.


The documentation for this class was generated from the following file: