• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/get users

提供: WordPress Codex 日本語版
移動先: 案内検索

これは WP_User_Query のラッパー関数です。$args で指定された条件に合うユーザーの配列を取得します。

使い方

<?php get_users( $args ); ?>

パラメータ

<?php $args = array(
	'blog_id'      => $GLOBALS['blog_id'],
	'role'         => '',
	'meta_key'     => '',
	'meta_value'   => '',
	'meta_compare' => '',
	'meta_query'   => array(),
	'date_query'   => array(),
	'include'      => array(),
	'exclude'      => array(),
	'orderby'      => 'login',
	'order'        => 'ASC',
	'offset'       => '',
	'search'       => '',
	'number'       => '',
	'count_total'  => false,
	'fields'       => 'all',
	'who'          => ''
 ); ?>
  • blog_id - 現在のブログの ID。マルチサイトが有効な場合は他の ID を指定できる。
  • role - 指定した権限グループのユーザーのみを返す。
  • include - ID の配列を指定して、その ID を持つユーザーのみを返す。現状では includeexclude (後述)引数の両方を同時に使うことはできない。チケット #23228 を参照。
  • exclude - ID の配列を指定して、その ID を持つユーザーを除外(他の引数に関わらず)して返す。include 引数がセットされていると exclude は無視される。
  • meta_key - wp_usermeta テーブルmeta_key の値を指定。このキーについて meta_value (後述)を持つユーザーを返す。使えるキーは get_userdata() を参照。
  • meta_value - meta_key で指定したキーについて探す meta_value の値。
  • meta_compare - meta_value の値をテストする演算子。有効な値は '!=', '>', '>=', '<', または '<='。デフォルトは '='。
  • meta_query - WP_Meta_Query/enmeta_query の形式で検索条件を指定する。
  • date_query - WP_Date_Query オブジェクトとして処理される配列。user_registered フィールドについて日付のクエリを行うことができる。
  • orderby - ソート順を決める項目。有効な値は 'ID', 'login', 'nicename', 'email', 'url', 'registered', 'display_name', 'post_count', または 'meta_value' ('meta_key' も指定すること。WP_User_Query を参照)。
  • order - ASC (昇順)または DESC (降順)。
  • offset - 検索結果の先頭から指定した数(整数 n)のユーザーを除外して返す。
  • search - この引数を使ってユーザーのメールアドレス、URL、ID、ユーザー名、もしくは表示名を検索する。
  • number - 返すユーザー数の上限を指定。
  • count_total - 常に false。総数を取得するには WP_User_Query/en を呼び出すこと。使い方は ここ/en を参照。
  • fields - 返す配列に含めるフィールドを指定。デフォルトは 'all'。wp_users テーブルのフィールドを配列に入れて指定する。それらのフィールドのみを持つ stdClass オブジェクトの配列が返される。
  • who - 'authors' を指定すると、投稿者(ユーザーレベルが 0 より大きい)のみが返される。

用例

すべての購読者を順序なしリスト形式で表示する基本的な例:

<?php
$blogusers = get_users( 'blog_id=1&orderby=nicename&role=subscriber' );
// WP_User オブジェクトの配列。
foreach ( $blogusers as $user ) {
	echo '<span>' . esc_html( $user->user_email ) . '</span>';
}

'search' フィールドを使う例:

<?php
$blogusers = get_users( array( 'search' => 'john' ) );
// WP_User オブジェクトの配列。
foreach ( $blogusers as $user ) {
	echo '<span>' . esc_html( $user->user_email ) . '</span>';
}

上記の例は、ユーザー名、ID、メールアドレスの何れかが "john" であるすべてのユーザーを探して表示します。 検索クエリの前または後に * を付けるとワイルドカード検索も可能です。 例えば "jo" で始まるすべてのユーザーを検索するには、"jo*" のように指定します。

そうすると結果は、ユーザー名、ID、メールアドレスの何れかが "jo" で始まるすべてのユーザーになります。 この * は検索クエリの前にも後にも付けることができます。 前に付けると、結果は、クエリが末尾に出てくるすべてのユーザーになります。

特定のフィールドを取得する例:

<?php
$blogusers = get_users( array( 'fields' => array( 'display_name' ) ) );
// stdClass オブジェクトの配列。
foreach ( $blogusers as $user ) {
	echo '<span>' . esc_html( $user->display_name ) . '</span>';
}

戻り値

(配列) 
ID、stdClass オブジェクト、または 'fields' パラメータに基づく WP_User オブジェクトの配列。
  • 'fields' が 'all' (デフォルト)または 'all_with_meta' であれば、WP_User オブジェクトの配列を返す。
  • 'fields' に wp_users テーブルのフィールドを入れた配列を指定すると、それらのフィールドのみを持つ stdClass オブジェクトの配列が返される。
  • 'fields' に wp_users テーブルのフィールドを一つ指定すると、ID の配列が返される。

参考

変更履歴

ソースファイル

get_users()wp-includes/user.php にあります。

WP_Meta_Query/en, WP_User_Query/en, WP_User


関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/get_users最新版との差分