Search moodle.org's
Developer Documentation
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.
/user/classes/ -> fields.php (source)
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
fields:: (19 methods):
__construct()
empty()
for_identity()
for_userpic()
for_name()
with_userpic()
with_name()
with_identity()
including()
excluding()
get_required_fields()
get_picture_fields()
get_name_fields()
get_identity_fields()
get_sql()
get_sql_fullname()
get_display_name()
reset_unique_identifier()
match_custom_field()
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_) |
