The inline documentation on the $fields query variable of the WP_User_Query

[birgire]

I hope I'm understanding this correctly, but it looks like we might need to update the description for the $fields query variable in the WP_User_Query class:

@type string|array $fields              Which fields to return. Single or all fields (string), or array
*                                             of fields. Accepts 'ID', 'display_name', 'login', 'nicename',
*                                             'email', 'url', 'registered'. Use 'all' for all fields and
*                                             'all_with_meta' to include meta fields. Default 'all'.

This is the relevant part of the WP_User_Query that handles the fields query variable:

if ( is_array( $qv['fields'] ) ) {
	$qv['fields'] = array_unique( $qv['fields'] );
	$this->query_fields = array();
	foreach ( $qv['fields'] as $field ) {
		$field = 'ID' === $field ? 'ID' : sanitize_key( $field );
		$this->query_fields[] = "$wpdb->users.$field";
	}
	$this->query_fields = implode( ',', $this->query_fields );
} elseif ( 'all' == $qv['fields'] ) {
	$this->query_fields = "$wpdb->users.*";
} else {
	$this->query_fields = "$wpdb->users.ID";
}

We can test the following:

// Returns user ID
$args = array(
	'fields' => 'login',
);

// Returns user ID
$args = array(
	'fields' => 'user_login',
);

// Returns all user fields
$args = array(
	'fields' => 'all',
);

// Returns user ID
$args = array(
	'fields' => 'ID',
);

// Gives SQL Error: Unknown column 'wp_users.login' in 'field list']
$args = array(
	'fields' => [ 'login' ],
);
	
// Works, returns the user_login field
$args = array(
	'fields' => [ 'user_login' ],
);

// User Query	
$users = get_users( $args );
var_dump( $users );

So if we try to use string fields other than 'all', 'ID', 'all_with_meta' we just get the user ID.

If we want to return fields like email, login, etc then we need to use correct wp_users table field names, within an array, like:

array( 'user_login', 'user_email' );

If this is correct, then the question is should we update the inline documentation to reflect the current code, or vice versa ?

... or am I looking at it in a wrong way here ?

[boonebgorges]

Thanks for the report, birgire.

Your understanding of the way 'fields' works is correct. Incorrect documentation was introduced in [29843].

[boonebgorges]

In 35645:

Correct documentation for 'fields' param of WP_User_Query.

[29843] introduced this documentation, and incorrectly stated that short
column names (eg 'login' instead of 'user_login') could be used.

Props birgire.
Fixes #34701.

[birgire]

Great, glad we fixed that one ;-)

It looks like we need to update the Codex as well:

​https://codex.wordpress.org/Class_Reference/WP_User_Query#Return_Fields_Parameter

that seems to have influenced other tutorials, like this one recently:

​http://code.tutsplus.com/tutorials/mastering-wp_user_query--cms-23204

where it uses 'fields' => 'email' to return only the emails.

I therefore guess there have been other users scratching their heads because of this parameter ;-)