WordPress Version: 6.2
/**
* Creates dropdown HTML content of users.
*
* The content can either be displayed, which it is by default or retrieved by
* setting the 'echo' argument. The 'include' and 'exclude' arguments do not
* need to be used; all users will be displayed in that case. Only one can be
* used, either 'include' or 'exclude', but not both.
*
* The available arguments are as follows:
*
* @since 2.3.0
* @since 4.5.0 Added the 'display_name_with_login' value for 'show'.
* @since 4.7.0 Added the `$role`, `$role__in`, and `$role__not_in` parameters.
*
* @param array|string $args {
* Optional. Array or string of arguments to generate a drop-down of users.
* See WP_User_Query::prepare_query() for additional available arguments.
*
* @type string $show_option_all Text to show as the drop-down default (all).
* Default empty.
* @type string $show_option_none Text to show as the drop-down default when no
* users were found. Default empty.
* @type int|string $option_none_value Value to use for $show_option_none when no users
* were found. Default -1.
* @type string $hide_if_only_one_author Whether to skip generating the drop-down
* if only one user was found. Default empty.
* @type string $orderby Field to order found users by. Accepts user fields.
* Default 'display_name'.
* @type string $order Whether to order users in ascending or descending
* order. Accepts 'ASC' (ascending) or 'DESC' (descending).
* Default 'ASC'.
* @type int[]|string $include Array or comma-separated list of user IDs to include.
* Default empty.
* @type int[]|string $exclude Array or comma-separated list of user IDs to exclude.
* Default empty.
* @type bool|int $multi Whether to skip the ID attribute on the 'select' element.
* Accepts 1|true or 0|false. Default 0|false.
* @type string $show 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.
* Default 'display_name'.
* @type int|bool $echo Whether to echo or return the drop-down. Accepts 1|true (echo)
* or 0|false (return). Default 1|true.
* @type int $selected Which user ID should be selected. Default 0.
* @type bool $include_selected Whether to always include the selected user ID in the drop-
* down. Default false.
* @type string $name Name attribute of select element. Default 'user'.
* @type string $id ID attribute of the select element. Default is the value of $name.
* @type string $class Class attribute of the select element. Default empty.
* @type int $blog_id ID of blog (Multisite only). Default is ID of the current blog.
* @type string $who Which type of users to query. Accepts only an empty string or
* 'authors'. Default empty.
* @type string|array $role 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. Default empty.
* @type string[] $role__in An array of role names. Matched users must have at least one of
* these roles. Default empty array.
* @type string[] $role__not_in An array of role names to exclude. Users matching one or more of
* these roles will not be included in results. Default empty array.
* }
* @return string HTML dropdown list of users.
*/
function wp_dropdown_users($args = '')
{
$defaults = array('show_option_all' => '', 'show_option_none' => '', 'hide_if_only_one_author' => '', 'orderby' => 'display_name', 'order' => 'ASC', 'include' => '', 'exclude' => '', 'multi' => 0, 'show' => 'display_name', 'echo' => 1, 'selected' => 0, 'name' => 'user', 'class' => '', 'id' => '', 'blog_id' => get_current_blog_id(), 'who' => '', 'include_selected' => false, 'option_none_value' => -1, 'role' => '', 'role__in' => array(), 'role__not_in' => array(), 'capability' => '', 'capability__in' => array(), 'capability__not_in' => array());
$defaults['selected'] = is_author() ? get_query_var('author') : 0;
$parsed_args = wp_parse_args($args, $defaults);
$query_args = wp_array_slice_assoc($parsed_args, array('blog_id', 'include', 'exclude', 'orderby', 'order', 'who', 'role', 'role__in', 'role__not_in', 'capability', 'capability__in', 'capability__not_in'));
$fields = array('ID', 'user_login');
$show = (!empty($parsed_args['show'])) ? $parsed_args['show'] : 'display_name';
if ('display_name_with_login' === $show) {
$fields[] = 'display_name';
} else {
$fields[] = $show;
}
$query_args['fields'] = $fields;
$show_option_all = $parsed_args['show_option_all'];
$show_option_none = $parsed_args['show_option_none'];
$option_none_value = $parsed_args['option_none_value'];
/**
* Filters the query arguments for the list of users in the dropdown.
*
* @since 4.4.0
*
* @param array $query_args The query arguments for get_users().
* @param array $parsed_args The arguments passed to wp_dropdown_users() combined with the defaults.
*/
$query_args = apply_filters('wp_dropdown_users_args', $query_args, $parsed_args);
$users = get_users($query_args);
$output = '';
if (!empty($users) && (empty($parsed_args['hide_if_only_one_author']) || count($users) > 1)) {
$name = esc_attr($parsed_args['name']);
if ($parsed_args['multi'] && !$parsed_args['id']) {
$id = '';
} else {
$id = $parsed_args['id'] ? " id='" . esc_attr($parsed_args['id']) . "'" : " id='{$name}'";
}
$output = "<select name='{$name}'{$id} class='" . $parsed_args['class'] . "'>\n";
if ($show_option_all) {
$output .= "\t<option value='0'>{$show_option_all}</option>\n";
}
if ($show_option_none) {
$_selected = selected($option_none_value, $parsed_args['selected'], false);
$output .= "\t<option value='" . esc_attr($option_none_value) . "'{$_selected}>{$show_option_none}</option>\n";
}
if ($parsed_args['include_selected'] && $parsed_args['selected'] > 0) {
$found_selected = false;
$parsed_args['selected'] = (int) $parsed_args['selected'];
foreach ((array) $users as $user) {
$user->ID = (int) $user->ID;
if ($user->ID === $parsed_args['selected']) {
$found_selected = true;
}
}
if (!$found_selected) {
$selected_user = get_userdata($parsed_args['selected']);
if ($selected_user) {
$users[] = $selected_user;
}
}
}
foreach ((array) $users as $user) {
if ('display_name_with_login' === $show) {
/* translators: 1: User's display name, 2: User login. */
$display = sprintf(_x('%1$s (%2$s)', 'user dropdown'), $user->display_name, $user->user_login);
} elseif (!empty($user->{$show})) {
$display = $user->{$show};
} else {
$display = '(' . $user->user_login . ')';
}
$_selected = selected($user->ID, $parsed_args['selected'], false);
$output .= "\t<option value='{$user->ID}'{$_selected}>" . esc_html($display) . "</option>\n";
}
$output .= '</select>';
}
/**
* Filters the wp_dropdown_users() HTML output.
*
* @since 2.3.0
*
* @param string $output HTML output generated by wp_dropdown_users().
*/
$html = apply_filters('wp_dropdown_users', $output);
if ($parsed_args['echo']) {
echo $html;
}
return $html;
}