Make WordPress Core


Ignore:
Timestamp:
05/19/2024 07:51:38 PM (2 months ago)
Author:
SergeyBiryukov
Message:

Docs: Add a note that the who parameter in WP_User_Query is deprecated.

Any usage of 'who' => 'authors' should be updated to use capability queries instead.

Includes documenting the capability query parameters in wp_dropdown_users().

Follow-up to [51943].

Props kkmuffme, swissspidy, SergeyBiryukov.
See #61243.

File:
1 edited

Legend:

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

    r58071 r58172  
    15411541 * @since 2.3.0
    15421542 * @since 4.5.0 Added the 'display_name_with_login' value for 'show'.
    1543  * @since 4.7.0 Added the `$role`, `$role__in`, and `$role__not_in` parameters.
     1543 * @since 4.7.0 Added the 'role', 'role__in', and 'role__not_in' parameters.
     1544 * @since 5.9.0 Added the 'capability', 'capability__in', and 'capability__not_in' parameters.
     1545 *              Deprecated the 'who' parameter.
    15441546 *
    15451547 * @param array|string $args {
     
    15471549 *     See WP_User_Query::prepare_query() for additional available arguments.
    15481550 *
    1549  *     @type string       $show_option_all         Text to show as the drop-down default (all).
    1550  *                                                 Default empty.
    1551  *     @type string       $show_option_none        Text to show as the drop-down default when no
    1552  *                                                 users were found. Default empty.
    1553  *     @type int|string   $option_none_value       Value to use for $show_option_none when no users
    1554  *                                                 were found. Default -1.
    1555  *     @type string       $hide_if_only_one_author Whether to skip generating the drop-down
    1556  *                                                 if only one user was found. Default empty.
    1557  *     @type string       $orderby                 Field to order found users by. Accepts user fields.
    1558  *                                                 Default 'display_name'.
    1559  *     @type string       $order                   Whether to order users in ascending or descending
    1560  *                                                 order. Accepts 'ASC' (ascending) or 'DESC' (descending).
    1561  *                                                 Default 'ASC'.
    1562  *     @type int[]|string $include                 Array or comma-separated list of user IDs to include.
    1563  *                                                 Default empty.
    1564  *     @type int[]|string $exclude                 Array or comma-separated list of user IDs to exclude.
    1565  *                                                 Default empty.
    1566  *     @type bool|int     $multi                   Whether to skip the ID attribute on the 'select' element.
    1567  *                                                 Accepts 1|true or 0|false. Default 0|false.
    1568  *     @type string       $show                    User data to display. If the selected item is empty
    1569  *                                                 then the 'user_login' will be displayed in parentheses.
    1570  *                                                 Accepts any user field, or 'display_name_with_login' to show
    1571  *                                                 the display name with user_login in parentheses.
    1572  *                                                 Default 'display_name'.
    1573  *     @type int|bool     $echo                    Whether to echo or return the drop-down. Accepts 1|true (echo)
    1574  *                                                 or 0|false (return). Default 1|true.
    1575  *     @type int          $selected                Which user ID should be selected. Default 0.
    1576  *     @type bool         $include_selected        Whether to always include the selected user ID in the drop-
    1577  *                                                 down. Default false.
    1578  *     @type string       $name                    Name attribute of select element. Default 'user'.
    1579  *     @type string       $id                      ID attribute of the select element. Default is the value of $name.
    1580  *     @type string       $class                   Class attribute of the select element. Default empty.
    1581  *     @type int          $blog_id                 ID of blog (Multisite only). Default is ID of the current blog.
    1582  *     @type string       $who                     Which type of users to query. Accepts only an empty string or
    1583  *                                                 'authors'. Default empty.
    1584  *     @type string|array $role                    An array or a comma-separated list of role names that users must
    1585  *                                                 match to be included in results. Note that this is an inclusive
    1586  *                                                 list: users must match *each* role. Default empty.
    1587  *     @type string[]     $role__in                An array of role names. Matched users must have at least one of
    1588  *                                                 these roles. Default empty array.
    1589  *     @type string[]     $role__not_in            An array of role names to exclude. Users matching one or more of
    1590  *                                                 these roles will not be included in results. Default empty array.
     1551 *     @type string          $show_option_all         Text to show as the drop-down default (all).
     1552 *                                                    Default empty.
     1553 *     @type string          $show_option_none        Text to show as the drop-down default when no
     1554 *                                                    users were found. Default empty.
     1555 *     @type int|string      $option_none_value       Value to use for `$show_option_none` when no users
     1556 *                                                    were found. Default -1.
     1557 *     @type string          $hide_if_only_one_author Whether to skip generating the drop-down
     1558 *                                                    if only one user was found. Default empty.
     1559 *     @type string          $orderby                 Field to order found users by. Accepts user fields.
     1560 *                                                    Default 'display_name'.
     1561 *     @type string          $order                   Whether to order users in ascending or descending
     1562 *                                                    order. Accepts 'ASC' (ascending) or 'DESC' (descending).
     1563 *                                                    Default 'ASC'.
     1564 *     @type int[]|string    $include                 Array or comma-separated list of user IDs to include.
     1565 *                                                    Default empty.
     1566 *     @type int[]|string    $exclude                 Array or comma-separated list of user IDs to exclude.
     1567 *                                                    Default empty.
     1568 *     @type bool|int        $multi                   Whether to skip the ID attribute on the 'select' element.
     1569 *                                                    Accepts 1|true or 0|false. Default 0|false.
     1570 *     @type string          $show                    User data to display. If the selected item is empty
     1571 *                                                    then the 'user_login' will be displayed in parentheses.
     1572 *                                                    Accepts any user field, or 'display_name_with_login' to show
     1573 *                                                    the display name with user_login in parentheses.
     1574 *                                                    Default 'display_name'.
     1575 *     @type int|bool        $echo                    Whether to echo or return the drop-down. Accepts 1|true (echo)
     1576 *                                                    or 0|false (return). Default 1|true.
     1577 *     @type int             $selected                Which user ID should be selected. Default 0.
     1578 *     @type bool            $include_selected        Whether to always include the selected user ID in the drop-
     1579 *                                                    down. Default false.
     1580 *     @type string          $name                    Name attribute of select element. Default 'user'.
     1581 *     @type string          $id                      ID attribute of the select element. Default is the value of `$name`.
     1582 *     @type string          $class                   Class attribute of the select element. Default empty.
     1583 *     @type int             $blog_id                 ID of blog (Multisite only). Default is ID of the current blog.
     1584 *     @type string          $who                     Deprecated, use `$capability` instead.
     1585 *                                                    Which type of users to query. Accepts only an empty string or
     1586 *                                                    'authors'. Default empty (all users).
     1587 *     @type string|string[] $role                    An array or a comma-separated list of role names that users
     1588 *                                                    must match to be included in results. Note that this is
     1589 *                                                    an inclusive list: users must match *each* role. Default empty.
     1590 *     @type string[]        $role__in                An array of role names. Matched users must have at least one
     1591 *                                                    of these roles. Default empty array.
     1592 *     @type string[]        $role__not_in            An array of role names to exclude. Users matching one or more
     1593 *                                                    of these roles will not be included in results. Default empty array.
     1594 *     @type string|string[] $capability              An array or a comma-separated list of capability names that users
     1595 *                                                    must match to be included in results. Note that this is
     1596 *                                                    an inclusive list: users must match *each* capability.
     1597 *                                                    Does NOT work for capabilities not in the database or filtered
     1598 *                                                    via {@see 'map_meta_cap'}. Default empty.
     1599 *     @type string[]        $capability__in          An array of capability names. Matched users must have at least one
     1600 *                                                    of these capabilities.
     1601 *                                                    Does NOT work for capabilities not in the database or filtered
     1602 *                                                    via {@see 'map_meta_cap'}. Default empty array.
     1603 *     @type string[]        $capability__not_in      An array of capability names to exclude. Users matching one or more
     1604 *                                                    of these capabilities will not be included in results.
     1605 *                                                    Does NOT work for capabilities not in the database or filtered
     1606 *                                                    via {@see 'map_meta_cap'}. Default empty array.
    15911607 * }
    15921608 * @return string HTML dropdown list of users.
Note: See TracChangeset for help on using the changeset viewer.