Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.3.x will end 7 October 2024 (12 months).
  • Bug fixes for security issues in 4.3.x will end 21 April 2025 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.2.x is supported too.

Class: core_user  - X-Ref

User class to access user details.

get_user($userid, $fields = '*', $strictness = IGNORE_MISSING)   X-Ref
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.

param: int $userid user id
param: string $fields A comma separated list of user fields to be returned, support and noreply user
param: int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
return: stdClass|bool user record if found, else false.

get_user_by_email($email, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING)   X-Ref
Return user object from db based on their email.

param: string $email The email of the user searched.
param: string $fields A comma separated list of user fields to be returned, support and noreply user.
param: int $mnethostid The id of the remote host.
param: int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
return: stdClass|bool user record if found, else false.

get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING)   X-Ref
Return user object from db based on their username.

param: string $username The username of the user searched.
param: string $fields A comma separated list of user fields to be returned, support and noreply user.
param: int $mnethostid The id of the remote host.
param: int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
return: stdClass|bool user record if found, else false.

search($query, \context_course $coursecontext = null,$max = 30, $querylimit = 5)   X-Ref
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.

param: string $query Search query text
param: \context_course|null $coursecontext Course context or null if system-wide
param: int $max Max number of users to return, default 30 (zero = no limit)
param: int $querylimit Max number of database queries, default 5 (zero = no limit)
return: array Array of user objects with limited fields

get_enrolled_sql_on_courses_with_capability($capability)   X-Ref
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.

param: string $capability Required capability
return: array Array containing SQL and params, or two nulls if there are no courses

get_dummy_user_record()   X-Ref
Helper function to return dummy noreply user record.

return: stdClass

get_noreply_user()   X-Ref
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: stdClass user record.

get_support_user()   X-Ref
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: stdClass user record.

reset_internal_users()   X-Ref
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.


is_real_user($userid, $checkdb = false)   X-Ref
Return true if user id is greater than 0 and alternatively check db.

param: int $userid user id.
param: bool $checkdb if true userid will be checked in db. By default it's false, and
return: bool true is real user else false.

is_current_user(stdClass $user)   X-Ref
Determine whether the given user ID is that of the current user. Useful for components implementing permission callbacks
for preferences consumed by {@see fill_preferences_cache}

param: stdClass $user
return: bool

require_active_user($user, $checksuspended = false, $checknologin = false)   X-Ref
Check if the given user is an active user in the site.

param: stdClass  $user         user object
param: boolean $checksuspended whether to check if the user has the account suspended
param: boolean $checknologin   whether to check if the user uses the nologin auth method

update_picture(stdClass $usernew, $filemanageroptions = array()   X-Ref
Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.

param: stdClass $usernew An object that contains some information about the user being updated
param: array $filemanageroptions
return: bool True if the user was updated, false if it stayed the same.

fill_properties_cache()   X-Ref
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: void

get_property_definition($property)   X-Ref
Get properties of a user field.

param: string $property property name to be retrieved.
return: array the property definition.

validate($data)   X-Ref
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.

param: stdClass|array $data user data object or array to be validated.
return: array|true $errors array of errors found on the user object, true if the validation passed.

reset_caches()   X-Ref
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.

clean_data($user)   X-Ref
Clean the user data.

param: stdClass|array $user the user data to be validated against properties definition.
return: stdClass $user the cleaned user data.

clean_field($data, $field)   X-Ref
Clean a specific user field.

param: string $data the user field data to be cleaned.
param: string $field the user field name on the property definition cache.
return: string the cleaned user data.

get_property_type($property)   X-Ref
Get the parameter type of the property.

param: string $property property name to be retrieved.
return: int the property parameter type.

get_property_null($property)   X-Ref
Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.

param: string $property property name to be retrieved.
return: bool true if the property is NULL_ALLOWED, false otherwise.

get_property_choices($property)   X-Ref
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.

param: string $property property name to be retrieved.
return: array the property parameter type.

get_property_default($property)   X-Ref
Get the property default.

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

param: string $property property name to be retrieved.
return: string the property default value.

fill_preferences_cache()   X-Ref
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: void

get_preference_definition($preferencename)   X-Ref
Retrieves the preference definition

param: string $preferencename
return: array

default_preference_permission_check($user, $preferencename)   X-Ref
Default callback used for checking if current user is allowed to change permission of user $user

param: stdClass $user
param: string $preferencename
return: bool

can_edit_preference($preferencename, $user)   X-Ref
Can current user edit preference of this/another user

param: string $preferencename
param: stdClass $user
return: bool

clean_preference($value, $preferencename)   X-Ref
Clean value of a user preference

param: string $value the user preference value to be cleaned.
param: string $preferencename the user preference name
return: string the cleaned preference value

awaiting_action(stdClass $user = null)   X-Ref
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.

param: stdClass $user User object, defaults to the current user.
return: bool

welcome_message()   X-Ref
Get welcome message.

return: lang_string welcome message

get_fullname(stdClass $user, context $context = null, array $options = [])   X-Ref
Return full name depending on context.
This function should be used for displaying purposes only as the details may not be the same as it is on database.

param: stdClass $user the person to get details of.
param: context|null $context The context will be used to determine the visibility of the user's full name.
param: array $options can include: override - if true, will not use forced firstname/lastname settings
return: string Full name of the user

get_profile_url(stdClass $user, context $context = null)   X-Ref
Return profile url depending on context.

param: stdClass $user the person to get details of.
param: context|null $context The context will be used to determine the visibility of the user's profile url.
return: moodle_url Profile url of the user

get_profile_picture(stdClass $user, context $context = null, array $options = [])   X-Ref
Return user picture depending on context.
This function should be used for displaying purposes only as the details may not be the same as it is on database.

param: stdClass $user the person to get details of.
param: context|null $context The context will be used to determine the visibility of the user's picture.
param: array $options public properties of {@see user_picture} to be overridden
return: user_picture User picture object

get_initials(stdClass $user)   X-Ref
Get initials for users

param: stdClass $user
return: string