ユーザークエリ

ユーザークエリを使用して、テンプレートや 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

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

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

取得するエレメント
r.baz'3d'foo@bar.baz'6c'foo@bar.baz'2f3.95654'foo@bar.baz'64'foo@bar.baz' メールアドレスが foo@bar.baz
a craft\elements\User object メールアドレスが foo@bar.baz ではない。
{# Fetch users with a .co.uk domain on their email address #}
{% set elements = craft.queryFunction()
    .email('*.co.uk')
    .all() %}

# firstName

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

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

取得するエレメント
6fc090.362772'Jane'4'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() %}
    
    // Fetch elements in a specific order
    $elements = ElementClass::find()
        ->id([1, 2, 3, 4, 5])
        ->fixedOrder()
        ->all();
    

    :::

    # group

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

    {# Fetch elements in the Foo user group #}
    {% set elements = craft.queryFunction()
        .group('foo')
        .all() %}
    

    # groupId

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

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

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

    # id

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

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

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

    # inReverse

    TIP

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

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

    {# Fetch elements in reverse #}
    {% set elements = craft.queryFunction()
        .inReverse()
        .all() %}
    
    // Fetch elements in reverse
    $elements = ElementClass::find()
        ->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 の間に最終ログインされたもの。
    ['not', 'foo', 'bar'] not in a group with a handle of foo or bar.
    a UserGroup object in a group represented by the object.

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

    {# Fetch elements that logged in recently #}
    {% set aWeekAgo = date('7 days ago')|atom %}
    
    {% set elements = craft.queryFunction()
        .lastLoginDate(">= #{aWeekAgo}")
        .all() %}
    
    // Fetch elements that logged in recently
    $aWeekAgo = (new \DateTime('7 days ago'))->format(\DateTime::ATOM);
    
    $elements = ElementClass::find()
        ->lastLoginDate(">= {$aWeekAgo}")
        ->all();
    

    :::

    # lastName

    :::

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

    取得するエレメント
    Doe'b44.50395768'Doe' ラストネームが Doe
    'not Doe' ラストネームが Doe ではない。
    [1, 2] in a group with an ID of 1 or 2.
    ['not', 1, 2] not in a group with an ID of 1 or 2.

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

    {# Fetch all the Doe's #}
    {% set elements = craft.queryFunction()
        .lastName('Doe')
        .all() %}
    
    // Fetch all the Doe's
    $elements = ElementClass::find()
        ->lastName('Doe')
        ->one();
    

    :::

    # limit

    :::

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

    取得するエレメント
    1 有効なアカウント。
    'suspended' 停止されているアカウント。
    'pending' アクティベーションが保留されているアカウント。
    'locked' (それが有効か停止されているかに関わらず)ロックされているアカウント。
    {# 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() %}
      
      // Fetch all elements except for the first 3
      $elements = ElementClass::find()
          ->offset(3)
          ->all();
      

      :::

      # relatedTo

      :::

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

      取得するエレメント
      'foo' ユーザー名が foo
      'not foo' ユーザー名が foo ではない。
      ['and', '>= 2018-04-04', '< 2018-05-01'] that last logged-in between 2018-04-01 and 2018-05-01.

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

      {# Fetch all elements in order of date created #}
      {% set elements = craft.queryFunction()
          .orderBy('dateCreated asc')
          .all() %}
      
      // Fetch all elements in order of date created
      $elements = ElementClass::find()
          ->orderBy('dateCreated asc')
          ->all();
      

      :::

      :::

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

      Value Fetches elements…
      'Doe' with a last name of Doe.
      'not Doe' not with a last name of Doe.

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

      {# Fetch all elements that are related to myCategory #}
      {% set elements = craft.queryFunction()
          .relatedTo(myCategory)
          .all() %}
      
      // Fetch all elements that are related to $myCategory
      $elements = ElementClass::find()
          ->relatedTo($myCategory)
          ->all();
      

      :::

      # status

      :::

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

      {# 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() %}
      
      // Get the search query from the 'q' query string param
      $searchQuery = \Craft::$app->request->getQueryParam('q');
      
      // Fetch all elements that match the search query
      $elements = ElementClass::find()
          ->search($searchQuery)
          ->all();
      

      :::

      # trashed

        {# Fetch active and locked elements #}
        {% set elements = {twig-function}
            .status(['active', 'locked'])
            .all() %}
        
        // Fetch active and locked elements
        $elements = ElementClass::find()
            ->status(['active', 'locked'])
            ->all();
        

        :::

        # uid

          {# Fetch trashed elements #}
          {% set elements = {twig-function}
              .trashed()
              .all() %}
          
          // Fetch trashed elements
          $elements = ElementClass::find()
              ->trashed()
              ->all();
          

          :::

          # username

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

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

            {# Fetch the element by its UID #}
            {% set element = craft.queryFunction()
                .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
                .one() %}
            
            // Fetch the element by its UID
            $element = ElementClass::find()
                ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
                ->one();
            

            :::

            # with

            :::

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

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

            {# Get the requested username #}
            {% set requestedUsername = craft.app.request.getSegment(2) %}
            
            {# Fetch that user #}
            {% set element = craft.queryFunction()
                .username(requestedUsername|literal)
                .one() %}
            
            // Get the requested username
            $requestedUsername = \Craft::$app->request->getSegment(2);
            
            // Fetch that user
            $element = ElementClass::find()
                ->username(\craft\helpers\Db::escapeParam($requestedUsername))
                ->one();
            

            :::

            # revisionCreator

            :::

            Possible values include:

            Value Fetches revisions…
            1 created by the user with an ID of 1.
            a craft\elements\User object by the user represented by the object.
            {# Fetch elements eager-loaded with the "Related" field’s relations #}
            {% set elements = craft.queryFunction()
                .with(['related'])
                .all() %}
            

            # revisionId

            Narrows the query results based on the elements’ revision’s ID (from the revisions table).

            Possible values include:

            Value Fetches revisions…
            1 for the revision with an ID of 1.
            {# Fetch a revision #}
            {% set elements = craft.queryFunction()
                .revisionId(10)
                .all() %}
            

            # revisionOf

            Narrows the query results to only revisions of a given element.

            Possible values include:

            Value Fetches revisions…
            1 for the element with an ID of 1.
            a ElementClass object for the element represented by the object.
            {# Fetch revisions of the element #}
            {% set elements = craft.queryFunction()
                .revisionOf(myElement)
                .all() %}
            

            # revisions

            Narrows the query results to only revision elements.

            {# Fetch a revision element #}
            {% set elements = {twig-function}
                .revisions()
                .id(123)
                .one() %}
            

            # search

            Narrows the query results to only elements that match a search query.

            See Searching for a full explanation of how to work with this parameter.

            {# 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

            Narrows the query results based on the elements’ statuses.

            Possible values include:

            Value Fetches elements…
            'active' (default) with active accounts.
            'suspended' with suspended accounts.
            'pending' with accounts that are still pending activation.
            'locked' with locked accounts (regardless of whether they’re active or suspended).
            ['active', 'suspended'] with active or suspended accounts.
            {# Fetch active and locked elements #}
            {% set elements = craft.queryFunction()
                .status(['active', 'locked'])
                .all() %}
            

            # trashed

            Narrows the query results to only elements that have been soft-deleted.

            {# Fetch trashed elements #}
            {% set elements = craft.queryFunction()
                .trashed()
                .all() %}
            

            # uid

            Narrows the query results based on the elements’ UIDs.

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

            # username

            Narrows the query results based on the users’ usernames.

            Possible values include:

            Value Fetches elements…
            'foo' with a username of foo.
            'not foo' not with a username of foo.
            {# Get the requested username #}
            {% set requestedUsername = craft.app.request.getSegment(2) %}
            
            {# Fetch that user #}
            {% set element = craft.queryFunction()
                .username(requestedUsername|literal)
                .one() %}
            

            # with

            Causes the query to return matching elements eager-loaded with related elements.

            See Eager-Loading Elements for a full explanation of how to work with this parameter.

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