WP_User_Query クラスの使い方｜説明・引数・注意点

説明

基本構文

new WP_User_Query( array|string $query = null )

引数

• $query：role、search、orderby、number、meta_query など

戻り値

WP_User_Query オブジェクト。get_results() でユーザーの配列を取得します。

使い方（サンプル）

$uq = new WP_User_Query( array( 'role' => 'editor' ) );
$users = $uq->get_results();

注意点

• 件数が多いサイトでは number と paged で絞ります。
• 合計数は get_total() で取得します。

実務での使いどころ

• ユーザーを、条件（ロール、検索、並び順）で、取得するとき。
• ページ送りつきの、ユーザー一覧を、作るとき（総数は get_total()）。

よくあるミスと対処

• number を指定せず、ユーザーが多いサイトで、大量のデータを、取得してしまう。
• search に、ワイルドカード（*）を付けず、完全一致のように、動く。部分一致は、*キーワード* の形で、指定する。
• get_results() の結果と、get_total() を、取り違える。get_total() は、ページ送りを無視した、総数。

NG例

$q = new WP_User_Query( array( 'search' => 'tar' ) ); // ワイルドカードがなく、完全一致に近い

OK例

$q = new WP_User_Query( array(
	'search'         => '*tar*',
	'search_columns' => array( 'user_login', 'display_name' ),
	'number'         => 20,
) );
$users = $q->get_results();
$total = $q->get_total();

使い分け早見表

関連項目

get_users()、WP_Query

公式リファレンス：WP_User_Query | WordPress Developer Resources