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

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

提供: WordPress Codex 日本語版
< クラスリファレンス
2015年8月2日 (日) 14:28時点におけるMiccweb (トーク | 投稿記録)による版 (関連情報)

移動先: 案内検索

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

説明

WP_User_Query is a class, defined in wp-includes/user.php, that allows querying WordPress database tables 'wp_users' and 'wp_usermeta'. This class was introduced in Version 3.1 and as a result, the WP_User_Search class got deprecated.

使い方

<?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()
Retrieve query variable.
set()
Set query variable.
get_results()
Return the list of users.
get_total()
Return the total number of users for the current query.

パラメータ

ユーザー権限パラメータ

Show users associated with certain role.

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

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

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

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

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

Show specific users.

  • include (array) - List of users to be included.
  • exclude (array) - List of users to be excluded.

Display specific users list

$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 ) ) );

ブログパラメータ

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' - ユーザーニックネームで検索
    • '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 パラメータ

Sort retrieved Users.

  • orderby (string) - Sort retrieved users by parameter. Defaults to 'login'.
    • 'ID' - Order by user id.
    • 'display_name' - Order by user display name.
    • 'name' / 'user_name' - Order by user name.
    • 'login' / 'user_login' - Order by user login.
    • 'nicename' / 'user_nicename' - Order by user nicename.
    • 'email' / 'user_email' - Order by user email.
    • 'url' / 'user_url' - Order by user url.
    • 'registered' / 'user_registered' - Order by user registered date.
    • 'post_count' - Order by user post count.
    • 'meta_value' - Note that a 'meta_key=keyname' must also be present in the query (available with Version 3.7).
  • order (string) - Designates the ascending or descending order of the 'orderby' parameter. Defaults to 'ASC'.
    • 'ASC' - ascending order from lowest to highest values (1, 2, 3; a, b, c).
    • 'DESC' - descending order from highest to lowest values (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' ) );

Display users sorted by registered, Ascending order

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

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

Show users associated with a certain custom field.

The WP_Meta_Query class is used to parse this part of the query since 3.2.0, so check the docs for that class for the full, up to date list of arguments.

  • meta_key (string) - カスタムフィールドのキー。
  • meta_value (string) - カスタムフィールドの値。
  • meta_compare (string) - Operator to test the 'meta_value'. See 'compare' below.
  • meta_query (array) - カスタムフィールドのパラメータ。 (available with Version 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' => '<' ) );

Multiple custom user fields handling

$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' - ユーザーニックネームの配列を返す。
    • '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最新版との差分