Add a wp_list_users() template tag

[greenshady]

Now that get_users() has been implemented (#14572), I propose we add a function called wp_list_users() that handles a basic list of users similar to wp_list_authors(). WordPress has long needed a function for handling this.

The arguments for the function would simply be the same arguments used for get_users(). The wp_list_users() function would basically be a function for outputting the HTML. The function should also have the ability to link to the user's archive page and output a link to the user's RSS feed.

This would make it easy for theme developers and users to be able to create a users list without a lot of PHP work.

An alternate idea might be to push a few more arguments into the wp_list_authors() function, but I don't think that's the best route to go since its primary function is to list users that have written posts.

[nacin]

Would need a patch.

[rohan013]

Adds a new function wp_list_users() which is very similar to wp_list_authors except the 'optioncount' and 'hide_empty' args since they are not valid here.

[Mte90]

patch refreshed

[afercia]

In 15145.2.diff​ naming a variable $return is potentially confusing, for better code readability I'd suggest to rename it. Also needs some minor coding standards.

Add wp_list_users function.

Trac ticket: https://core.trac.wordpress.org/ticket/15145

[Mte90]

Refreshed also this one but is still missing unit tests

[audrasjb]

Hey,
I'm not super convinced by the style parameter. First it doesn't exist on related functions like wp_list_pages, second I don't think the function should output anything else than a list. But it would be nice to add a hook to help to filter the output, just like wp_list_pages does:

    /**
     * Filters the HTML output of the pages to list.
     *
     * @since 5.8.0
     *
     * @see wp_list_users()
     *
     * @param string    $output      HTML output of the users list.
     * @param array     $parsed_args An array of user-listing arguments. See wp_list_users()
     *                               for information on accepted arguments.
     * @param WP_User[] $users       Array of the user objects.
     */
    $html = apply_filters( 'wp_list_users', $output, $parsed_args, $users );

Also, the PR needs an @since mention :)

[Mte90]

Updated the patch with this feedback except for the style.

Maybe it is the case to move the style part to a function like get_the_term_list for users?

[audrasjb]

@Mte90 ok the patch looks good to me, thanks for the update. By the way, there are some minor check failures on the proposed PR :)

[Mte90]

I saw that errors but they are not on the right lines and so on and I cannot rerun jobs to update the checks itself.

I can't rerun the jobs as the linting is wrong as that lines are clean and report errors on the wrong lines.

[desrosj]

Today is feature freeze for 5.8. Since a committer has not had a chance to review this one, I'm going to punt.

I'm putting this in 5.9 instead of Future Release, though. And I'll try to return to it in the next cycle.

@Mte90 I did push an update to your branch that should fix the coding standards issues! Also, it would be great if we could add some unit tests. Looks like wp_list_authors() has some. We could probably use those as a starting point.

[Mte90]

Thanks for the help I will check for the unit tests :-)

[Mte90]

I did the unit tests months ago but I cannot check the logs now to see the errors as they are expired.

[costdev]

Refresh + Unit tests added.

[costdev]

Patch 15145.3.diff refreshes the previous patch against trunk and adds unit tests for the wp_list_users() function.

The tests for wp_list_authors() and unit tests written for wp_list_users() in ​PR 1059 test arguments like exclude. Such arguments are handled by the call to get_users() and are not touched by wp_list_users().

This patch does not test these arguments and instead tests only the expected behaviour of wp_list_users().

[audrasjb]

The patch and tests look good to me. I tested the $echo/$html/$style param variations and it works fine on my side.

[hellofromTonya]

Reassigning review to me in preparation for commit consideration prior to 5.9 feature freeze.

[audrasjb]

I saw a few inconsistencies between this functions and other existing functions like wp_list_pages or wp_list_categories.

for instance, if $style !== 'list' the wp_list_categories function uses <br /> as a separator.

wp_list_users() makes it easy for extenders to create a basic list of users, similar to wp_list_authors().

Trac ticket: https://core.trac.wordpress.org/ticket/15145

[hellofromTonya]

Replying to audrasjb:

I saw a few inconsistencies between this functions and other existing functions like wp_list_pages or wp_list_categories.

for instance, if $style !== 'list' the wp_list_categories function uses <br /> as a separator.

I see differences between the existing functions themselves. Guessing each has been tailored for its specific list of things.

This new function most closely resembles wp_list_authors().

[hellofromTonya]

​PR 1837 includes the patch and tests. It's approved. Marking for commit.

[hellofromTonya]

In 52064:

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.

Committed via changeset https://core.trac.wordpress.org/changeset/52064.

This patch was pulled into PR #1837 which was committed via changeset https://core.trac.wordpress.org/changeset/52064.