Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
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$purposeInitial 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
fieldsUser 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
$thisSame 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$contextContext; if supplied, includes only fields the current user should see
bool$allowcustomIf true, custom profile fields may be included
Return values
fieldsUser 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
fieldsUser 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
fieldsUser 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$fieldField name in database
Return values
stringField 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$contextContext; if not supplied, all fields will be included without checks
bool$allowcustomIf 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$differentorderIn 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$limitpurposesIf specified, gets fields only for these purposes
Return values
string[]Array of required fields
Exceptions
coding_exceptionIf 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$aliasOptional (but recommended) alias for user table in query, e.g. 'u'
bool$namedparamsIf true, uses named :parameters instead of indexed ? parameters
string$prefixOptional prefix for all field names in result, e.g. 'u_'
string$renameidRenames the 'id' field if specified, e.g. 'userid'
bool$leadingcommaIf true the 'selects' list will start with a comma
Return values
stdClassObject 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$tablealiasUser table alias, if set elsewhere in the query, null if not required
bool$overrideIf true then the alternativefullnameformat format rather than fullnamedisplay format will be used
Return values
arraySQL 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
$thisSame 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$fieldnameField name
Return values
stringEmpty 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|nullContext; if supplied, includes only fields the current user should see
bool$allowcustomIf true, custom profile fields may be included
Return values
$thisSame 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
$thisSame 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
$thisSame object for chaining function calls

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