Make WordPress Core


Ignore:
Timestamp:
11/09/2021 12:22:34 AM (3 years ago)
Author:
hellofromTonya
Message:

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.

File:
1 edited

Legend:

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

    r52063 r52064  
    764764
    765765    return (array) $user_search->get_results();
     766}
     767
     768/**
     769 * List all the users of the site, with several options available.
     770 *
     771 * @since 5.9.0
     772 *
     773 * @param string|array $args {
     774 *     Optional. Array or string of default arguments.
     775 *
     776 *     @type string $orderby       How to sort the users. Accepts 'nicename', 'email', 'url', 'registered',
     777 *                                 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name',
     778 *                                 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'. Default 'name'.
     779 *     @type string $order         Sorting direction for $orderby. Accepts 'ASC', 'DESC'. Default 'ASC'.
     780 *     @type int    $number        Maximum users to return or display. Default empty (all users).
     781 *     @type bool   $exclude_admin Whether to exclude the 'admin' account, if it exists. Default false.
     782 *     @type bool   $show_fullname Whether to show the user's full name. Default false.
     783 *     @type string $feed          If not empty, show a link to the user's feed and use this text as the alt
     784 *                                 parameter of the link. Default empty.
     785 *     @type string $feed_image    If not empty, show a link to the user's feed and use this image URL as
     786 *                                 clickable anchor. Default empty.
     787 *     @type string $feed_type     The feed type to link to, such as 'rss2'. Defaults to default feed type.
     788 *     @type bool   $echo          Whether to output the result or instead return it. Default true.
     789 *     @type string $style         If 'list', each user is wrapped in an `<li>` element, otherwise the users
     790 *                                 will be separated by commas.
     791 *     @type bool   $html          Whether to list the items in HTML form or plaintext. Default true.
     792 *     @type string $exclude       An array, comma-, or space-separated list of user IDs to exclude. Default empty.
     793 *     @type string $include       An array, comma-, or space-separated list of user IDs to include. Default empty.
     794 * }
     795 * @return string|null The output if echo is false. Otherwise null.
     796 */
     797function wp_list_users( $args = array() ) {
     798    $defaults = array(
     799        'orderby'       => 'name',
     800        'order'         => 'ASC',
     801        'number'        => '',
     802        'exclude_admin' => true,
     803        'show_fullname' => false,
     804        'feed'          => '',
     805        'feed_image'    => '',
     806        'feed_type'     => '',
     807        'echo'          => true,
     808        'style'         => 'list',
     809        'html'          => true,
     810        'exclude'       => '',
     811        'include'       => '',
     812    );
     813
     814    $args = wp_parse_args( $args, $defaults );
     815
     816    $return = '';
     817
     818    $query_args           = wp_array_slice_assoc( $args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) );
     819    $query_args['fields'] = 'ids';
     820    $users                = get_users( $query_args );
     821
     822    foreach ( $users as $user_id ) {
     823        $user = get_userdata( $user_id );
     824
     825        if ( $args['exclude_admin'] && 'admin' === $user->display_name ) {
     826            continue;
     827        }
     828
     829        if ( $args['show_fullname'] && '' !== $user->first_name && '' !== $user->last_name ) {
     830            $name = "$user->first_name $user->last_name";
     831        } else {
     832            $name = $user->display_name;
     833        }
     834
     835        if ( ! $args['html'] ) {
     836            $return .= $name . ', ';
     837
     838            continue; // No need to go further to process HTML.
     839        }
     840
     841        if ( 'list' === $args['style'] ) {
     842            $return .= '<li>';
     843        }
     844
     845        $row = $name;
     846
     847        if ( ! empty( $args['feed_image'] ) || ! empty( $args['feed'] ) ) {
     848            $row .= ' ';
     849            if ( empty( $args['feed_image'] ) ) {
     850                $row .= '(';
     851            }
     852
     853            $row .= '<a href="' . get_author_feed_link( $user->ID, $args['feed_type'] ) . '"';
     854
     855            $alt = '';
     856            if ( ! empty( $args['feed'] ) ) {
     857                $alt  = ' alt="' . esc_attr( $args['feed'] ) . '"';
     858                $name = $args['feed'];
     859            }
     860
     861            $row .= '>';
     862
     863            if ( ! empty( $args['feed_image'] ) ) {
     864                $row .= '<img src="' . esc_url( $args['feed_image'] ) . '" style="border: none;"' . $alt . ' />';
     865            } else {
     866                $row .= $name;
     867            }
     868
     869            $row .= '</a>';
     870
     871            if ( empty( $args['feed_image'] ) ) {
     872                $row .= ')';
     873            }
     874        }
     875
     876        $return .= $row;
     877        $return .= ( 'list' === $args['style'] ) ? '</li>' : ', ';
     878    }
     879
     880    $return = rtrim( $return, ', ' );
     881
     882    if ( ! $args['echo'] ) {
     883        return $return;
     884    }
     885    echo $return;
    766886}
    767887
Note: See TracChangeset for help on using the changeset viewer.