[wp-trac] [WordPress Trac] #34701: The inline documentation on the $fields query variable of the WP_User_Query

[WordPress Trac]

#34701: The inline documentation on the $fields query variable of the WP_User_Query
--------------------------+-----------------------------
 Reporter:  birgire       |      Owner:
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Users         |    Version:  trunk
 Severity:  normal        |   Keywords:
  Focuses:  docs          |
--------------------------+-----------------------------
 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 ?

--
Ticket URL: <https://core.trac.wordpress.org/ticket/34701>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform