User fields - Revision history

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T20:35:28Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 20:35, 14 July 2021
				
Line 25:
Line 25:
=== List fields required to display a user picture === === List fields required to display a user picture ===



<code php> <syntaxhighlight lang="php">
$fields = \core_user\fields::for_userpic()->get_required_fields(); $fields = \core_user\fields::for_userpic()->get_required_fields();
</syntaxhighlight> </syntaxhighlight>
Line 35:
Line 35:
=== List fields required to display a user's full name === === List fields required to display a user's full name ===



<code php> <syntaxhighlight lang="php">
$fields = \core_user\fields::for_name()->get_required_fields(); $fields = \core_user\fields::for_name()->get_required_fields();
</syntaxhighlight> </syntaxhighlight>
Line 45:
Line 45:
=== List fields required to display a user picture and full name === === List fields required to display a user picture and full name ===



<code php> <syntaxhighlight lang="php">
$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields(); $fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();
</syntaxhighlight> </syntaxhighlight>
Line 57:
Line 57:
Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields. Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.



<code php> <syntaxhighlight lang="php">
$fields = \core_user\fields::for_identity($context)->get_required_fields(); $fields = \core_user\fields::for_identity($context)->get_required_fields();
</syntaxhighlight> </syntaxhighlight>
Line 63:
Line 63:
The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function: The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:



<code php> <syntaxhighlight lang="php">
$fields = \core_user\fields::for_identity($context, false)->get_required_fields(); $fields = \core_user\fields::for_identity($context, false)->get_required_fields();
</syntaxhighlight> </syntaxhighlight>
Line 73:
Line 73:
Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists: Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:



<code php> <syntaxhighlight lang="php">
$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields(); $fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();
</syntaxhighlight> </syntaxhighlight>
Line 79:
Line 79:
Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list. Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.



<code php> <syntaxhighlight lang="php">
$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields(); $fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();
</syntaxhighlight> </syntaxhighlight>
Line 91:
Line 91:
Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this: Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:



<code php> <syntaxhighlight lang="php">
$result = $DB->get_records_sql(" $result = $DB->get_records_sql("
         SELECT u.id, u.deleted          SELECT u.id, u.deleted
Line 102:
Line 102:
We can create a user fields object like this: We can create a user fields object like this:



<code php> <syntaxhighlight lang="php">
$context = \context_system::instance(); $context = \context_system::instance();
$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted'); $userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');
Line 109:
Line 109:
The user fields object can create SQL snippets for you like this: The user fields object can create SQL snippets for you like this:



<code php> <syntaxhighlight lang="php">
$sql = $userfields->get_sql('u'); $sql = $userfields->get_sql('u');
</syntaxhighlight> </syntaxhighlight>
Line 115:
Line 115:
This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query: This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:



<code php> <syntaxhighlight lang="php">
$result = $DB->get_records_sql(" $result = $DB->get_records_sql("
         SELECT u.id, u.deleted {$sql->selects}          SELECT u.id, u.deleted {$sql->selects}
Line 138:
Line 138:
An extra parameter on get_required_fields lets you include only one category of fields from the object: An extra parameter on get_required_fields lets you include only one category of fields from the object:



<code php> <syntaxhighlight lang="php">
$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]); $extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);
</syntaxhighlight> </syntaxhighlight>
Line 146:
Line 146:
To display those columns you will need a header with a field name. You can get a field name as follows: To display those columns you will need a header with a field name. You can get a field name as follows:



<code php> <syntaxhighlight lang="php">
$header = \core_user\fields::get_display_name($field); $header = \core_user\fields::get_display_name($field);
</syntaxhighlight> </syntaxhighlight>

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T20:16:20Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 20:16, 14 July 2021
Line 27:		Line 27:
	<code php>		<code php>
	$fields = \core_user\fields::for_userpic()->get_required_fields();		$fields = \core_user\fields::for_userpic()->get_required_fields();
	</~~code~~>		</syntaxhighlight>

	This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).		This will return an array of fields required for displaying userpic (id, picture, firstname, lastname, ...).
Line 37:		Line 37:
	<code php>		<code php>
	$fields = \core_user\fields::for_name()->get_required_fields();		$fields = \core_user\fields::for_name()->get_required_fields();
	</~~code~~>		</syntaxhighlight>

	This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).		This returns all fields needed to display a name (firstname, lastname, firstnamephonetic, ...).
Line 47:		Line 47:
	<code php>		<code php>
	$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();		$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();
	</~~code~~>		</syntaxhighlight>

	If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.		If you need both types of fields, you can combine them by creating the object initially with a 'for' method, and then calling the 'with' method to add a different category of fields.
Line 59:		Line 59:
	<code php>		<code php>
	$fields = \core_user\fields::for_identity($context)->get_required_fields();		$fields = \core_user\fields::for_identity($context)->get_required_fields();
	</~~code~~>		</syntaxhighlight>

	The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:		The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:
Line 65:		Line 65:
	<code php>		<code php>
	$fields = \core_user\fields::for_identity($context, false)->get_required_fields();		$fields = \core_user\fields::for_identity($context, false)->get_required_fields();
	</~~code~~>		</syntaxhighlight>

	Now it won't return any custom profile fields (and your code doesn't support them, which is sad).		Now it won't return any custom profile fields (and your code doesn't support them, which is sad).
Line 75:		Line 75:
	<code php>		<code php>
	$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();		$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();
	</~~code~~>		</syntaxhighlight>

	Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.		Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.
Line 81:		Line 81:
	<code php>		<code php>
	$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();		$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();
	</~~code~~>		</syntaxhighlight>

	You can use both including and excluding functions if you want.		You can use both including and excluding functions if you want.
Line 96:		Line 96:
	FROM {user} u		FROM {user} u
	ORDER BY u.lastaccess DESC", [], 0, 10);		ORDER BY u.lastaccess DESC", [], 0, 10);
	</~~code~~>		</syntaxhighlight>

	Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.		Suppose that we also want to include the user's name, and any identity fields that are enabled for the current user. We don't want to include the 'id' or 'deleted' field because they're already included in the query.
Line 105:		Line 105:
	$context = \context_system::instance();		$context = \context_system::instance();
	$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');		$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');
	</~~code~~>		</syntaxhighlight>

	The user fields object can create SQL snippets for you like this:		The user fields object can create SQL snippets for you like this:
Line 111:		Line 111:
	<code php>		<code php>
	$sql = $userfields->get_sql('u');		$sql = $userfields->get_sql('u');
	</~~code~~>		</syntaxhighlight>

	This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:		This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:
Line 121:		Line 121:
	{$sql->joins}		{$sql->joins}
	ORDER BY u.lastaccess DESC", $sql->params, 0, 10);		ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
	</~~code~~>		</syntaxhighlight>

	There are many options to the get_sql function, as well as the user table alias shown. For example, you can:		There are many options to the get_sql function, as well as the user table alias shown. For example, you can:
Line 140:		Line 140:
	<code php>		<code php>
	$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);		$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);
	</~~code~~>		</syntaxhighlight>

	== Field names ==		== Field names ==
Line 148:		Line 148:
	<code php>		<code php>
	$header = \core_user\fields::get_display_name($field);		$header = \core_user\fields::get_display_name($field);
	</~~code~~>		</syntaxhighlight>

	This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).		This works for both standard user table fields e.g. email (it will get the appropriate language string), and for custom fields (it will get the name for the custom field).

Quen at 12:40, 29 March 2021

2021-03-29T12:40:31Z

← Older revision		Revision as of 12:40, 29 March 2021
Line 1:		Line 1:
	{{Moodle 3.11}}		{{Moodle 3.11}}

	Code relating to display of user fields is in the class <tt>\core_user\fields</tt> in file <tt>/~~lib~~/classes/~~user_fields~~.php</tt>.		Code relating to display of user fields is in the class <tt>\core_user\fields</tt> in file <tt>/user/classes/fields.php</tt>.

	* See also [[User-related APIs]], which has information about defining custom user fields.		* See also [[User-related APIs]], which has information about defining custom user fields.

Quen: Updated for new location of class

2021-03-29T12:40:14Z

Updated for new location of class

← Older revision		Revision as of 12:40, 29 March 2021
Line 1:		Line 1:
	{{Moodle 3.11}}		{{Moodle 3.11}}

	Code relating to display of user fields is in the class <tt>\~~core~~\~~user_fields~~</tt> in file <tt>/lib/classes/user_fields.php</tt>.		Code relating to display of user fields is in the class <tt>\core_user\fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

	* See also [[User-related APIs]], which has information about defining custom user fields.		* See also [[User-related APIs]], which has information about defining custom user fields.
Line 26:		Line 26:

	<code php>		<code php>
	$fields = \~~core~~\~~user_fields~~::for_userpic()->get_required_fields();		$fields = \core_user\fields::for_userpic()->get_required_fields();
	</code>		</code>

Line 36:		Line 36:

	<code php>		<code php>
	$fields = \~~core~~\~~user_fields~~::for_name()->get_required_fields();		$fields = \core_user\fields::for_name()->get_required_fields();
	</code>		</code>

Line 46:		Line 46:

	<code php>		<code php>
	$fields = \~~core~~\~~user_fields~~::for_name()->with_userpic()->get_required_fields();		$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();
	</code>		</code>

Line 58:		Line 58:

	<code php>		<code php>
	$fields = \~~core~~\~~user_fields~~::for_identity($context)->get_required_fields();		$fields = \core_user\fields::for_identity($context)->get_required_fields();
	</code>		</code>

Line 64:		Line 64:

	<code php>		<code php>
	$fields = \~~core~~\~~user_fields~~::for_identity($context, false)->get_required_fields();		$fields = \core_user\fields::for_identity($context, false)->get_required_fields();
	</code>		</code>

Line 74:		Line 74:

	<code php>		<code php>
	$fields = \~~core~~\~~user_fields~~::for_identity($context)->including('email')->get_required_fields();		$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();
	</code>		</code>

Line 80:		Line 80:

	<code php>		<code php>
	$fields = \~~core~~\~~user_fields~~::for_name()->excluding('firstname')->get_required_fields();		$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();
	</code>		</code>

Line 104:		Line 104:
	<code php>		<code php>
	$context = \context_system::instance();		$context = \context_system::instance();
	$userfields = \~~core~~\~~user_fields~~::for_name()->with_identity($context)->excluding('id', 'deleted');		$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');
	</code>		</code>

Line 139:		Line 139:

	<code php>		<code php>
	$extracolumns = $userfields->get_required_fields([\~~core~~\~~user_fields~~::PURPOSE_IDENTITY]);		$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);
	</code>		</code>

Line 147:		Line 147:

	<code php>		<code php>
	$header = \~~core~~\~~user_fields~~::get_display_name($field);		$header = \core_user\fields::get_display_name($field);
	</code>		</code>

Stronk7: Stronk7 moved page User fields API to User fields: removing the api suffix as requested

2021-03-11T13:30:14Z

Stronk7 moved page User fields API to User fields: removing the api suffix as requested

← Older revision	Revision as of 13:30, 11 March 2021
(No difference)

Quen at 12:54, 11 March 2021

2021-03-11T12:54:52Z

← Older revision		Revision as of 12:54, 11 March 2021
Line 3:		Line 3:
	Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.		Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

	* See also [[User-related APIs]] which has information about defining custom user fields.		* See also [[User-related APIs]], which has information about defining custom user fields.

	== Overview ==		== Overview ==

Quen at 12:54, 11 March 2021

2021-03-11T12:54:40Z

← Older revision		Revision as of 12:54, 11 March 2021
Line 2:		Line 2:

	Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.		Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

			* See also [[User-related APIs]] which has information about defining custom user fields.

	== Overview ==		== Overview ==

Quen at 12:47, 11 March 2021

2021-03-11T12:47:06Z

← Older revision		Revision as of 12:47, 11 March 2021
Line 1:		Line 1:
	{{Moodle 3.11}}		{{Moodle 3.11}}

	~~The~~ user fields ~~API~~ is ~~located~~ in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.		Code relating to display of user fields is in the class <tt>\core\user_fields</tt> in file <tt>/lib/classes/user_fields.php</tt>.

	== Overview ==		== Overview ==

	This ~~API~~ is normally used when displaying lists of users in a table. It has the following main functions.		This class is normally used when displaying lists of users in a table. It has the following main functions.

	# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.		# Decide which extra user fields (e.g. email, username) should be shown in the table, based on the <tt>showuseridentity</tt> admin setting, the current context, and the permissions of the user.
Line 13:		Line 13:
	== Custom fields ==		== Custom fields ==

	This ~~API~~ supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.		This class supports two kinds of fields: basic user fields (in the <tt>user</tt> table) and custom profile fields (in the <tt>user_info_data</tt> table). Because the queries are more complex when getting custom profile fields, there may be some code that doesn't support custom profile fields.

	When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.		When fields are listed, a standard field in the user table such as email is called <tt>email</tt>. A custom profile field, such as one with the shortname frog, is prefixed so that it is referred to as <tt>profile_field_frog</tt>.

Quen: /* Getting SQL */

2021-03-11T12:38:25Z

Getting SQL

← Older revision		Revision as of 12:38, 11 March 2021
Line 87:		Line 87:
	In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.		In most cases it is not very useful to just get a list of fields. You also need to create the SQL to obtain the values for the fields.

	Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is ~~the~~ basic SQL that does this:		Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

	<code ~~sql~~>		<code php>
	SELECT u.id, u.deleted		$result = $DB->get_records_sql("
	FROM {user} u		SELECT u.id, u.deleted
	ORDER BY u.lastaccess DESC		FROM {user} u
			ORDER BY u.lastaccess DESC", [], 0, 10);
	</code>		</code>

Line 104:		Line 105:
	</code>		</code>

	The user fields object can ~~write the~~ SQL for you like this:		The user fields object can create SQL snippets for you like this:

	<code php>		<code php>
Line 114:		Line 115:
	<code php>		<code php>
	$result = $DB->get_records_sql("		$result = $DB->get_records_sql("
	SELECT id, deleted {$sql->selects}		SELECT u.id, u.deleted {$sql->selects}
	FROM {user} u		FROM {user} u
	{$sql->joins}		{$sql->joins}
	ORDER BY u.lastaccess DESC", $sql->params, 0, 10);		ORDER BY u.lastaccess DESC", $sql->params, 0, 10);
	</code>		</code>

Quen: /* Add or remove arbitrary extra fields */

2021-03-11T12:31:12Z

Add or remove arbitrary extra fields

← Older revision		Revision as of 12:31, 11 March 2021
Line 75:		Line 75:
	</code>		</code>

	Alternatively you might want to exclude a field - this ~~could~~ be if you know you are going to ~~have~~ that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.		Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

	<code php>		<code php>

← Older revision		Revision as of 20:35, 14 July 2021
Line 25:		Line 25:
	=== List fields required to display a user picture ===		=== List fields required to display a user picture ===

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fields = \core_user\fields::for_userpic()->get_required_fields();		$fields = \core_user\fields::for_userpic()->get_required_fields();
	</syntaxhighlight>		</syntaxhighlight>
Line 35:		Line 35:
	=== List fields required to display a user's full name ===		=== List fields required to display a user's full name ===

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fields = \core_user\fields::for_name()->get_required_fields();		$fields = \core_user\fields::for_name()->get_required_fields();
	</syntaxhighlight>		</syntaxhighlight>
Line 45:		Line 45:
	=== List fields required to display a user picture and full name ===		=== List fields required to display a user picture and full name ===

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();		$fields = \core_user\fields::for_name()->with_userpic()->get_required_fields();
	</syntaxhighlight>		</syntaxhighlight>
Line 57:		Line 57:
	Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.		Because the capability for the current user depends on the location you are looking at, you need to pass a context when getting these fields.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fields = \core_user\fields::for_identity($context)->get_required_fields();		$fields = \core_user\fields::for_identity($context)->get_required_fields();
	</syntaxhighlight>		</syntaxhighlight>
Line 63:		Line 63:
	The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:		The list of fields from this function might include custom profile fields e.g. 'profile_field_frog'. In legacy code which only supports fields on the user table, you can pass false to the second 'allow custom fields' parameter of the function:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fields = \core_user\fields::for_identity($context, false)->get_required_fields();		$fields = \core_user\fields::for_identity($context, false)->get_required_fields();
	</syntaxhighlight>		</syntaxhighlight>
Line 73:		Line 73:
	Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:		Sometimes you might want a list of fields to contain extra fields. You could just add them to the array, but that could cause duplicates in some situations which might result in bugs that only appear in certain settings. Instead, there is a convenient way to include them in these lists:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();		$fields = \core_user\fields::for_identity($context)->including('email')->get_required_fields();
	</syntaxhighlight>		</syntaxhighlight>
Line 79:		Line 79:
	Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.		Alternatively you might want to exclude a field - this would usually be because you know you are going to list that field in a database query separately. It is OK to exclude a field whether or not it is actually included; that way the code will continue to work whatever the field list.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();		$fields = \core_user\fields::for_name()->excluding('firstname')->get_required_fields();
	</syntaxhighlight>		</syntaxhighlight>
Line 91:		Line 91:
	Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:		Let's use a simple example - we are writing code that displays a list of all users in the whole system ordered by their last access date, most recent first. For some reason we are also including deleted users (but maybe we're going to display them differently). Here is a basic SQL query that does this:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$result = $DB->get_records_sql("		$result = $DB->get_records_sql("
	SELECT u.id, u.deleted		SELECT u.id, u.deleted
Line 102:		Line 102:
	We can create a user fields object like this:		We can create a user fields object like this:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$context = \context_system::instance();		$context = \context_system::instance();
	$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');		$userfields = \core_user\fields::for_name()->with_identity($context)->excluding('id', 'deleted');
Line 109:		Line 109:
	The user fields object can create SQL snippets for you like this:		The user fields object can create SQL snippets for you like this:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$sql = $userfields->get_sql('u');		$sql = $userfields->get_sql('u');
	</syntaxhighlight>		</syntaxhighlight>
Line 115:		Line 115:
	This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:		This returns an object with the fields 'selects', 'joins', 'params', and (not normally needed) 'mappings'. Here is how you use it with the above SQL query:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$result = $DB->get_records_sql("		$result = $DB->get_records_sql("
	SELECT u.id, u.deleted {$sql->selects}		SELECT u.id, u.deleted {$sql->selects}
Line 138:		Line 138:
	An extra parameter on get_required_fields lets you include only one category of fields from the object:		An extra parameter on get_required_fields lets you include only one category of fields from the object:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);		$extracolumns = $userfields->get_required_fields([\core_user\fields::PURPOSE_IDENTITY]);
	</syntaxhighlight>		</syntaxhighlight>
Line 146:		Line 146:
	To display those columns you will need a header with a field name. You can get a field name as follows:		To display those columns you will need a header with a field name. You can get a field name as follows:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$header = \core_user\fields::get_display_name($field);		$header = \core_user\fields::get_display_name($field);
	</syntaxhighlight>		</syntaxhighlight>

User fields - Revision history

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Quen at 12:40, 29 March 2021

Quen: Updated for new location of class

Stronk7: Stronk7 moved page User fields API to User fields: removing the api suffix as requested

Quen at 12:54, 11 March 2021

Quen at 12:54, 11 March 2021

Quen at 12:47, 11 March 2021

Quen: /* Getting SQL */

Quen: /* Add or remove arbitrary extra fields */

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""