get_users

（3.1.0以降）
get_users - ユーザー情報を取得する

説明

array get_users( [ array $args = array() ] )

ユーザー情報を取得する。

パラメータ

$args

絞り込み条件を連想配列で指定する（省略時は、array()）。

キー名	意味	値の例
blog_id	ブログIDを指定	1
role	ロール（'administrator'、'editor'、'author'、'contributor'、'subscriber'など）か、そのカンマ区切りまたは配列を指定	'administrator'
role__in	[4.4.0]取得対象のロールを配列で指定	array( 'subscriber' )
role__not_in	[4.4.0]取得対象から除外するロールを配列で指定	array( 'administrator' )
meta_key	ユーザーメタ情報のキー名を指定	'wp_user_level'
meta_value	ユーザーメタ情報の値を指定	'ja'
meta_compare	ユーザーメタ情報の比較条件（''、'='、'!='など）を指定	'<''
meta_compare_key	[5.1.0]ユーザーメタ情報のキー名の比較条件を指定	'REGEXP'
meta_type	ユーザーメタ情報の値を比較する際にキャストするMySQLのデータ型を指定	'BINARY'
meta_type_key	[5.3.0]ユーザーメタ情報のキーを比較する際にキャストするMySQLのデータ型を指定	'BINARY'
capability	[5.9.0]所有するcapabilityを単独またはカンマ区切りまたはその配列を指定	'publish_posts'
capability__in	[5.9.0]所有するcapabilityを配列で指定	array( 'edit_posts', 'edit_pages' )
capability__not_in	[5.9.0]除外するcapabilityを配列で指定	array( 'switch_themes', 'activate_plugins' )
include	取得するユーザーIDを配列で指定	array(1,2)
exclude	除外するユーザーIDを配列で指定	array(0)
search	検索キーワードを指定（キーワードの前後に'*'指定可）	'ad*'
search_columns	検索項目（'ID'、'user_login'、'user_email'、'user_url'、'user_nicename'のいずれか）を指定	~~'display_name'~~'search'で指定した値により異なる
orderby	ソート対象の項目名、複数の場合はカンマ区切りか配列を指定（省略時は'user_login'）	'user_nicename'
order	ソート順として'ASC'または'DESC'を指定（省略時は'DESC'）	'ASC'
number	取得件数を指定	5
offset	取得位置を指定（number省略時は無効）	10
paged	[4.4.0]取得位置をページ番号で指定（number省略時は無効）	2
fields	'all'、'all_with_meta'か取得する項目、または項目の配列を指定（省略時は'all'）	array( 'ID', 'display_name' )
who	'authors'以外は無効	'authors'
has_published_posts	[4.3.0]任意の投稿タイプならtrueを、特定の投稿タイプなら投稿タイプ名の配列を指定	true
nicename	[4.7.0]user_nicenameを指定	'john'
nicename__in	[4.7.0]取得対象のuser_nicenameを配列で指定	array( 'john', 'jack' )
nicename__not_in	[4.7.0]取得対象から除外するuser_nicenameを配列で指定	array( 'john', 'jack' )
login	[4.7.0]user_loginを指定	'John1999'
login__in	[4.7.0]取得対象のuser_loginを配列で指定	array( 'John1999', 'Jack765' )
login__not_in	[4.7.0]取得対象から除外するuser_loginを配列で指定	array( 'John1999', 'Jack765' )

返り値

条件にマッチしたユーザー情報（オブジェクト）の配列を返す。ユーザー情報は次の通り。

項目名	意味
ID	ユーザーID
user_login	ログイン名
user_pass	ログインパスワードのハッシュ値
user_nicename	ユーザー名
user_email	メールアドレス
user_url	ホームページURL
user_registered	登録日時
user_activation_key	アクティベーションキー
user_status	ステータス
spam	スパムフラグ
deleted	削除フラグ

注意

内部ではWP_User_Queryクラスを利用してユーザー情報を取得している。

[4.2.0]'orderby'の値として'meta_value_num'をサポート、ソート時のメタ情報の内容を数値として評価する。また'orderby'の値に連想配列が指定できるようになった（キーは項目名、値は'ASC'または'DESC'）。

[4.3.0]'has_published_posts'が追加された。trueを指定した場合はすべての投稿タイプを対象に公開済みの投稿があるユーザー情報を取得する。また配列で投稿タイプを指定した場合はその投稿タイプに公開済みの投稿があるユーザー情報を取得する。

[4.4.0]'paged'が追加された。取得位置は、'number'の値が10の場合、'paged'の値が1なら0（先頭）に、'paged'の値が2なら10になる。

[4.4.0]'role__in'と'role__not_in'が追加された。'role__in'に配列で'administrator'と'editor'を指定した場合はどちらかを所有するユーザー情報を取得する。'role__not_in'に配列で'administrator'と'editor'を指定した場合はどちらかも所有しないユーザー情報を取得する。

[4.4.0]'role'の値として、ロールをカンマ区切りしたものか、ロールを含んだ配列を指定できるようになった。

[4.4.0]'number'の値として、全件を取得する-1がサポートされた。

[4.7.0]'nicename'、'nicename__in'、'nicename__not_in'が追加され、user_nicenameを対象にした検索がサポートされた。

[4.7.0]'login'、'login__in'、'login__not_in'が追加され、user_loginを対象にした検索がサポートされた。

[5.9.0]'capability'、'capability__in'、'capability__not_in'が追加され、ユーザーが所有するcapabilityを対象にした検索がサポートされた。

使用例

すべてのユーザー情報を取得する。
<?php $users = get_users(); ?>
表示名が'ad'から始まるユーザー情報を取得する。
<?php $users = get_users( array( 'search' => 'ad*', 'search_columns' => 'display_name' ); ?>
11件目から5件のユーザー情報を取得する。
<?php $users = get_users( array( 'offset' => 10, 'number' => 5 ); ?>
一部（ここではID、メールアドレス、表示名）のユーザー情報を取得する。
<?php $users = get_users( array( 'fields' => array( 'ID','user_email','display_name' ) ); ?>