当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「クラスリファレンス/WP User Query」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(用例)
(ユーザー権限パラメータを追加)
 
(4人の利用者による、間の12版が非表示)
2行目: 2行目:
 
== 説明 ==
 
== 説明 ==
  
<tt>WP_User_Query</tt> is a class, defined in {{Trac|wp-includes/user.php}}, that allows querying [[Database_Description|WordPress database]] tables '<tt>[[Database_Description#Table:_wp_users|wp_users]]</tt>' and '<tt>[[Database_Description#Table:_wp_usermeta|wp_usermeta]]</tt>'. This class was introduced in [[Version 3.1]] and as a result, the <tt>WP_User_Search</tt> class got deprecated.
+
<!--<tt>WP_User_Query</tt> is a class, defined in {{Trac|wp-includes/user.php}}, that allows querying [[Database_Description|WordPress database]] tables '<tt>[[Database_Description#Table:_wp_users|wp_users]]</tt>' and '<tt>[[Database_Description#Table:_wp_usermeta|wp_usermeta]]</tt>'. This class was introduced in [[Version 3.1]] and as a result, the <tt>WP_User_Search</tt> class got deprecated.-->
 +
 
 +
<tt>WP_User_Query</tt> は {{Trac|wp-includes/user.php}} に定義されているクラスで、[[データベース構造|データベース]]の <code>[[データベース構造#Table:_wp_users|wp_users]]</code> と <code>[[データベース構造#Table:_wp_usermeta|wp_usermeta]]</code> に関するリクエストを取り扱います。[[Version 3.1|バージョン3.1]] から導入され、<tt>WP_User_Search</tt> が非推奨になりました。
  
 
== 使い方 ==
 
== 使い方 ==
59行目: 61行目:
  
 
; <tt>get()</tt>
 
; <tt>get()</tt>
: Retrieve query variable.
+
: クエリ変数を取得する。
  
 
; <tt>set()</tt>
 
; <tt>set()</tt>
: Set query variable.
+
: クエリ変数をセットする。
  
 
; <tt>get_results()</tt>
 
; <tt>get_results()</tt>
: Return the list of users.
+
: ユーザーのリストを返す。
  
 
; <tt>get_total()</tt>
 
; <tt>get_total()</tt>
: Return the total number of users for the current query.
+
: 現在のクエリでのユーザーの合計数を返す。
  
 
== パラメータ ==
 
== パラメータ ==
74行目: 76行目:
 
=== ユーザー権限パラメータ ===
 
=== ユーザー権限パラメータ ===
  
Show users associated with certain role.
+
特定の権限に関連付けられているユーザーを表示します。
  
* '''<tt>role</tt>''' (''string'') - use [[Roles and Capabilities|User Role]].
+
* '''<tt>role</tt>''' (''string / array'') - ユーザーが持つ権限に一致する権限名の配列、またはコンマ区切りのリストで指定します。これは包括的なリストであることに注意してください。デフォルトは空です。
 +
* '''<tt>role__in</tt>''' (''array'') - ユーザーが持つ権限のいずれかに一致する権限名の配列で指定します。デフォルトは空の配列です。(4.4以降)
 +
* '''<tt>role__not_in</tt>''' (''array'') - 除外する権限名の配列。これらの権限の1つ以上に一致するユーザーは結果に含まれません。デフォルトは空の配列です。(4.4以降)
  
 
'''管理者権限ユーザーの表示'''
 
'''管理者権限ユーザーの表示'''
85行目: 89行目:
  
 
  $user_query = new WP_User_Query( array( 'role' => 'Subscriber' ) );
 
  $user_query = new WP_User_Query( array( 'role' => 'Subscriber' ) );
 +
 +
'''購読者権限ユーザーを除くユーザーの表示'''
 +
 +
$user_query = new WP_User_Query( array( 'role__not_in' => 'Subscriber' ) );
  
 
=== インクルード & エクスクルード パラメータ ===
 
=== インクルード & エクスクルード パラメータ ===
  
Show specific users.
+
特定のユーザーを表示します。
  
* '''<tt>include</tt>''' (''array'') - List of users to be included.
+
* '''<tt>include</tt>''' (''array'') - ユーザのリストが含まれます。
* '''<tt>exclude</tt>''' (''array'') - List of users to be excluded.
+
* '''<tt>exclude</tt>''' (''array'') - ユーザのリストが除外されます。
  
'''Display specific users list'''
+
'''特定のユーザーのリストを表示'''
  
 
  $user_query = new WP_User_Query( array( 'include' => array( 1, 2, 3 ) ) );
 
  $user_query = new WP_User_Query( array( 'include' => array( 1, 2, 3 ) ) );
  
'''Display all users except a specific list of users'''
+
'''ユーザーの特定のリスト以外のすべてのユーザーを表示'''
  
 
  $user_query = new WP_User_Query( array( 'exclude' => array( 4, 5, 6 ) ) );
 
  $user_query = new WP_User_Query( array( 'exclude' => array( 4, 5, 6 ) ) );
119行目: 127行目:
 
** '<tt>ID</tt>' - Search by user id.
 
** '<tt>ID</tt>' - Search by user id.
 
** '<tt>login</tt>' / '<tt>user_login</tt>' - ユーザーログインで検索
 
** '<tt>login</tt>' / '<tt>user_login</tt>' - ユーザーログインで検索
** '<tt>nicename</tt>' / '<tt>user_nicename</tt>' - ユーザーニックネームで検索
+
** '<tt>nicename</tt>' / '<tt>user_nicename</tt>' - ユーザーの nicename で検索(ニックネームではありません)
 
** '<tt>email</tt>' / '<tt>user_email</tt>' - ユーザーのメールアドレスで検索
 
** '<tt>email</tt>' / '<tt>user_email</tt>' - ユーザーのメールアドレスで検索
 
** '<tt>url</tt>' / '<tt>user_url</tt>' - ユーザーのURLで検索
 
** '<tt>url</tt>' / '<tt>user_url</tt>' - ユーザーのURLで検索
154行目: 162行目:
 
=== Order & Orderby パラメータ ===
 
=== Order & Orderby パラメータ ===
  
Sort retrieved Users.
+
ユーザー情報を取得してソートする。
  
* '''<tt>orderby</tt>''' (''string'') - Sort retrieved users by parameter.  Defaults to 'login'.
+
* '''<tt>orderby</tt>''' (''string'') - パラメータでユーザーを取得してソート。 デフォルトは 'login'.
** '<tt>ID</tt>' - Order by user id.
+
** '<tt>ID</tt>' - ユーザーIDの順。
** '<tt>display_name</tt>' - Order by user display name.
+
** '<tt>display_name</tt>' - ユーザー表示名の順。
** '<tt>name</tt>' / '<tt>user_name</tt>' - Order by user name.
+
** '<tt>name</tt>' / '<tt>user_name</tt>' - ユーザー名の順。
** '<tt>login</tt>' / '<tt>user_login</tt>' - Order by user login.
+
** '<tt>include</tt>' - インクルードパラメータで指定したIDの順。'''注意:''' クエリに 'include=IDのリスト' を含める必要があります([[Version 4.1|バージョン4.1]]から使用可能)。
** '<tt>nicename</tt>' / '<tt>user_nicename</tt>' - Order by user nicename.
+
** '<tt>login</tt>' / '<tt>user_login</tt>' - ユーザーログインの順。
** '<tt>email</tt>' / '<tt>user_email</tt>' - Order by user email.
+
** '<tt>nicename</tt>' / '<tt>user_nicename</tt>' - ユーザーの nicename の順(ニックネームではありません)。
** '<tt>url</tt>' / '<tt>user_url</tt>' - Order by user url.
+
** '<tt>email</tt>' / '<tt>user_email</tt>' - ユーザーメールアドレスの順。
** '<tt>registered</tt>' / '<tt>user_registered</tt>' - Order by user registered date.
+
** '<tt>url</tt>' / '<tt>user_url</tt>' - ユーザーURLの順。
** '<tt>post_count</tt>' - Order by user post count.
+
** '<tt>registered</tt>' / '<tt>user_registered</tt>' - ユーザー登録日時の順。
** '<tt>meta_value</tt>' - Note that a 'meta_key=keyname' must also be present in the query (available with [[Version 3.7]]).
+
** '<tt>post_count</tt>' - ユーザー投稿数の順。
 +
** '<tt>meta_value</tt>' - ユーザー・メタデータの値の文字順。'''注意:''' クエリに 'meta_key=キー名' を含める必要があります([[Version 3.7|バージョン3.7]]から使用可能)。
 +
** '<tt>meta_value_num</tt>' - ユーザー・メタデータの値の数値順。'''注意:''' クエリに 'meta_key=キー名' を含める必要があります([[Version 4.2|バージョン4.2]]から使用可能)。
  
* '''<tt>order</tt>''' (''string'') - Designates the ascending or descending order of the '<tt>orderby</tt>' parameter. Defaults to 'ASC'.
+
* '''<tt>order</tt>''' (''文字列'') - '<tt>orderby</tt>' パラメーターを昇順もしくは降順で指定する。 デフォルトは 'ASC'(昇順)。
** '<tt>ASC</tt>' - ascending order from lowest to highest values (1, 2, 3; a, b, c).
+
** '<tt>ASC</tt>' - 最低から最高の値への昇順(1, 2, 3; a, b, c).
** '<tt>DESC</tt>' - descending order from highest to lowest values (3, 2, 1; c, b, a).
+
** '<tt>DESC</tt>' - 最高から最低の値への降順 (3, 2, 1; c, b, a).
  
'''Display users sorted by Post Count, Descending order'''
+
'''投稿数の降順でソートしてユーザーを表示'''
  
 
  $user_query = new WP_User_Query( array ( 'orderby' => 'post_count', 'order' => 'DESC' ) );
 
  $user_query = new WP_User_Query( array ( 'orderby' => 'post_count', 'order' => 'DESC' ) );
  
'''Display users sorted by registered, Ascending order'''
+
'''登録日時の昇順でソートしてユーザーを表示'''
  
 
  $user_query = new WP_User_Query( array ( 'orderby' => 'registered', 'order' => 'ASC' ) );
 
  $user_query = new WP_User_Query( array ( 'orderby' => 'registered', 'order' => 'ASC' ) );
 +
 +
'''ニックネームの昇順でソートしてユーザーを取得'''
 +
<!-- 出典: https://ja.wordpress.org/support/topic/ユーザーのnicknameとuser_nicenameについて/#post-217781 -->
 +
<pre>
 +
$user_query = new WP_User_Query( array(
 +
'order'    => 'ASC',
 +
'orderby'  => 'meta_value',
 +
'meta_key' => 'nickname',
 +
) );
 +
</pre>
  
 
=== カスタムフィールドパラメータ ===
 
=== カスタムフィールドパラメータ ===
  
Show users associated with a certain custom field.
+
表示ユーザーは、特定のカスタムフィールドに関連付けられます。
  
The <tt>[[Class_Reference/WP_Meta_Query | WP_Meta_Query]]</tt> class is used to parse this part of the query since [[Version 3.2|3.2.0]], so check the docs for that class for the full, up to date [[Class_Reference/WP_Meta_Query#Accepted_Arguments | list of arguments]].
+
<tt>[[Class_Reference/WP_Meta_Query | WP_Meta_Query]]</tt> クラスは、 [[Version 3.2|バージョン3.2.0]]以降、クエリのこの部分をパースするために使用されます, so check the docs for that class for the full, up to date [[Class_Reference/WP_Meta_Query#Accepted_Arguments | list of arguments]].
  
* '''<tt>meta_key</tt>''' (''string'') - カスタムフィールドのキー。
+
* '''<tt>meta_key</tt>''' (''文字列'') - カスタムフィールド(ユーザー・メタデータ)のキー。
* '''<tt>meta_value</tt>''' (''string'') - カスタムフィールドの値。
+
* '''<tt>meta_value</tt>''' (''文字列'') - カスタムフィールド(ユーザー・メタデータ)の値。
* '''<tt>meta_compare</tt>''' (''string'') - Operator to test the '<tt>meta_value</tt>'. See <tt>'compare'</tt> below.
+
* '''<tt>meta_compare</tt>''' (''文字列'') - '<tt>meta_value</tt>' との比較演算子。後述の <tt>'compare'</tt> を見てください。
  
* '''<tt>meta_query</tt>''' (''array'') - カスタムフィールドのパラメータ。 (available with [[Version 3.5]]).
+
* '''<tt>meta_query</tt>''' (''array'') - カスタムフィールド(ユーザー・メタデータ)の組み合わせクエリが行えるパラメータ([[Version 3.5|バージョン3.5]]から使用可能)。
 
** '''<tt>key</tt>''' (''string'') - カスタムフィールドのキー。
 
** '''<tt>key</tt>''' (''string'') - カスタムフィールドのキー。
 
** '''<tt>value</tt>''' (''string''|''array'') - カスタムフィールドの値 (''Note'': Array support is limited to a compare value of 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' or 'NOT EXISTS')
 
** '''<tt>value</tt>''' (''string''|''array'') - カスタムフィールドの値 (''Note'': Array support is limited to a compare value of 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' or 'NOT EXISTS')
204行目: 224行目:
 
  $user_query = new WP_User_Query( array( 'meta_key' => 'age', 'meta_value' => '30', 'meta_compare' => '<' ) );
 
  $user_query = new WP_User_Query( array( 'meta_key' => 'age', 'meta_value' => '30', 'meta_compare' => '<' ) );
  
'''Multiple custom user fields handling'''
+
'''複数取り扱うカスタムユーザーフィールド'''
  
 
  $args = array(
 
  $args = array(
252行目: 272行目:
 
戻り値のセット。
 
戻り値のセット。
  
* '''<tt>fields</tt>''' (''string|array'') - Which fields to return. Defaults to ''all''.
+
* '''<tt>fields</tt>''' (''string|array'') - Which fields to return. デフォルトは ''all''.
** '<tt>ID</tt>' - Return an array of user id's.
+
** '<tt>ID</tt>' - ユーザーIDの配列を返す。
** '<tt>display_name</tt>' - Return an array of user display names.
+
** '<tt>display_name</tt>' - ユーザー表示名の配列を返す。
** '<tt>login</tt>' / '<tt>user_login</tt>' - Return an array of user login names.
+
** '<tt>login</tt>' / '<tt>user_login</tt>' - ユーザーログイン名の配列を返す。
** '<tt>nicename</tt>' / '<tt>user_nicename</tt>' - Return an array of user nicenames.
+
** '<tt>nicename</tt>' / '<tt>user_nicename</tt>' - ユーザーの nicename の配列を返す(ニックネームではありません)。
** '<tt>email</tt>' / '<tt>user_email</tt>' - Return an array of user emails.
+
** '<tt>email</tt>' / '<tt>user_email</tt>' - ユーザーのメールアドレスの配列を返す。
** '<tt>url</tt>' / '<tt>user_url</tt>' - Return an array of user urls.
+
** '<tt>url</tt>' / '<tt>user_url</tt>' - ユーザーURLの配列を返す。
** '<tt>registered</tt>' / '<tt>user_registered</tt>' - Return an array of user registered dates.
+
** '<tt>registered</tt>' / '<tt>user_registered</tt>' - ユーザー登録日時の配列を返す。
** '<tt>all</tt> (default) or <tt>all_with_meta</tt>' - Returns an array of [[Class_Reference/WP_User|WP_User]] objects.  Must pass an array to subset fields returned.
+
** '<tt>all</tt> (default) or <tt>all_with_meta</tt>' - [[Class_Reference/WP_User|WP_User]] オブジェクトの配列を返す。フィールドが返されたサブセットに配列を渡す必要があります。
  
'''Return an array of WP_User object'''
+
'''WP_User オブジェクトの配列を返す'''
  
 
  $user_query = new WP_User_Query( array( 'role' => 'editor', 'fields' => 'all_with_meta' ) );
 
  $user_query = new WP_User_Query( array( 'role' => 'editor', 'fields' => 'all_with_meta' ) );
357行目: 377行目:
 
* [[クラスリファレンス/WP_User | WP_User]] class
 
* [[クラスリファレンス/WP_User | WP_User]] class
 
* [[関数リファレンス/get_users|<tt>get_users()</tt>]]
 
* [[関数リファレンス/get_users|<tt>get_users()</tt>]]
* [[Class_Reference/WP_Query | WP_Query]] - Class for post-related queries
+
* [[Class_Reference/WP_Query | WP_Query]] - post-related クエリのクラス
* [[Class_Reference/WP_Comment_Query | WP_Comment_Query]] - Class for comment-related queries
+
* [[Class_Reference/WP_Comment_Query | WP_Comment_Query]] - comment-related クエリのクラス
  
 
{{Class Footer}}
 
{{Class Footer}}
 
  
 
{{原文|Class_Reference/WP_User_Query|151908}}<!--  16:44, 3 June 2015‎ MichaelH  版 -->
 
{{原文|Class_Reference/WP_User_Query|151908}}<!--  16:44, 3 June 2015‎ MichaelH  版 -->
[[Category:未翻訳]]
+
 
 +
{{DEFAULTSORT:WP_User_Query}}
 
[[Category:クラス]]
 
[[Category:クラス]]
 
[[Category:wp3.1]]
 
[[Category:wp3.1]]
 
[[Category:wp3.5]]
 
[[Category:wp3.5]]
 
[[Category:wp4.2]]
 
[[Category:wp4.2]]

2018年1月12日 (金) 15:58時点における最新版

このページ「クラスリファレンス/WP User Query」は未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

説明

WP_User_Querywp-includes/user.php に定義されているクラスで、データベースwp_userswp_usermeta に関するリクエストを取り扱います。バージョン3.1 から導入され、WP_User_Search が非推奨になりました。

使い方

<?php
$args = array(
	.
	.
	.
);

// The Query
$user_query = new WP_User_Query( $args );

// User Loop
if ( ! empty( $user_query->results ) ) {
	foreach ( $user_query->results as $user ) {
		echo '<p>' . $user->display_name . '</p>';
	}
} else {
	echo 'No users found.';
}
?>

メソッド・プロパティ

プロパティ

$query_vars
An associative array containing the query variables and their respective values, after parsing.
$results
An array containing a list of found user id's.
$total_users
Total number of found users for the current query.
$query_fields
SQL 句 for the return fields.
$query_from
SQL 句
$query_where
SQL 句
$query_orderby
SQL 句 for sorting retrieved users.
$query_limit
SQL 句 for limiting retrieved users.

メソッド

get()
クエリ変数を取得する。
set()
クエリ変数をセットする。
get_results()
ユーザーのリストを返す。
get_total()
現在のクエリでのユーザーの合計数を返す。

パラメータ

ユーザー権限パラメータ

特定の権限に関連付けられているユーザーを表示します。

  • role (string / array) - ユーザーが持つ権限に一致する権限名の配列、またはコンマ区切りのリストで指定します。これは包括的なリストであることに注意してください。デフォルトは空です。
  • role__in (array) - ユーザーが持つ権限のいずれかに一致する権限名の配列で指定します。デフォルトは空の配列です。(4.4以降)
  • role__not_in (array) - 除外する権限名の配列。これらの権限の1つ以上に一致するユーザーは結果に含まれません。デフォルトは空の配列です。(4.4以降)

管理者権限ユーザーの表示

$user_query = new WP_User_Query( array( 'role' => 'Administrator' ) );

購読者権限ユーザーの表示

$user_query = new WP_User_Query( array( 'role' => 'Subscriber' ) );

購読者権限ユーザーを除くユーザーの表示

$user_query = new WP_User_Query( array( 'role__not_in' => 'Subscriber' ) );

インクルード & エクスクルード パラメータ

特定のユーザーを表示します。

  • include (array) - ユーザのリストが含まれます。
  • exclude (array) - ユーザのリストが除外されます。

特定のユーザーのリストを表示

$user_query = new WP_User_Query( array( 'include' => array( 1, 2, 3 ) ) );

ユーザーの特定のリスト以外のすべてのユーザーを表示

$user_query = new WP_User_Query( array( 'exclude' => array( 4, 5, 6 ) ) );

ブログパラメータ

Show users associated with certain blog on the network.

  • blog_id (int) - The blog id on a multisite environment. Defaults to the current blog id.

Display users from blog 33

$user_query = new WP_User_Query( array( 'blog_id' => 33 ) );

検索パラメータ

ユーザーの検索

  • search (string) - Searches for possible string matches on columns. Use of the * wildcard before and/or after the string will match on columns starting with*, *ending with, or *containing* the string you enter.
  • search_columns (array) - List of database table columns to matches the search string across multiple columns.
    • 'ID' - Search by user id.
    • 'login' / 'user_login' - ユーザーログインで検索
    • 'nicename' / 'user_nicename' - ユーザーの nicename で検索(ニックネームではありません)
    • 'email' / 'user_email' - ユーザーのメールアドレスで検索
    • 'url' / 'user_url' - ユーザーのURLで検索

We can use the user_search_columns filter to modify the search columns.

Display users based on a keyword search

$user_query = new WP_User_Query( array( 'search' => 'Rami' ) );

Display users based on a keyword search, only on login and email columns

$args = array(
	'search'         => 'Rami',
	'search_columns' => array( 'user_login', 'user_email' )
);
$user_query = new WP_User_Query( $args );

ページ送りパラメータ

Limit retrieved Users.

  • number (int) - The maximum returned number of results (needed in pagination).
  • offset (int) - Offset the returned results (needed in pagination).

10 ユーザーを表示

$user_query = new WP_User_Query( array( 'number' => 10 ) );

Display 5 users starting from 25

$user_query = new WP_User_Query( array( 'number' => 5, 'offset' => 25 ) );

Order & Orderby パラメータ

ユーザー情報を取得してソートする。

  • orderby (string) - パラメータでユーザーを取得してソート。 デフォルトは 'login'.
    • 'ID' - ユーザーIDの順。
    • 'display_name' - ユーザー表示名の順。
    • 'name' / 'user_name' - ユーザー名の順。
    • 'include' - インクルードパラメータで指定したIDの順。注意: クエリに 'include=IDのリスト' を含める必要があります(バージョン4.1から使用可能)。
    • 'login' / 'user_login' - ユーザーログインの順。
    • 'nicename' / 'user_nicename' - ユーザーの nicename の順(ニックネームではありません)。
    • 'email' / 'user_email' - ユーザーメールアドレスの順。
    • 'url' / 'user_url' - ユーザーURLの順。
    • 'registered' / 'user_registered' - ユーザー登録日時の順。
    • 'post_count' - ユーザー投稿数の順。
    • 'meta_value' - ユーザー・メタデータの値の文字順。注意: クエリに 'meta_key=キー名' を含める必要があります(バージョン3.7から使用可能)。
    • 'meta_value_num' - ユーザー・メタデータの値の数値順。注意: クエリに 'meta_key=キー名' を含める必要があります(バージョン4.2から使用可能)。
  • order (文字列) - 'orderby' パラメーターを昇順もしくは降順で指定する。 デフォルトは 'ASC'(昇順)。
    • 'ASC' - 最低から最高の値への昇順(1, 2, 3; a, b, c).
    • 'DESC' - 最高から最低の値への降順 (3, 2, 1; c, b, a).

投稿数の降順でソートしてユーザーを表示

$user_query = new WP_User_Query( array ( 'orderby' => 'post_count', 'order' => 'DESC' ) );

登録日時の昇順でソートしてユーザーを表示

$user_query = new WP_User_Query( array ( 'orderby' => 'registered', 'order' => 'ASC' ) );

ニックネームの昇順でソートしてユーザーを取得

$user_query = new WP_User_Query( array(
	'order'    => 'ASC',
	'orderby'  => 'meta_value',
	'meta_key' => 'nickname',
) );

カスタムフィールドパラメータ

表示ユーザーは、特定のカスタムフィールドに関連付けられます。

WP_Meta_Query クラスは、 バージョン3.2.0以降、クエリのこの部分をパースするために使用されます, so check the docs for that class for the full, up to date list of arguments.

  • meta_key (文字列) - カスタムフィールド(ユーザー・メタデータ)のキー。
  • meta_value (文字列) - カスタムフィールド(ユーザー・メタデータ)の値。
  • meta_compare (文字列) - 'meta_value' との比較演算子。後述の 'compare' を見てください。
  • meta_query (array) - カスタムフィールド(ユーザー・メタデータ)の組み合わせクエリが行えるパラメータ(バージョン3.5から使用可能)。
    • key (string) - カスタムフィールドのキー。
    • value (string|array) - カスタムフィールドの値 (Note: Array support is limited to a compare value of 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' or 'NOT EXISTS')
    • compare (string) - Operator to test。有効な値は、 '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS', and 'NOT EXISTS'. デフォルト値は '='.
      注: Currently 'NOT EXISTS' does not always work as intended if 'relation' is 'OR' when, (1) using the 'role' parameter on single site installs, or (2) for any query on multisite. See ticket #23849.
    • type (string) - カスタムフィールドのタイプ。 使用できる値は 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'。 デフォルト値は 'CHAR'。

イスラエルからのユーザーの表示

$user_query = new WP_User_Query( array( 'meta_key' => 'country', 'meta_value' => 'Israel' ) );

30歳以下のユーザーの表示

$user_query = new WP_User_Query( array( 'meta_key' => 'age', 'meta_value' => '30', 'meta_compare' => '<' ) );

複数取り扱うカスタムユーザーフィールド

$args = array(
	'meta_query' => array(
		'relation' => 'OR',
		array(
			'key'     => 'country',
			'value'   => 'Israel',
			'compare' => '='
		),
		array(
			'key'     => 'age',
			'value'   => array( 20, 30 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN'
		)
	)
 );
$user_query = new WP_User_Query( $args );

Who パラメータ

どのユーザー?

  • who (文字列) - Which users to query. 現在は'authors' のみをサポートする。 デフォルトはすべてのユーザー。

著者のみを表示する

$user_query = new WP_User_Query( array( 'who' => 'authors' ) );

Equals to:

$args = array(
	'meta_key'     => 'user_level',
	'meta_value'   => '0',
	'meta_compare' => '!=',
	'blog_id'      => 0
)
$user_query = new WP_User_Query( $args );

合計数のパラメータ

  • count_total (boolean) - Whether to count the total number of users found. When true (default), the total number of results for the query can be retrieved using the get_total() method. If you don't need the total number of results, set this to false.

フィールドパラメータを返す

戻り値のセット。

  • fields (string|array) - Which fields to return. デフォルトは all.
    • 'ID' - ユーザーIDの配列を返す。
    • 'display_name' - ユーザー表示名の配列を返す。
    • 'login' / 'user_login' - ユーザーログイン名の配列を返す。
    • 'nicename' / 'user_nicename' - ユーザーの nicename の配列を返す(ニックネームではありません)。
    • 'email' / 'user_email' - ユーザーのメールアドレスの配列を返す。
    • 'url' / 'user_url' - ユーザーURLの配列を返す。
    • 'registered' / 'user_registered' - ユーザー登録日時の配列を返す。
    • 'all (default) or all_with_meta' - WP_User オブジェクトの配列を返す。フィールドが返されたサブセットに配列を渡す必要があります。

WP_User オブジェクトの配列を返す

$user_query = new WP_User_Query( array( 'role' => 'editor', 'fields' => 'all_with_meta' ) );

Return List all blog editors, return limited fields in resulting row objects:

$user_fields = array( 'user_login', 'user_nicename', 'user_email', 'user_url' );
$user_query = new WP_User_Query( array( 'role' => 'editor', 'fields' => $user_fields ) );

戻り値

(Array) 
An array of IDs, stdClass objects, or WP_User objects, depending on the value of the 'fields' parameter.
  • If 'fields' is set to 'all' (default), or 'all_with_meta', it will return an array of WP_User objects.
  • If 'fields' is set to an array of wp_users table fields, it will return an array of stdClass objects with only those fields.
  • If 'fields' is set to any individual wp_users table field, an array of IDs will be returned.

フィルター

  • found_users_query - Alters SQL 'SELECT FOUND_ROWS()' clause to the query that returns the count total.

用例

以下は first_name / last_name / description や デフォルトの search_columns でユーザーを検索する場合の例です。

// The search term
$search_term = 'Ross';

// WP_User_Query arguments
$args = array (
    'role' => 'reporter',
    'order' => 'ASC',
    'orderby' => 'display_name',
    'search' => '*'.esc_attr( $search_term ).'*',
    'meta_query' => array(
        'relation' => 'OR',
        array(
            'key'     => 'first_name',
            'value'   => $search_term,
            'compare' => 'LIKE'
        ),
        array(
            'key'     => 'last_name',
            'value'   => $search_term,
            'compare' => 'LIKE'
        ),
        array(
            'key' => 'description',
            'value' => $search_term ,
            'compare' => 'LIKE'
        )
    )
);

// Create the WP_User_Query object
$wp_user_query = new WP_User_Query($args);

// Get the results
$authors = $wp_user_query->get_results();

// Check for results
if (!empty($authors)) {
    echo '<ul>';
    // loop trough each author
    foreach ($authors as $author)
    {
        // get all the user's data
        $author_info = get_userdata($author->ID);
        echo '<li>'.$author_info->first_name.' '.$author_info->last_name.'</li>';
    }
    echo '</ul>';
} else {
    echo 'No authors found';
}

更新履歴

  • 3.5.0:
    • 追加 $query_vars プロパティ
    • 追加 get() メソッド
    • 追加 set() メソッド
    • 追加 meta_query パラメータ

ソースファイル

WP_User_Querywp-includes/user.phpにあります。

リソース

関連情報

クラスリファレンス関数リファレンスの各インデックスも参照してください。

最新英語版: WordPress Codex » Class_Reference/WP_User_Query最新版との差分