• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

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

提供: WordPress Codex 日本語版
移動先: 案内検索

このページ「クラスリファレンス/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()
現在のクエリでのユーザーの合計数を返す。

パラメータ

ユーザー権限パラメータ

Show users associated with certain role.

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

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

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

$user_query = new WP_User_Query( array( 'role' => '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' - ユーザー名の順。
    • '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最新版との差分