From c610440f4682666ed4c6fb37faeba39306acb701 Mon Sep 17 00:00:00 2001 From: hellofromTonya Date: Tue, 9 Nov 2021 00:23:58 +0000 Subject: [PATCH] Users: Introduce `wp_list_users()` function. Introduces a new function called `wp_list_users()`. Similar to other list functions such as `wp_list_authors()`, it lists all the users of the site. Options are available to configure the HTML output. Following the same pattern of the other list functions, the list's HTML output is rendered by default. Setting the `echo` argument to `false`, returns the list's HTML output. A new test class is included. Props afercia, audrasjb, chriscct7, costdev, desrosj, greenshady, hellofromTonya, mte90, nacin, rohan013, sergeybiryukov. Fixes #15145. Built from https://develop.svn.wordpress.org/trunk@52064 git-svn-id: http://core.svn.wordpress.org/trunk@51656 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/user.php | 120 ++++++++++++++++++++++++++++++++++++++++ wp-includes/version.php | 2 +- 2 files changed, 121 insertions(+), 1 deletion(-) diff --git a/wp-includes/user.php b/wp-includes/user.php index fb01d38dad..49f4f3fa7d 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -765,6 +765,126 @@ function get_users( $args = array() ) { return (array) $user_search->get_results(); } +/** + * List all the users of the site, with several options available. + * + * @since 5.9.0 + * + * @param string|array $args { + * Optional. Array or string of default arguments. + * + * @type string $orderby How to sort the users. Accepts 'nicename', 'email', 'url', 'registered', + * 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name', + * 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'. Default 'name'. + * @type string $order Sorting direction for $orderby. Accepts 'ASC', 'DESC'. Default 'ASC'. + * @type int $number Maximum users to return or display. Default empty (all users). + * @type bool $exclude_admin Whether to exclude the 'admin' account, if it exists. Default false. + * @type bool $show_fullname Whether to show the user's full name. Default false. + * @type string $feed If not empty, show a link to the user's feed and use this text as the alt + * parameter of the link. Default empty. + * @type string $feed_image If not empty, show a link to the user's feed and use this image URL as + * clickable anchor. Default empty. + * @type string $feed_type The feed type to link to, such as 'rss2'. Defaults to default feed type. + * @type bool $echo Whether to output the result or instead return it. Default true. + * @type string $style If 'list', each user is wrapped in an `
  • ` element, otherwise the users + * will be separated by commas. + * @type bool $html Whether to list the items in HTML form or plaintext. Default true. + * @type string $exclude An array, comma-, or space-separated list of user IDs to exclude. Default empty. + * @type string $include An array, comma-, or space-separated list of user IDs to include. Default empty. + * } + * @return string|null The output if echo is false. Otherwise null. + */ +function wp_list_users( $args = array() ) { + $defaults = array( + 'orderby' => 'name', + 'order' => 'ASC', + 'number' => '', + 'exclude_admin' => true, + 'show_fullname' => false, + 'feed' => '', + 'feed_image' => '', + 'feed_type' => '', + 'echo' => true, + 'style' => 'list', + 'html' => true, + 'exclude' => '', + 'include' => '', + ); + + $args = wp_parse_args( $args, $defaults ); + + $return = ''; + + $query_args = wp_array_slice_assoc( $args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) ); + $query_args['fields'] = 'ids'; + $users = get_users( $query_args ); + + foreach ( $users as $user_id ) { + $user = get_userdata( $user_id ); + + if ( $args['exclude_admin'] && 'admin' === $user->display_name ) { + continue; + } + + if ( $args['show_fullname'] && '' !== $user->first_name && '' !== $user->last_name ) { + $name = "$user->first_name $user->last_name"; + } else { + $name = $user->display_name; + } + + if ( ! $args['html'] ) { + $return .= $name . ', '; + + continue; // No need to go further to process HTML. + } + + if ( 'list' === $args['style'] ) { + $return .= '
  • '; + } + + $row = $name; + + if ( ! empty( $args['feed_image'] ) || ! empty( $args['feed'] ) ) { + $row .= ' '; + if ( empty( $args['feed_image'] ) ) { + $row .= '('; + } + + $row .= ''; + } else { + $row .= $name; + } + + $row .= ''; + + if ( empty( $args['feed_image'] ) ) { + $row .= ')'; + } + } + + $return .= $row; + $return .= ( 'list' === $args['style'] ) ? '
  • ' : ', '; + } + + $return = rtrim( $return, ', ' ); + + if ( ! $args['echo'] ) { + return $return; + } + echo $return; +} + /** * Get the sites a user belongs to. * diff --git a/wp-includes/version.php b/wp-includes/version.php index 2332cc7d2d..2004144583 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '5.9-alpha-52063'; +$wp_version = '5.9-alpha-52064'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.