Make WordPress Core


Ignore:
Timestamp:
11/20/2021 12:06:06 AM (3 years ago)
Author:
johnbillion
Message:

Query: Correct and standardise the meta query documentation.

Also improves the formatting of some surrounding documentation.

Props audrasjb, johnbillion

Fixes #53467

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-wp-user-query.php

    r51943 r52226  
    137137     * @since 4.7.0 Added 'nicename', 'nicename__in', 'nicename__not_in', 'login', 'login__in',
    138138     *              and 'login__not_in' parameters.
     139     * @since 5.1.0 Introduced the 'meta_compare_key' parameter.
     140     * @since 5.3.0 Introduced the 'meta_type_key' parameter.
    139141     * @since 5.9.0 Added 'capability', 'capability__in', and 'capability__not_in' parameters.
    140142     *
     
    145147     *     Optional. Array or string of Query parameters.
    146148     *
    147      *     @type int          $blog_id             The site ID. Default is the current site.
    148      *     @type string|array $role                An array or a comma-separated list of role names that users must match
    149      *                                             to be included in results. Note that this is an inclusive list: users
    150      *                                             must match *each* role. Default empty.
    151      *     @type string[]     $role__in            An array of role names. Matched users must have at least one of these
    152      *                                             roles. Default empty array.
    153      *     @type string[]     $role__not_in        An array of role names to exclude. Users matching one or more of these
    154      *                                             roles will not be included in results. Default empty array.
    155      *     @type string       $capability          An array or a comma-separated list of capability names that users must match
    156      *                                             to be included in results. Note that this is an inclusive list: users
    157      *                                             must match *each* capability.
    158      *                                             Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
    159      *                                             Default empty.
    160      *     @type string[]     $capability__in      An array of capability names. Matched users must have at least one of these
    161      *                                             capabilities.
    162      *                                             Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
    163      *                                             Default empty array.
    164      *     @type string[]     $capability__not_in  An array of capability names to exclude. Users matching one or more of these
    165      *                                             capabilities will not be included in results.
    166      *                                             Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
    167      *                                             Default empty array.
    168      *     @type string       $meta_key            User meta key. Default empty.
    169      *     @type string       $meta_value          User meta value. Default empty.
    170      *     @type string       $meta_compare        Comparison operator to test the `$meta_value`. Accepts '=', '!=',
    171      *                                             '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN',
    172      *                                             'BETWEEN', 'NOT BETWEEN', 'EXISTS', 'NOT EXISTS', 'REGEXP',
    173      *                                             'NOT REGEXP', or 'RLIKE'. Default '='.
    174      *     @type int[]        $include             An array of user IDs to include. Default empty array.
    175      *     @type int[]        $exclude             An array of user IDs to exclude. Default empty array.
    176      *     @type string       $search              Search keyword. Searches for possible string matches on columns.
    177      *                                             When `$search_columns` is left empty, it tries to determine which
    178      *                                             column to search in based on search string. Default empty.
    179      *     @type string[]     $search_columns      Array of column names to be searched. Accepts 'ID', 'user_login',
    180      *                                             'user_email', 'user_url', 'user_nicename', 'display_name'.
    181      *                                             Default empty array.
    182      *     @type string|array $orderby             Field(s) to sort the retrieved users by. May be a single value,
    183      *                                             an array of values, or a multi-dimensional array with fields as
    184      *                                             keys and orders ('ASC' or 'DESC') as values. Accepted values are
    185      *                                             'ID', 'display_name' (or 'name'), 'include', 'user_login'
    186      *                                             (or 'login'), 'login__in', 'user_nicename' (or 'nicename'),
    187      *                                             'nicename__in', 'user_email (or 'email'), 'user_url' (or 'url'),
    188      *                                             'user_registered' (or 'registered'), 'post_count', 'meta_value',
    189      *                                             'meta_value_num', the value of `$meta_key`, or an array key of
    190      *                                             `$meta_query`. To use 'meta_value' or 'meta_value_num', `$meta_key`
    191      *                                             must be also be defined. Default 'user_login'.
    192      *     @type string       $order               Designates ascending or descending order of users. Order values
    193      *                                             passed as part of an `$orderby` array take precedence over this
    194      *                                             parameter. Accepts 'ASC', 'DESC'. Default 'ASC'.
    195      *     @type int          $offset              Number of users to offset in retrieved results. Can be used in
    196      *                                             conjunction with pagination. Default 0.
    197      *     @type int          $number              Number of users to limit the query for. Can be used in
    198      *                                             conjunction with pagination. Value -1 (all) is supported, but
    199      *                                             should be used with caution on larger sites.
    200      *                                             Default -1 (all users).
    201      *     @type int          $paged               When used with number, defines the page of results to return.
    202      *                                             Default 1.
    203      *     @type bool         $count_total         Whether to count the total number of users found. If pagination
    204      *                                             is not needed, setting this to false can improve performance.
    205      *                                             Default true.
    206      *     @type string|array $fields              Which fields to return. Single or all fields (string), or array
    207      *                                             of fields. Accepts 'ID', 'display_name', 'user_login',
    208      *                                             'user_nicename', 'user_email', 'user_url', 'user_registered'.
    209      *                                             Use 'all' for all fields and 'all_with_meta' to include
    210      *                                             meta fields. Default 'all'.
    211      *     @type string       $who                 Type of users to query. Accepts 'authors'.
    212      *                                             Default empty (all users).
    213      *     @type bool|array   $has_published_posts Pass an array of post types to filter results to users who have
    214      *                                             published posts in those post types. `true` is an alias for all
    215      *                                             public post types.
    216      *     @type string       $nicename            The user nicename. Default empty.
    217      *     @type string[]     $nicename__in        An array of nicenames to include. Users matching one of these
    218      *                                             nicenames will be included in results. Default empty array.
    219      *     @type string[]     $nicename__not_in    An array of nicenames to exclude. Users matching one of these
    220      *                                             nicenames will not be included in results. Default empty array.
    221      *     @type string       $login               The user login. Default empty.
    222      *     @type string[]     $login__in           An array of logins to include. Users matching one of these
    223      *                                             logins will be included in results. Default empty array.
    224      *     @type string[]     $login__not_in       An array of logins to exclude. Users matching one of these
    225      *                                             logins will not be included in results. Default empty array.
     149     *     @type int             $blog_id             The site ID. Default is the current site.
     150     *     @type string|array    $role                An array or a comma-separated list of role names that users must match
     151     *                                                to be included in results. Note that this is an inclusive list: users
     152     *                                                must match *each* role. Default empty.
     153     *     @type string[]        $role__in            An array of role names. Matched users must have at least one of these
     154     *                                                roles. Default empty array.
     155     *     @type string[]        $role__not_in        An array of role names to exclude. Users matching one or more of these
     156     *                                                roles will not be included in results. Default empty array.
     157     *     @type string|string[] $meta_key            Meta key or keys to filter by.
     158     *     @type string|string[] $meta_value          Meta value or values to filter by.
     159     *     @type string          $meta_compare        MySQL operator used for comparing the meta value.
     160     *                                                See WP_Meta_Query::__construct for accepted values and default value.
     161     *     @type string          $meta_compare_key    MySQL operator used for comparing the meta key.
     162     *                                                See WP_Meta_Query::__construct for accepted values and default value.
     163     *     @type string          $meta_type           MySQL data type that the meta_value column will be CAST to for comparisons.
     164     *                                                See WP_Meta_Query::__construct for accepted values and default value.
     165     *     @type string          $meta_type_key       MySQL data type that the meta_key column will be CAST to for comparisons.
     166     *                                                See WP_Meta_Query::__construct for accepted values and default value.
     167     *     @type array           $meta_query          An associative array of WP_Meta_Query arguments.
     168     *                                                See WP_Meta_Query::__construct for accepted values.
     169     *     @type string          $capability          An array or a comma-separated list of capability names that users must match
     170     *                                                to be included in results. Note that this is an inclusive list: users
     171     *                                                must match *each* capability.
     172     *                                                Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
     173     *                                                Default empty.
     174     *     @type string[]        $capability__in      An array of capability names. Matched users must have at least one of these
     175     *                                                capabilities.
     176     *                                                Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
     177     *                                                Default empty array.
     178     *     @type string[]        $capability__not_in  An array of capability names to exclude. Users matching one or more of these
     179     *                                                capabilities will not be included in results.
     180     *                                                Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}.
     181     *                                                Default empty array.
     182     *     @type int[]           $include             An array of user IDs to include. Default empty array.
     183     *     @type int[]           $exclude             An array of user IDs to exclude. Default empty array.
     184     *     @type string          $search              Search keyword. Searches for possible string matches on columns.
     185     *                                                When `$search_columns` is left empty, it tries to determine which
     186     *                                                column to search in based on search string. Default empty.
     187     *     @type string[]        $search_columns      Array of column names to be searched. Accepts 'ID', 'user_login',
     188     *                                                'user_email', 'user_url', 'user_nicename', 'display_name'.
     189     *                                                Default empty array.
     190     *     @type string|array    $orderby             Field(s) to sort the retrieved users by. May be a single value,
     191     *                                                an array of values, or a multi-dimensional array with fields as
     192     *                                                keys and orders ('ASC' or 'DESC') as values. Accepted values are:
     193     *                                                - 'ID'
     194     *                                                - 'display_name' (or 'name')
     195     *                                                - 'include'
     196     *                                                - 'user_login' (or 'login')
     197     *                                                - 'login__in'
     198     *                                                - 'user_nicename' (or 'nicename'),
     199     *                                                - 'nicename__in'
     200     *                                                - 'user_email (or 'email')
     201     *                                                - 'user_url' (or 'url'),
     202     *                                                - 'user_registered' (or 'registered')
     203     *                                                - 'post_count'
     204     *                                                - 'meta_value',
     205     *                                                - 'meta_value_num'
     206     *                                                - The value of `$meta_key`
     207     *                                                - An array key of `$meta_query`
     208     *                                                To use 'meta_value' or 'meta_value_num', `$meta_key`
     209     *                                                must be also be defined. Default 'user_login'.
     210     *     @type string          $order               Designates ascending or descending order of users. Order values
     211     *                                                passed as part of an `$orderby` array take precedence over this
     212     *                                                parameter. Accepts 'ASC', 'DESC'. Default 'ASC'.
     213     *     @type int             $offset              Number of users to offset in retrieved results. Can be used in
     214     *                                                conjunction with pagination. Default 0.
     215     *     @type int             $number              Number of users to limit the query for. Can be used in
     216     *                                                conjunction with pagination. Value -1 (all) is supported, but
     217     *                                                should be used with caution on larger sites.
     218     *                                                Default -1 (all users).
     219     *     @type int             $paged               When used with number, defines the page of results to return.
     220     *                                                Default 1.
     221     *     @type bool            $count_total         Whether to count the total number of users found. If pagination
     222     *                                                is not needed, setting this to false can improve performance.
     223     *                                                Default true.
     224     *     @type string|array    $fields              Which fields to return. Single or all fields (string), or array
     225     *                                                of fields. Accepts:
     226     *                                                - 'ID'
     227     *                                                - 'display_name'
     228     *                                                - 'user_login'
     229     *                                                - 'user_nicename'
     230     *                                                - 'user_email'
     231     *                                                - 'user_url'
     232     *                                                - 'user_registered'
     233     *                                                - 'all' for all fields
     234     *                                                - 'all_with_meta' to include meta fields.
     235     *                                                Default 'all'.
     236     *     @type string          $who                 Type of users to query. Accepts 'authors'.
     237     *                                                Default empty (all users).
     238     *     @type bool|array      $has_published_posts Pass an array of post types to filter results to users who have
     239     *                                                published posts in those post types. `true` is an alias for all
     240     *                                                public post types.
     241     *     @type string          $nicename            The user nicename. Default empty.
     242     *     @type string[]        $nicename__in        An array of nicenames to include. Users matching one of these
     243     *                                                nicenames will be included in results. Default empty array.
     244     *     @type string[]        $nicename__not_in    An array of nicenames to exclude. Users matching one of these
     245     *                                                nicenames will not be included in results. Default empty array.
     246     *     @type string          $login               The user login. Default empty.
     247     *     @type string[]        $login__in           An array of logins to include. Users matching one of these
     248     *                                                logins will be included in results. Default empty array.
     249     *     @type string[]        $login__not_in       An array of logins to exclude. Users matching one of these
     250     *                                                logins will not be included in results. Default empty array.
    226251     * }
    227252     */
Note: See TracChangeset for help on using the changeset viewer.