Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 311 and 401]

(no description)

File Size: 685 lines (30 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class


Class: fields  - X-Ref

Class for retrieving information about user fields that are needed for displaying user identity.

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

param: int $purpose Initial purpose for object or -1 for none

empty()   X-Ref
Constructs an empty user fields object to get arbitrary user fields.

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

return: fields User fields object ready for use

for_identity(?\context $context, bool $allowcustom = true)   X-Ref
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');

param: \context|null $context Context; if supplied, includes only fields the current user should see
param: bool $allowcustom If true, custom profile fields may be included
return: fields User fields object ready for use

for_userpic()   X-Ref
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: fields User fields object ready for use

for_name()   X-Ref
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: fields User fields object ready for use

with_userpic()   X-Ref
On an existing fields object, adds the fields required for displaying user pictures.

return: $this Same object for chaining function calls

with_name()   X-Ref
On an existing fields object, adds the fields required for displaying user full names.

return: $this Same object for chaining function calls

with_identity(?\context $context, bool $allowcustom = true)   X-Ref
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.

param: \context|null Context; if supplied, includes only fields the current user should see
param: bool $allowcustom If true, custom profile fields may be included
return: $this Same object for chaining function calls

including(string ...$include)   X-Ref
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'.

param: string ...$include One or more fields to add
return: $this Same object for chaining function calls

excluding(...$exclude)   X-Ref
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.

param: string ...$exclude One or more fields to exclude
return: $this Same object for chaining function calls

get_required_fields(array $limitpurposes = [])   X-Ref
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.)

param: array $limitpurposes If specified, gets fields only for these purposes
return: string[] Array of required fields

get_picture_fields()   X-Ref
Gets fields required for user pictures.

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

return: string[] All fields required for user pictures

get_name_fields(bool $differentorder = false)   X-Ref
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.

param: bool $differentorder In a few places, a different order of fields is required
return: string[] All fields used to display user names

get_identity_fields(?\context $context, bool $allowcustom = true)   X-Ref
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.

param: \context|null $context Context; if not supplied, all fields will be included without checks
param: bool $allowcustom If true, custom profile fields will be included
return: string[] Array of required fields

get_sql(string $alias = '', bool $namedparams = false, string $prefix = '',string $renameid = '', bool $leadingcomma = true)   X-Ref
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.)

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

get_sql_fullname(?string $tablealias = 'u', bool $override = false)   X-Ref
Similar to {@see \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);

param: string|null $tablealias User table alias, if set elsewhere in the query, null if not required
param: bool $override If true then the alternativefullnameformat format rather than fullnamedisplay format will be used
return: array SQL select snippet and parameters

get_display_name(string $field)   X-Ref
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'.

param: string $field Field name in database
return: string Field name for display to user

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

match_custom_field(string $fieldname)   X-Ref
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).

param: string $fieldname Field name
return: string Empty string if not a profile field, or profile field name (without profile_field_)