wp_dropdown_users( array|string $args = '' ): string

Description

Compatibility

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

Parameters

$argsarray|stringoptional

Array or string of arguments to generate a drop-down of users. See WP_User_Query::prepare_query() for additional available arguments.Default: ''

• $show_option_allstringdefault: empty

  Text to show as the drop-down default (all).

• $show_option_nonestringdefault: empty

  Text to show as the drop-down default when no users were found.

• $option_none_valueint|stringdefault: -1

  Value to use for $show_option_none when no users were found.

• $hide_if_only_one_authorstringdefault: empty

  Whether to skip generating the drop-down if only one user was found.

• $orderbystringdefault: 'display_name'

  Field to order found users by. Accepts user fields.

• $orderstringdefault: 'ASC'

  Whether to order users in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC' (descending).

• $includeint[]|stringdefault: empty

  Array or comma-separated list of user IDs to include.

• $excludeint[]|stringdefault: empty

  Array or comma-separated list of user IDs to exclude.

• $multibool|intdefault: 0|false

  Whether to skip the ID attribute on the 'select' element. Accepts 1|true or 0|false.

• $showstringdefault: 'display_name'

  User data to display. If the selected item is empty then the 'user_login' will be displayed in parentheses. Accepts any user field, or 'display_name_with_login' to show the display name with user_login in parentheses.

• $echoint|booldefault: 1|true

  Whether to echo or return the drop-down. Accepts 1|true (echo) or 0|false (return).

• $selectedintdefault: 0

  Which user ID should be selected.

• $include_selectedbooldefault: false

  Whether to always include the selected user ID in the drop- down.

• $namestringdefault: 'user'

  Name attribute of select element.

• $idstringdefault: is the value of $name

  ID attribute of the select element.

• $classstringdefault: empty

  Class attribute of the select element.

• $blog_idintdefault: is ID of the current blog

  ID of blog (Multisite only).

• $whostringdefault: empty (all users)

  Deprecated, use $capability instead. Which type of users to query. Accepts only an empty string or 'authors'.

• $rolestring|string[]default: empty

  An array or a comma-separated list of role names that users must match to be included in results. Note that this is an inclusive list: users must match each role.

• $role__instring[]default: empty array

  An array of role names. Matched users must have at least one of these roles.

• $role__not_instring[]default: empty array

  An array of role names to exclude. Users matching one or more of these roles will not be included in results.

• $capabilitystring|string[]default: empty

  An array or a comma-separated list of capability names that users must match to be included in results. Note that this is an inclusive list: users must match each capability. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

• $capability__instring[]default: empty array

  An array of capability names. Matched users must have at least one of these capabilities. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

• $capability__not_instring[]default: empty array

  An array of capability names to exclude. Users matching one or more of these capabilities will not be included in results. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

Return value

string

HTML dropdown list of users.

Performance profile

How much work a call to wp_dropdown_users() 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_users().

Scaling

Scales with input

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

Instructions

79–170

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

Plugin surface

2 hooks

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

Called by

2

2 places 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

Further down the call graph this can also reach option, 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 · 9 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_dropdown_users() 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_dropdown_users() runs, in this order:

1. 1
   apply_filters( wp_dropdown_users_args )filterline 1792 (+73 into the body)

   Filters the query arguments for the list of users in the dropdown.

2. 2
   apply_filters( wp_dropdown_users )filterline 1858 (+139 into the body)

   Filters the wp_dropdown_users() HTML output.

Uses · 12

• get_current_blog_id()Retrieves the current site ID.
• is_author()Determines whether the query is for an existing author archive page.
• get_query_var()Retrieves the value of a query variable in the WP_Query class.
• 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.
• esc_attr()Escaping for HTML attributes.
• selected()Outputs the HTML selected attribute.
• get_userdata()Retrieves user info by user ID.
• _x()Retrieves translated string with gettext context.
• esc_html()Escaping for HTML blocks.

Used by · 2

• WP_Posts_List_Table::inline_edit()Outputs the hidden row displayed when inline editing
• post_author_meta_box()Displays form field with list of authors.

Source code

View on Trac ↗View on GitHub ↗

1719function wp_dropdown_users( $args = '' ) {1720	$defaults = array(1721		'show_option_all'         => '',1722		'show_option_none'        => '',1723		'hide_if_only_one_author' => '',1724		'orderby'                 => 'display_name',1725		'order'                   => 'ASC',1726		'include'                 => '',1727		'exclude'                 => '',1728		'multi'                   => 0,1729		'show'                    => 'display_name',1730		'echo'                    => 1,1731		'selected'                => 0,1732		'name'                    => 'user',1733		'class'                   => '',1734		'id'                      => '',1735		'blog_id'                 => get_current_blog_id(),1736		'who'                     => '',1737		'include_selected'        => false,1738		'option_none_value'       => -1,1739		'role'                    => '',1740		'role__in'                => array(),1741		'role__not_in'            => array(),1742		'capability'              => '',1743		'capability__in'          => array(),1744		'capability__not_in'      => array(),1745	);1746 1747	$defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0;1748 1749	$parsed_args = wp_parse_args( $args, $defaults );1750 1751	$query_args = wp_array_slice_assoc(1752		$parsed_args,1753		array(1754			'blog_id',1755			'include',1756			'exclude',1757			'orderby',1758			'order',1759			'who',1760			'role',1761			'role__in',1762			'role__not_in',1763			'capability',1764			'capability__in',1765			'capability__not_in',1766		)1767	);1768 1769	$fields = array( 'ID', 'user_login' );1770 1771	$show = ! empty( $parsed_args['show'] ) ? $parsed_args['show'] : 'display_name';1772	if ( 'display_name_with_login' === $show ) {1773		$fields[] = 'display_name';1774	} else {1775		$fields[] = $show;1776	}1777 1778	$query_args['fields'] = $fields;1779 1780	$show_option_all   = $parsed_args['show_option_all'];1781	$show_option_none  = $parsed_args['show_option_none'];1782	$option_none_value = $parsed_args['option_none_value'];1783 1784	/**1785	 * Filters the query arguments for the list of users in the dropdown.1786	 *1787	 * @since 4.4.01788	 *1789	 * @param array $query_args  The query arguments for get_users().1790	 * @param array $parsed_args The arguments passed to wp_dropdown_users() combined with the defaults.1791	 */1792	$query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $parsed_args );1793 1794	$users = get_users( $query_args );1795 1796	$output = '';1797	if ( ! empty( $users ) && ( empty( $parsed_args['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) {1798		$name = esc_attr( $parsed_args['name'] );

Changelog

Introduced in 2.3.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/user.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.