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



お勧め

フィードにサムネイル画像を追加する(2022年11月1日 更新)

WordPressが出力するの標準のフィードには、各投稿のサムネイル画像の情報が含まれていない。ネットで検索してみるといくつかの方法があることがわかったので、その中から2つ試してみた。

投稿一覧に「投稿フォーマット」フィルターが追加される(2019年4月12日 更新)

WordPress 5.2 Beta2(以降5.2Beta2)のソースコードを眺めていると、投稿一覧ページのフィルター機能に「投稿フォーマット」(select要素)が追加されていた。

5.5の機能強化:コメントフォームのちょっとした改良(2020年8月12日 更新)

来月にリリースされるWordPress 5.5に向けてBeta 1、2、3と公開が続いている。「WordPress 5.5 Beta 3(以降Beta 3)」のソースコードを見ていくと、コメントフォームを表示する comment_form関数が機能拡張されていた。

Login rebuilderに「XML-RPC設定」を追加しました(2018年5月27日 更新)

公式サイトで公開しているプラグイン「Login rebuilder」をバージョンアップし、XML-RPCリクエストの管理機能を追加しました。Login rebuilderの主たる機能は、ログインページをサイト別にユニークなURLに変更し、ログインページへの不正アクセスを回避することです。WordPressのXML-RPCリクエストはピンバックや外部ツールやサイトなどとの連携に利用されていますが、今回追加した機能ではXML-RPCリクエストの処理に対していくつかの制限できるようにしています。

index.htmlでアーカイブページを表示させる(2011年10月14日 更新)

静的なサイトでは、各ディレクトリにindex.htmlファイルを置き、そのディレクトリの内容を紹介することが多い。WordPressで構築したサイトも同様にできないかと考え、試行錯誤してみた(こんなことを考えてるのは自分だけだろうか!?)。