WP_REST_Users_Controller::get_items( WP_REST_Request $request ): WP_REST_Response|WP_Error

In this article

Retrieves all users.

Parameters

$requestWP_REST_Requestrequired
Full details about the request.

Return

WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.

Source

public function get_items( $request ) {

	// Retrieve the list of registered collection query parameters.
	$registered = $this->get_collection_params();

	/*
	 * This array defines mappings between public API query parameters whose
	 * values are accepted as-passed, and their internal WP_Query parameter
	 * name equivalents (some are the same). Only values which are also
	 * present in $registered will be set.
	 */
	$parameter_mappings = array(
		'exclude'      => 'exclude',
		'include'      => 'include',
		'order'        => 'order',
		'per_page'     => 'number',
		'search'       => 'search',
		'roles'        => 'role__in',
		'capabilities' => 'capability__in',
		'slug'         => 'nicename__in',
	);

	$prepared_args = array();

	/*
	 * For each known parameter which is both registered and present in the request,
	 * set the parameter's value on the query $prepared_args.
	 */
	foreach ( $parameter_mappings as $api_param => $wp_param ) {
		if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
			$prepared_args[ $wp_param ] = $request[ $api_param ];
		}
	}

	if ( isset( $registered['offset'] ) && ! empty( $request['offset'] ) ) {
		$prepared_args['offset'] = $request['offset'];
	} else {
		$prepared_args['offset'] = ( $request['page'] - 1 ) * $prepared_args['number'];
	}

	if ( isset( $registered['orderby'] ) ) {
		$orderby_possibles        = array(
			'id'              => 'ID',
			'include'         => 'include',
			'name'            => 'display_name',
			'registered_date' => 'registered',
			'slug'            => 'user_nicename',
			'include_slugs'   => 'nicename__in',
			'email'           => 'user_email',
			'url'             => 'user_url',
		);
		$prepared_args['orderby'] = $orderby_possibles[ $request['orderby'] ];
	}

	if ( isset( $registered['who'] ) && ! empty( $request['who'] ) && 'authors' === $request['who'] ) {
		$prepared_args['who'] = 'authors';
	} elseif ( ! current_user_can( 'list_users' ) ) {
		$prepared_args['has_published_posts'] = get_post_types( array( 'show_in_rest' => true ), 'names' );
	}

	if ( ! empty( $request['has_published_posts'] ) ) {
		$prepared_args['has_published_posts'] = ( true === $request['has_published_posts'] )
			? get_post_types( array( 'show_in_rest' => true ), 'names' )
			: (array) $request['has_published_posts'];
	}

	if ( ! empty( $prepared_args['search'] ) ) {
		if ( ! current_user_can( 'list_users' ) ) {
			$prepared_args['search_columns'] = array( 'ID', 'user_login', 'user_nicename', 'display_name' );
		}
		$prepared_args['search'] = '*' . $prepared_args['search'] . '*';
	}
	/**
	 * Filters WP_User_Query arguments when querying users via the REST API.
	 *
	 * @link https://developer.wordpress.org/reference/classes/wp_user_query/
	 *
	 * @since 4.7.0
	 *
	 * @param array           $prepared_args Array of arguments for WP_User_Query.
	 * @param WP_REST_Request $request       The REST API request.
	 */
	$prepared_args = apply_filters( 'rest_user_query', $prepared_args, $request );

	$query = new WP_User_Query( $prepared_args );

	$users = array();

	foreach ( $query->results as $user ) {
		$data    = $this->prepare_item_for_response( $user, $request );
		$users[] = $this->prepare_response_for_collection( $data );
	}

	$response = rest_ensure_response( $users );

	// Store pagination values for headers then unset for count query.
	$per_page = (int) $prepared_args['number'];
	$page     = (int) ceil( ( ( (int) $prepared_args['offset'] ) / $per_page ) + 1 );

	$prepared_args['fields'] = 'ID';

	$total_users = $query->get_total();

	if ( $total_users < 1 ) {
		// Out-of-bounds, run the query again without LIMIT for total count.
		unset( $prepared_args['number'], $prepared_args['offset'] );
		$count_query = new WP_User_Query( $prepared_args );
		$total_users = $count_query->get_total();
	}

	$response->header( 'X-WP-Total', (int) $total_users );

	$max_pages = (int) ceil( $total_users / $per_page );

	$response->header( 'X-WP-TotalPages', $max_pages );

	$base = add_query_arg( urlencode_deep( $request->get_query_params() ), rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ) );
	if ( $page > 1 ) {
		$prev_page = $page - 1;

		if ( $prev_page > $max_pages ) {
			$prev_page = $max_pages;
		}

		$prev_link = add_query_arg( 'page', $prev_page, $base );
		$response->link_header( 'prev', $prev_link );
	}
	if ( $max_pages > $page ) {
		$next_page = $page + 1;
		$next_link = add_query_arg( 'page', $next_page, $base );

		$response->link_header( 'next', $next_link );
	}

	return $response;
}

Hooks

apply_filters( ‘rest_user_query’, array $prepared_args, WP_REST_Request $request )

Filters WP_User_Query arguments when querying users via the REST API.

Changelog

VersionDescription
4.7.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.