core_user\fields Class Reference

Public Member Functions
	excluding (... $exclude)
	On an existing fields object, excludes fields from retrieval.
	get_required_fields (array $limitpurposes=[])
	Gets an array of all fields that are required for the specified purposes, also taking into account the $includes and $excludes settings.
	get_sql (string $alias='', bool $namedparams=false, string $prefix='', string $renameid='', bool $leadingcomma=true)
	Gets SQL that can be used in a query to get the necessary fields.
	including (string ... $include)
	On an existing fields object, adds extra fields to be retrieved.
	with_identity (?\context $context, bool $allowcustom=true)
	On an existing fields object, adds the fields required for displaying user identity.
	with_name ()
	On an existing fields object, adds the fields required for displaying user full names.
	with_userpic ()
	On an existing fields object, adds the fields required for displaying user pictures.

Static Public Member Functions
static	empty ()
	Constructs an empty user fields object to get arbitrary user fields.
static	for_identity (?\context $context, bool $allowcustom=true)
	Constructs a user fields object to get identity information for display.
static	for_name ()
	Constructs a user fields object to get information required for displaying a user full name.
static	for_userpic ()
	Constructs a user fields object to get information required for displaying a user picture.
static	get_display_name (string $field)
	Gets the display name of a given user field.
static	get_identity_fields (?\context $context, bool $allowcustom=true)
	Gets all fields required for user identity.
static	get_name_fields (bool $differentorder=false)
	Gets fields required for user names.
static	get_picture_fields ()
	Gets fields required for user pictures.
static	get_sql_fullname (?string $tablealias='u', bool $override=false)
	Similar to {.
static	match_custom_field (string $fieldname)
	Checks if a field name looks like a custom profile field i.e.
static	reset_unique_identifier ()
	Resets the unique identifier used to ensure that multiple SQL fragments generated in the same request will have different identifiers for parameters and table aliases.

Public Attributes
int const	CUSTOM_INCLUDE = 3
	Field required by custom include list.
string const	PROFILE_FIELD_PREFIX = 'profile_field_'
	Prefix used to identify custom profile fields.
string const	PROFILE_FIELD_REGEX = '~^' . self::PROFILE_FIELD_PREFIX . '(.*)$~'
	Regular expression used to match a field name against the prefix.
int const	PURPOSE_IDENTITY = 0
	All fields required to display user's identity, based on server configuration.
int const	PURPOSE_NAME = 2
	All fields required for somebody's name.
int const	PURPOSE_USERPIC = 1
	All fields required to display a user picture.

Protected Member Functions
	__construct (int $purpose=-1)
	Protected constructor - use one of the for_xx methods to create an object.

Protected Attributes
bool	$allowcustom
	True to allow custom user fields.
context null	$context
	Context in use.
string[]	$exclude
	List of fields to exclude.
array null	$fields = null
	Associative array from field => array of purposes it was used for => true.
string[]	$include
	List of extra fields to include.
bool[]	$purposes
	Array of purposes (from PURPOSE_xx to true/false)

Static Protected Attributes
static int	$uniqueidentifier = 1
	Unique identifier for different queries generated in same request.

Constructor & Destructor Documentation

__construct()

core_user\fields::__construct ( int $purpose = -1 )

protected

Protected constructor - use one of the for_xx methods to create an object.

Parameters

int

$purpose

Initial purpose for object or -1 for none

Member Function Documentation

empty()

static core_user\fields::empty ( )

static

Constructs an empty user fields object to get arbitrary user fields.

You can add fields to retrieve with the including() function.

Return values

fields

User fields object ready for use

excluding()

core_user\fields::excluding

(

...

)

On an existing fields object, excludes fields from retrieval.

You can specify either fields from the user table e.g. 'email', or profile fields e.g. 'profile_field_height'.

This is useful when constructing queries where your query already explicitly references certain fields, so you don't want to retrieve them twice.

Parameters

string

...$exclude One or more fields to exclude

Return values

$this

Same object for chaining function calls

for_identity()

static core_user\fields::for_identity ( ?\context $context, bool $allowcustom = true )

static

Constructs a user fields object to get identity information for display.

The function does all the required capability checks to see if the current user is allowed to see them in the specified context. You can pass context null to get all the fields without checking permissions.

If the code can only handle fields in the main user table, and not custom profile fields, then set $allowcustom to false.

Note: After constructing the object you can use the ->with_xx, ->including, and ->excluding functions to control the required fields in more detail. For example:

$fields = fields\for_identity($context)->with_userpic()->excluding('email');

Parameters

context | null	$context	Context; if supplied, includes only fields the current user should see
bool	$allowcustom	If true, custom profile fields may be included

Return values

fields

User fields object ready for use

for_name()

static core_user\fields::for_name ( )

static

Constructs a user fields object to get information required for displaying a user full name.

Note: After constructing the object you can use the ->with_xx, ->including, and ->excluding functions to control the required fields in more detail. For example:

$fields = fields\for_name()->with_userpic()->excluding('email');

Return values

fields

User fields object ready for use

for_userpic()

static core_user\fields::for_userpic ( )

static

Constructs a user fields object to get information required for displaying a user picture.

Note: After constructing the object you can use the ->with_xx, ->including, and ->excluding functions to control the required fields in more detail. For example:

$fields = fields\for_userpic()->with_name()->excluding('email');

Return values

fields

User fields object ready for use

get_display_name()

static core_user\fields::get_display_name ( string $field )

static

Gets the display name of a given user field.

Supports field names from the 'user' database table, and custom profile fields supplied in the format 'profile_field_xx'.

Parameters

string

$field

Field name in database

Return values

string

Field name for display to user

Exceptions

coding_exception

get_identity_fields()

static core_user\fields::get_identity_fields ( ?\context $context, bool $allowcustom = true )

static

Gets all fields required for user identity.

These fields should be included in tables showing lists of users (in addition to the user's name which is included as standard).

The results include basic field names (columns from the 'user' database table) and, unless turned off, custom profile field names in the format 'profile_field_myfield', note these fields will always be returned lower cased to match how they are returned by the DML library.

This function does all the required capability checks to see if the current user is allowed to see them in the specified context. You can pass context null to get all the fields without checking permissions.

Parameters

context | null	$context	Context; if not supplied, all fields will be included without checks
bool	$allowcustom	If true, custom profile fields will be included

Return values

string[]

Array of required fields

Exceptions

coding_exception

get_name_fields()

static core_user\fields::get_name_fields ( bool $differentorder = false )

static

Gets fields required for user names.

The results include only basic field names (columns from the 'user' database table).

Fields are usually returned in a specific order, which the fullname() function depends on. If you specify 'true' to the $strangeorder flag, then the firstname and lastname fields are moved to the front; this is useful in a few places in existing code. New code should avoid requiring a particular order.

Parameters

bool

$differentorder

In a few places, a different order of fields is required

Return values

string[]

All fields used to display user names

get_picture_fields()

static core_user\fields::get_picture_fields ( )

static

Gets fields required for user pictures.

The results include only basic field names (columns from the 'user' database table).

Return values

string[]

All fields required for user pictures

get_required_fields()

core_user\fields::get_required_fields

(

array

$limitpurposes = []

)

Gets an array of all fields that are required for the specified purposes, also taking into account the $includes and $excludes settings.

The results may include basic field names (columns from the 'user' database table) and, unless turned off, custom profile field names in the format 'profile_field_myfield'.

You should not rely on the order of fields, with one exception: if there is an id field it will be returned first. This is in case it is used with get_records calls.

The $limitpurposes parameter is useful if you want to get a different set of fields than the purposes in the constructor. For example, if you want to get SQL for identity + user picture fields, but you then want to only get the identity fields as a list. (You can only specify purposes that were also passed to the constructor i.e. it can only be used to restrict the list, not add to it.)

Parameters

array

$limitpurposes

If specified, gets fields only for these purposes

Return values

string[]

Array of required fields

Exceptions

coding_exception

If any unknown purpose is listed

get_sql()

core_user\fields::get_sql	(	string	$alias = '',
		bool	$namedparams = false,
		string	$prefix = '',
		string	$renameid = '',
		bool	$leadingcomma = true )

Gets SQL that can be used in a query to get the necessary fields.

The result of this function is an object with fields 'selects', 'joins', 'params', and 'mappings'.

If not empty, the list of selects will begin with a comma and the list of joins will begin and end with a space. You can include the result in your existing query like this:

SELECT (your existing fields) $selects FROM {user} u JOIN (your existing joins) $joins

When there are no custom fields then the 'joins' result will always be an empty string, and 'params' will be an empty array.

The $fieldmappings value is often not needed. It is an associative array from each field name to an SQL expression for the value of that field, e.g.: 'profile_field_frog' => 'uf1d_3.data' 'city' => 'u.city' This is helpful if you want to use the profile fields in a WHERE clause, becuase you can't refer to the aliases used in the SELECT list there.

The leading comma is included because this makes it work in the pattern above even if there are no fields from the get_sql() data (which can happen if doing identity fields and none are selected). If you want the result without a leading comma, set $leadingcomma to false.

If the 'id' field is included then it will always be first in the list. Otherwise, you should not rely on the field order.

For identity fields, the function does all the required capability checks to see if the current user is allowed to see them in the specified context. You can pass context null to get all the fields without checking permissions.

If your code for any reason cannot cope with custom fields then you can turn them off.

You can have either named or ? params. If you use named params, they are of the form uf1s_2; the first number increments in each call using a static variable in this class and the second number refers to the field being queried. A similar pattern is used to make join aliases unique.

If your query refers to the user table by an alias e.g. 'u' then specify this in the $alias parameter; otherwise it will use {user} (if there are any joins for custom profile fields) or simply refer to the field by name only (if there aren't).

If you need to use a prefix on the field names (for example in case they might coincide with existing result columns from your query, or if you want a convenient way to split out all the user data into a separate object) then you can specify one here. For example, if you include name fields and the prefix is 'u_' then the results will include 'u_firstname'.

If you don't want to prefix all the field names but only change the id field name, use the $renameid parameter. (When you use this parameter, it takes precedence over any prefix; the id field will not be prefixed, while all others will.)

Parameters

string	$alias	Optional (but recommended) alias for user table in query, e.g. 'u'
bool	$namedparams	If true, uses named :parameters instead of indexed ? parameters
string	$prefix	Optional prefix for all field names in result, e.g. 'u_'
string	$renameid	Renames the 'id' field if specified, e.g. 'userid'
bool	$leadingcomma	If true the 'selects' list will start with a comma

Return values

stdClass

Object with necessary SQL components

get_sql_fullname()

static core_user\fields::get_sql_fullname ( ?string $tablealias = 'u', bool $override = false )

static

Similar to {.

See also

moodle_database\sql_fullname} except it returns all user name fields as defined by site config, in a single select statement suitable for inclusion in a query/filter for a users fullname, e.g.

[$select, $params] = fields\get_sql_fullname('u'); $users = $DB->get_records_sql_menu("SELECT u.id, {$select} FROM {user} u", $params);

Parameters

string | null	$tablealias	User table alias, if set elsewhere in the query, null if not required
bool	$override	If true then the alternativefullnameformat format rather than fullnamedisplay format will be used

Return values

array

SQL select snippet and parameters

including()

core_user\fields::including

(

string ...

$include

)

On an existing fields object, adds extra fields to be retrieved.

You can specify either fields from the user table e.g. 'email', or profile fields e.g. 'profile_field_height'.

Parameters

string

...$include One or more fields to add

Return values

$this

Same object for chaining function calls

match_custom_field()

static core_user\fields::match_custom_field ( string $fieldname )

static

Checks if a field name looks like a custom profile field i.e.

it begins with profile_field_ (does not check if that profile field actually exists).

Parameters

string

$fieldname

Field name

Return values

string

Empty string if not a profile field, or profile field name (without profile_field_)

reset_unique_identifier()

static core_user\fields::reset_unique_identifier ( )

static

Resets the unique identifier used to ensure that multiple SQL fragments generated in the same request will have different identifiers for parameters and table aliases.

This is intended only for use in unit testing.

with_identity()

core_user\fields::with_identity	(	?\context	$context,
		bool	$allowcustom = true )

On an existing fields object, adds the fields required for displaying user identity.

The function does all the required capability checks to see if the current user is allowed to see them in the specified context. You can pass context null to get all the fields without checking permissions.

If the code can only handle fields in the main user table, and not custom profile fields, then set $allowcustom to false.

Parameters

	context|null	Context; if supplied, includes only fields the current user should see
bool	$allowcustom	If true, custom profile fields may be included

Return values

$this

Same object for chaining function calls

with_name()

core_user\fields::with_name

(

)

On an existing fields object, adds the fields required for displaying user full names.

Return values

$this

Same object for chaining function calls

with_userpic()

core_user\fields::with_userpic

(

)

On an existing fields object, adds the fields required for displaying user pictures.

Return values

$this

Same object for chaining function calls

---

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

• user/classes/fields.php