説明
パラメータ
- $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
関連
お勧め
6.2に追加されるsearch_columnsパラメータが便利(2023年3月30日 更新)
バージョン6.2では記事検索機能を備えたWP_Queryクラスにsearch_columnsパラメータが追加される。標準のキーワード検索では、タイトル(post_title)、本文(post_content)、抜粋(post_excerpt)が対象になっているが、search_columnsパラメータを使うと対象を絞り込めるようになる。
固定ページのURLの拡張子をhtmlに変更する(2013年3月9日 更新)
固定ページについて、URLを静的ページっぽく拡張子htmlに変更したいという要望を受けることがある。これまでは「.html on PAGES」というプラグインを使っていて特に不満があったわけではないのだが、今回ひょんなことから簡単に対応できることがわかったので、メモ書きしておく。KUSANAGIでマルチサイト(サブドメイン)を試した(2019年8月6日 更新)
本サイトはサブディレクトリタイプのマルチサイト機能を採用して構築しているが、これまでサブドメインタイプは利用した経験はない。マルチサイト機能のサブドメインタイプは以前から1度は試してみたいと思っており、今回実際にサイトを構築してみた。
Fotepo:プラグイン作ってみました(2019年9月19日 更新)
仕事柄、Chromeの「デベロッパーツール」を使ってページのフォントを変更することがある。そんな時、無効なフォント名を指定してしまったり、フォント名をまちがえることがあり、もう少しお手軽にできないかと思って作ったのが今回紹介するプラグイン「Fotepo」である。
カテゴリー専用の投稿一覧と新規投稿メニューを追加する(2012年1月23日 更新)
サイト更新の1クリックを省くため、特定カテゴリーの投稿に対して同じようにメニューを追加してみた。カスタム投稿タイプの専用投稿メニューみたいな感じである。