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.3の新機能:クエリーログに任意の項目を追加できる新フィルター(2019年10月23日 更新)

5.3 RC2」が公開され、正式リリースまであと20日。公式ディレクトリにプラグインを公開していることもあり、5.3に関する開発者向けの情報「Miscellaneous Developer Focused Changes in 5.3」を読んでいる。

個人データのエクスポートメール向けに追加された新フィルター(2020年4月2日 更新)

先週「WordPress 5.4 RC3」が公開され、正式リリースまであと1週間。ブロックエディターの機能強化が目立つわけですが、地味な変更点もちらほらと。今回はその中の1つ、「個人データのエクスポート」機能に関連するフィルターを紹介する。

投稿内容に応じてwpautopを制御する(2013年8月13日 更新)

投稿内容を表示する the_content関数では、 wpautop関数がフィルターの1つとして呼び出され、改行をbrタグに変換したり、pタグで調整したりする。この機能自体は便利なのだが、きちんとデザインされたHTMLソースを流し込んだ場合はこの機能は好ましくない。そんなわけで、記事内容に応じてwpautop関数を制御できないか考えてみた。

新「WordPress Events and News」ウィジェットが興味深い(2018年5月27日 更新)

4.8のベータ版ですぐに新機能とわかるのが管理者ダッシュボードの新「WordPress Events and News」ウィジェット。ユーザーが指定した地域近隣で開催されるイベント情報を表示してくれるウィジェットで、この中のフォームがちょっと興味深かった。なおこの記事はWordPress 4.8 beta-2をもとにしており、以降のバージョンで変更される可能性があることをあらかじめ断っておく。

各種リンクを取得する関数一覧(2014年6月12日 更新)

サイト設計において、ページ間の相互リンクは重要である。WordPressでは各種ページのリンク(パーマリンク)を取得する関数を用意しており、それらを一通り把握しておくべきだろう。