ユーザークエリ

ユーザークエリを使用して、テンプレートや PHP コード内でユーザーを取得できます。

{# Create a new user query #}
{% set myUserQuery = craft.users() %}

ユーザークエリを作成すると、結果を絞り込むためのパラメータをセットできます。さらに、.all() を呼び出して実行できます。User オブジェクトの配列が返されます。

TIP

エレメントクエリがどのように機能するかについては、エレメントクエリについてを参照してください。

実例

次の操作を行うことで、「Authors」ユーザーグループに含まれるユーザーのリストを表示できます。

  1. craft.users() でユーザークエリを作成します。
  2. group パラメータをセットします。
  3. .all() でユーザーを取得します。
  4. for タグを使用してユーザーをループ処理し、リストの HTML を作成します。
{# Create a user query with the 'group' parameter #}
{% set myUserQuery = craft.users()
    .group('authors') %}

{# Fetch the users #}
{% set users = myUserQuery.all() %}

{# Display the list #}
<ul>
    {% for user in users %}
        <li><a href="{{ url('authors/'~user.username) }}">{{ user.name }}</a></li>
    {% endfor %}
</ul>

パラメータ

ユーザークエリは、次のパラメータをサポートしています。

admin

「管理」権限を持つユーザーだけに、クエリの結果を絞り込みます。

{# Fetch admins #}
{% set elements = {twig-function}
    .admin()
    .all() %}

anyStatus

status および enabledForSite() パラメータをクリアします。

{# Fetch all elements, regardless of status #}
{% set elements = craft.queryFunction()
    .anyStatus()
    .all() %}

asArray

ElementClass オブジェクトではなく、データの配列として、マッチしたエレメントをクエリが返します。

{# Fetch elements as arrays #}
{% set elements = craft.queryFunction()
    .asArray()
    .all() %}

can

直接ユーザーアカウントにセットされているかユーザーグループの1つを通してセットされている、特定のユーザー権限を持つユーザーだけに、クエリの結果を絞り込みます。

Craft によって定義された利用可能なユーザー権限のリストは、ユーザーを参照してください。

{# Fetch users that can access the Control Panel #}
{% set elements = {twig-function}
    .can('accessCp')
    .all() %}

dateCreated

エレメントの作成日に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'>= 2018-04-01'2018-04-01 以降に作成されたもの。
'< 2018-05-01'2018-05-01 より前に作成されたもの。
['and', '>= 2018-04-04', '< 2018-05-01']2018-04-01 から 2018-05-01 の間に作成されたもの。
{# Fetch elements created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set elements = craft.queryFunction()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

dateUpdated

エレメントの最終アップデート日に基づいて、クエリの結果が絞り込まれます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'>= 2018-04-01'2018-04-01 以降にアップデートされたもの。
'< 2018-05-01'2018-05-01 より前にアップデートされたもの。
['and', '>= 2018-04-04', '< 2018-05-01']2018-04-01 から 2018-05-01 の間にアップデートされたもの。
{# Fetch elements updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set elements = craft.queryFunction()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

email

ユーザーのメールアドレスに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'foo@bar.baz'メールアドレスが foo@bar.baz
'not foo@bar.baz'メールアドレスが foo@bar.baz ではない。
'*@bar.baz'メールアドレスが @bar.baz で終わる。
{# Fetch users with a .co.uk domain on their email address #}
{% set elements = craft.queryFunction()
    .email('*.co.uk')
    .all() %}

firstName

ユーザーのファーストネーム(名)に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'Jane'ファーストネームが Jane
'not Jane'ファーストネームが Jane ではない。
{# Fetch all the Jane's #}
{% set elements = craft.queryFunction()
    .firstName('Jane')
    .all() %}

fixedOrder

クエリの結果を id で指定された順序で返します。

{# Fetch elements in a specific order #}
{% set elements = craft.queryFunction()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

group

ユーザーが属するユーザーグループに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'foo'ハンドルが foo のグループ内。
'not foo'ハンドルが foo のグループ内ではない。
['foo', 'bar']ハンドルが foo または bar のグループ内。
['not', 'foo', 'bar']ハンドルが foo または bar のグループ内ではない。
UserGroup オブジェクトオブジェクトで表されるグループ内。
{# Fetch elements in the Foo user group #}
{% set elements = craft.queryFunction()
    .group('foo')
    .all() %}

groupId

グループ ID ごとに、ユーザーが属するユーザーグループに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
1ID が 1 のグループ内。
'not 1'ID が 1 のグループ内ではない。
[1, 2]ID が 1 または 2 のグループ内。
['not', 1, 2]ID が 1 または 2 のグループ内ではない。
{# Fetch elements in a group with an ID of 1 #}
{% set elements = craft.queryFunction()
    .groupId(1)
    .all() %}

id

エレメントの ID に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
1ID が 1。
'not 1'ID が 1ではない。
[1, 2]ID が 1 または 2。
['not', 1, 2]ID が 1 または 2 ではない。
{# Fetch the element by its ID #}
{% set element = craft.queryFunction()
    .id(1)
    .one() %}

TIP

特定の順序で結果を返したい場合、fixedOrder と組み合わせることができます。

inReverse

クエリの結果を逆順で返します。

{# Fetch elements in reverse #}
{% set elements = craft.queryFunction()
    .inReverse()
    .all() %}

lastLoginDate

ユーサーの最終ログイン日に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'>= 2018-04-01'2018-04-01 以降に最終ログインされたもの。
'< 2018-05-01'2018-05-01 より前に最終ログインされたもの。
['and', '>= 2018-04-04', '< 2018-05-01']2018-04-01 から 2018-05-01 の間に最終ログインされたもの。
{# Fetch elements that logged in recently #}
{% set aWeekAgo = date('7 days ago')|atom %}

{% set elements = craft.queryFunction()
    .lastLoginDate(">= #{aWeekAgo}")
    .all() %}

lastName

ユーザーのラストネーム(姓)に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'Doe'ラストネームが Doe
'not Doe'ラストネームが Doe ではない。
{# Fetch all the Doe's #}
{% set elements = craft.queryFunction()
    .lastName('Doe')
    .all() %}

limit

返されるエレメントの数を決定します。

{# Fetch up to 10 elements  #}
{% set elements = craft.queryFunction()
    .limit(10)
    .all() %}

offset

結果からスキップされるエレメントの数を決定します。

{# Fetch all elements except for the first 3 #}
{% set elements = craft.queryFunction()
    .offset(3)
    .all() %}

orderBy

返されるエレメントの順序を決定します。

{# Fetch all elements in order of date created #}
{% set elements = craft.queryFunction()
    .orderBy('dateCreated asc')
    .all() %}

relatedTo

特定の他のエレメントと関連付けられたエレメントだけに、クエリの結果を絞り込みます。

このパラメーターがどのように機能するかの詳細については、リレーションを参照してください。

{# Fetch all elements that are related to myCategory #}
{% set elements = craft.queryFunction()
    .relatedTo(myCategory)
    .all() %}

検索結果にマッチするエレメントだけに、クエリの結果を絞り込みます。

このパラメーターがどのように機能するかの詳細については、検索を参照してください。

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all elements that match the search query #}
{% set elements = craft.queryFunction()
    .search(searchQuery)
    .all() %}

status

エレメントのステータスに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'active'(デフォルト)有効なアカウント。
'suspended'停止されているアカウント。
'pending'アクティベーションが保留されているアカウント。
'locked'(それが有効か停止されているかに関わらず)ロックされているアカウント。
['active', 'suspended']有効、または、停止されているアカウント。
{# Fetch active and locked elements #}
{% set elements = {twig-function}
    .status(['active', 'locked'])
    .all() %}

trashed

ソフトデリートされたエレメントだけに、クエリの結果を絞り込みます。

{# Fetch trashed elements #}
{% set elements = {twig-function}
    .trashed()
    .all() %}

uid

エレメントの UID に基づいて、クエリの結果を絞り込みます。

{# Fetch the element by its UID #}
{% set element = craft.queryFunction()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

username

ユーザーのユーザー名に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するエレメント
'foo'ユーザー名が foo
'not foo'ユーザー名が foo ではない。
{# Get the requested username #}
{% set requestedUsername = craft.app.request.getSegment(2) %}

{# Fetch that user #}
{% set element = craft.queryFunction()
    .username(requestedUsername|literal)
    .one() %}

with

関連付けられたエレメントを eager-loaded した状態で、マッチしたエレメントをクエリが返します。

このパラメーターがどのように機能するかの詳細については、エレメントのEager-Loadingを参照してください。

{# Fetch elements eager-loaded with the "Related" field’s relations #}
{% set elements = craft.queryFunction()
    .with(['related'])
    .all() %}