wp_list_authors( string|array $args = '' ): void|string

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$argsstring|arrayoptional

Array or string of default arguments.Default: ''

• $orderbystringdefault: 'name'

  How to sort the authors. Accepts 'nicename', 'email', 'url', 'registered', 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name', 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'.

• $orderstringdefault: 'ASC'

  Sorting direction for $orderby. Accepts 'ASC', 'DESC'.

• $numberintdefault: empty (all authors)

  Maximum authors to return or display.

• $optioncountbooldefault: false

  Show the count in parenthesis next to the author's name.

• $exclude_adminbooldefault: true

  Whether to exclude the 'admin' account, if it exists.

• $show_fullnamebooldefault: false

  Whether to show the author's full name.

• $hide_emptybooldefault: true

  Whether to hide any authors with no posts.

• $feedstringdefault: empty

  If not empty, show a link to the author's feed and use this text as the alt parameter of the link.

• $feed_imagestringdefault: empty

  If not empty, show a link to the author's feed and use this image URL as clickable anchor.

• $feed_typestringdefault: is the value of get_default_feed()

  The feed type to link to. Possible values include 'rss2', 'atom'.

• $echobooldefault: true

  Whether to output the result or instead return it.

• $stylestring

  If 'list', each author is wrapped in an <li> element, otherwise the authors will be separated by commas.

• $htmlbooldefault: true

  Whether to list the items in HTML form or plaintext.

• $excludeint[]|stringdefault: empty

  Array or comma/space-separated list of author IDs to exclude.

• $includeint[]|stringdefault: empty

  Array or comma/space-separated list of author IDs to include.

Return value

void|string

Void if 'echo' argument is true, list of authors if 'echo' is false.

Performance profile

How much work a call to wp_list_authors() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->get_results().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

44–63

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 198.

Plugin surface

2 hooks

Third-party callbacks on 'wp_list_authors_args', 'pre_wp_list_authors_post_counts_query' run inside this call, and their cost is not bounded by anything here.

Called by

1

1 place in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• querycontent queryget_users()called directly
• sqldatabase query->get_results()called directly
• optionoption read or writeget_option()one call below wp_list_authors()

Further down the call graph this can also reach cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 2 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_list_authors() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 2

2 hooks fire while wp_list_authors() runs, in this order:

1. 1
   apply_filters( wp_list_authors_args )filterline 490 (+36 into the body)

   Filters the query arguments for the list of all authors of the site.

2. 2
   apply_filters( pre_wp_list_authors_post_counts_query )filterline 502 (+48 into the body)

   Filters whether to short-circuit performing the query for author post counts.

Uses · 11

• wp_parse_args()Merges user defined arguments into defaults array.
• wp_array_slice_assoc()Extracts a slice of an array, given a list of keys.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_users()Retrieves list of users matching criteria.
• get_private_posts_cap_sql()Retrieves the private post SQL based on capability.
• get_userdata()Retrieves user info by user ID.
• _x()Retrieves translated string with gettext context.
• esc_url()Checks and cleans a URL.
• get_author_posts_url()Retrieves the URL to the author page for the user with the ID provided.
• get_author_feed_link()Retrieves the feed link for a given author.
• esc_attr()Escaping for HTML attributes.

Used by · 1

• list_authors()Lists authors.

Source code

View on Trac ↗View on GitHub ↗

454function wp_list_authors( $args = '' ) {455	global $wpdb;456 457	$defaults = array(458		'orderby'       => 'name',459		'order'         => 'ASC',460		'number'        => '',461		'optioncount'   => false,462		'exclude_admin' => true,463		'show_fullname' => false,464		'hide_empty'    => true,465		'feed'          => '',466		'feed_image'    => '',467		'feed_type'     => '',468		'echo'          => true,469		'style'         => 'list',470		'html'          => true,471		'exclude'       => '',472		'include'       => '',473	);474 475	$parsed_args = wp_parse_args( $args, $defaults );476 477	$return = '';478 479	$query_args           = wp_array_slice_assoc( $parsed_args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) );480	$query_args['fields'] = 'ids';481 482	/**483	 * Filters the query arguments for the list of all authors of the site.484	 *485	 * @since 6.1.0486	 *487	 * @param array $query_args  The query arguments for get_users().488	 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults.489	 */490	$query_args = apply_filters( 'wp_list_authors_args', $query_args, $parsed_args );491 492	$authors = get_users( $query_args );493 494	/**495	 * Filters whether to short-circuit performing the query for author post counts.496	 *497	 * @since 6.1.0498	 *499	 * @param int[]|false $post_counts Array of post counts, keyed by author ID.500	 * @param array       $parsed_args The arguments passed to wp_list_authors() combined with the defaults.501	 */502	$post_counts = apply_filters( 'pre_wp_list_authors_post_counts_query', false, $parsed_args );503 504	if ( ! is_array( $post_counts ) ) {505		$post_counts       = array();506		$post_counts_query = $wpdb->get_results(507			"SELECT DISTINCT post_author, COUNT(ID) AS count508			FROM $wpdb->posts509			WHERE " . get_private_posts_cap_sql( 'post' ) . '510			GROUP BY post_author'511		);512 513		foreach ( (array) $post_counts_query as $row ) {514			$post_counts[ $row->post_author ] = $row->count;515		}516	}517 518	foreach ( $authors as $author_id ) {519		$posts = $post_counts[ $author_id ] ?? 0;520 521		if ( ! $posts && $parsed_args['hide_empty'] ) {522			continue;523		}524 525		$author = get_userdata( $author_id );526 527		if ( $parsed_args['exclude_admin'] && 'admin' === $author->display_name ) {528			continue;529		}530 531		if ( $parsed_args['show_fullname'] && $author->first_name && $author->last_name ) {532			$name = sprintf(533				/* translators: 1: User's first name, 2: Last name. */

Changelog

Introduced in 1.2.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/author-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.