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_fullname (stdClass $user, context $context=null, array $options=[])
	Return full name depending on context.

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_profile_picture (stdClass $user, context $context=null, array $options=[])
	Return user picture depending on context.

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

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.

Copyright: 2013 Rajesh Taneja rajes.nosp@m.h@mo.nosp@m.odle..nosp@m.com

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 $user User 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 $user the user data to be validated against properties definition.

Return values

stdClass\$user the cleaned user data.

◆ clean_field()

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

static

Clean a specific user field.

Parameters

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

Return values

string the cleaned user data.

◆ clean_preference()

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

static

Clean value of a user preference.

Parameters

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

Return values

string the 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 $capability Required capability

Return values

array Array containing SQL and params, or two nulls if there are no courses

◆ get_fullname()

static core_user::get_fullname	(	stdClass	$user,
		context	$context = null,
		array	$options = [] )

static

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.

Parameters

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

Return values

string Full name of the user

◆ 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

stdClass user record.

◆ get_preference_definition()

static core_user::get_preference_definition ( $preferencename )

staticprotected

Retrieves the preference definition.

Parameters

string $preferencename

Return values

array

◆ get_profile_picture()

static core_user::get_profile_picture	(	stdClass	$user,
		context	$context = null,
		array	$options = [] )

static

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.

Parameters

stdClass	$user	the person to get details of.
context \| null	$context	The context will be used to determine the visibility of the user's picture.
array	$options	public properties of {

See also

user_picture} to be overridden

courseid = $this->page->course->id (course id of user profile in link)
size = 35 (size of image)
link = true (make image clickable - the link leads to user profile)
popup = false (open in popup)
alttext = true (add image alt attribute)
class = image class attribute (default 'userpicture')
visibletoscreenreaders = true (whether to be visible to screen readers)
includefullname = false (whether to include the user's full name together with the user picture)
includetoken = false (whether to use a token for authentication. True for current user, int value for other user id)

Return values

user_picture User picture object

◆ get_profile_url()

static core_user::get_profile_url	(	stdClass	$user,
		context	$context = null )

static

Return profile url depending on context.

Parameters

stdClass	$user	the person to get details of.
context \| null	$context	The context will be used to determine the visibility of the user's profile url.

Return values

moodle_url Profile url of the user

◆ 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 $property property name to be retrieved.

Exceptions

coding_exception if the requested property name is invalid or if it does not has a list of choices.

Return values

array the 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 $property property name to be retrieved.

Exceptions

coding_exception if the requested property name is invalid or if it does not has a default value.

Return values

string the property default value.

◆ get_property_definition()

static core_user::get_property_definition ( $property )

static

Get properties of a user field.

Parameters

string $property property name to be retrieved.

Exceptions

coding_exception if the requested property name is invalid.

Return values

array the 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 $property property name to be retrieved.

Exceptions

coding_exception if the requested property name is invalid.

Return values

bool	true 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 $property property name to be retrieved.

Exceptions

coding_exception if the requested property name is invalid.

Return values

int	the 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

stdClass user 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	$userid	user id
string	$fields	A comma separated list of user fields to be returned, support and noreply user will not be filtered by this.
int	$strictness	IGNORE_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|bool user record if found, else false.

Exceptions

dml_exception if 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	$email	The email of the user searched.
string	$fields	A comma separated list of user fields to be returned, support and noreply user.
int	$mnethostid	The id of the remote host.
int	$strictness	IGNORE_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|bool user record if found, else false.

Exceptions

dml_exception if 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	$username	The username of the user searched.
string	$fields	A comma separated list of user fields to be returned, support and noreply user.
int	$mnethostid	The id of the remote host.
int	$strictness	IGNORE_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|bool user record if found, else false.

Exceptions

dml_exception if 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	$userid	user id.
bool	$checkdb	if true userid will be checked in db. By default it's false, and userid is compared with 0 for performance.

Return values

bool	true 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	$user	user object
boolean	$checksuspended	whether to check if the user has the account suspended
boolean	$checknologin	whether 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	$query	Search query text
context_course \| null	$coursecontext	Course context or null if system-wide
int	$max	Max number of users to return, default 30 (zero = no limit)
int	$querylimit	Max number of database queries, default 5 (zero = no limit)

Return values

array Array 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	$usernew	An object that contains some information about the user being updated
array	$filemanageroptions

Return values

bool	True 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 $data user data object or array to be validated.

Return values

array|true\$errors array 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_string welcome 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:

lib/classes/user.php

Static Public Member Functions

Public Attributes

Static Public Attributes

Static Protected Member Functions

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ awaiting_action()

◆ can_edit_preference()

◆ clean_data()

◆ clean_field()

◆ clean_preference()

◆ default_preference_permission_check()

◆ fill_preferences_cache()

◆ fill_properties_cache()

◆ get_dummy_user_record()

◆ get_enrolled_sql_on_courses_with_capability()

◆ get_fullname()

◆ get_initials()

◆ get_noreply_user()

◆ get_preference_definition()

◆ get_profile_picture()

◆ get_profile_url()

◆ get_property_choices()

◆ get_property_default()

◆ get_property_definition()

◆ get_property_null()

◆ get_property_type()

◆ get_support_user()

◆ get_user()

◆ get_user_by_email()

◆ get_user_by_username()

◆ is_current_user()

◆ is_real_user()

◆ require_active_user()

◆ reset_caches()

◆ reset_internal_users()

◆ search()

◆ update_picture()

◆ validate()

◆ welcome_message()

Member Data Documentation

◆ AUTHSYNCFIELDS