クラスリファレンス/WP User Query

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

説明

WP_User_Query は wp-includes/user.php に定義されているクラスで、データベースの wp_users と wp_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 パラメータ

導入: 3.1.0

ソースファイル

WP_User_Query は wp-includes/user.phpにあります。

クラスリファレンス/WP User Query

目次

説明

使い方

メソッド・プロパティ

プロパティ

メソッド

パラメータ

ユーザー権限パラメータ

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

ブログパラメータ

検索パラメータ

ページ送りパラメータ

Order & Orderby パラメータ

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

Who パラメータ

合計数のパラメータ

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

戻り値

フィルター

用例

更新履歴

ソースファイル

リソース

関連情報

案内メニュー

個人用ツール

名前空間

変種

表示

その他

検索

このサイトについて

リファレンス

サーバー別情報

ドキュメント整備

協力・貢献

WordPress関連リンク

ツール

クラスリファレンス/WP User Query

目次

説明

使い方

メソッド・プロパティ

プロパティ

メソッド

パラメータ

ユーザー権限パラメータ

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

ブログパラメータ

検索パラメータ

ページ送りパラメータ

Order & Orderby パラメータ

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

Who パラメータ

合計数のパラメータ

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

戻り値

フィルター

用例

更新履歴

ソースファイル

リソース

関連情報

案内メニュー

検索

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