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' ) ); ?>

フィルター

実行するフィルターはありません。

アクション

実行するアクションはありません。

ソースファイル

/wp-includes/user.php

最終更新 : 2022年07月19日 15:36



お勧め

5.5で非推奨になる関数名について(2020年8月12日 更新)

来月にリリースされるWordPress 5.5に向けてBeta 1、2と公開が続いている。「WordPress 5.5 Beta 2(以降Beta 2)」のソースコードを見ていくと、いくつかの関数が非推奨になるようだ。

meta_compare_key使ってみた(2019年3月19日 更新)

ブロックエディターの登場により、標準のカスタムフィールドを使う機会はかなり減った気がする。そんな中、5.1.0で追加されたのが、カスタムフィールド名(メタキー)に含まれる文字列を指定する'meta_compare_key'キーだ。

プラグインの設定ページもレスポンシブ対応(2014年6月3日 更新)

レスポンシブ対応したWordPressの管理画面。プラグインやテーマのカスタマイズで管理画面を拡張しているなら、切り替わるタイミングはきっちり押さえておきたいところではないだろうか。

初期化に関連するアクションのおさらい(2013年11月27日 更新)

いつも何気なくfunctions.phpで使っているafter_setup_themeアクションやinitアクション。普段はあまり意識していなかったが、ふとしたことからどんな順番に呼び出されるのか気になってしまい、ちょっと調べてみた。

全投稿を取得するのはnopaging=1でいい(2011年8月31日 更新)

query_posts関数(またはWP_Queryクラス)を使う場合、取得する件数の指定を省略すると管理者ページの「表示設定」-「1ページに表示する最大件数」の指定値分だけの投稿情報を取得する。それでは条件にマッチするすべての投稿情報を取得するには?