カテゴリクエリ

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

{# Create a new category query #}
{% set myCategoryQuery = craft.categories() %}

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

TIP

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

実例

次の操作を行うことで、「Topics」カテゴリグループに含まれるすべてのカテゴリのナビゲーションを表示できます。

  1. craft.categories() でカテゴリクエリを作成します。
  2. group パラメータをセットします。
  3. .all() でカテゴリを取得します。
  4. nav タグを使用してカテゴリをループ処理し、ナビゲーションの HTML を作成します。
{# Create a category query with the 'group' parameter #}
{% set myCategoryQuery = craft.categories()
    .group('topics') %}

{# Fetch the categories #}
{% set categories = myCategoryQuery.all() %}

{# Display the navigation #}
<ul>
    {% nav category in categories %}
        <li>
            <a href="{{ category.url }}">{{ category.title }}</a>
            {% ifchildren %}
                <ul>
                    {% children %}
                </ul>
            {% endifchildren %}
        </li>
    {% endnav %}
</ul>

パラメータ

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

ancestorDist

ancestorOf で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。

{# Fetch categories above this one #}
{% set categories = craft.categories()
    .ancestorOf(myCategory)
    .ancestorDist(3)
    .all() %}

ancestorOf

指定したカテゴリの先祖であるカテゴリだけに、クエリの結果を絞り込みます。

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

取得するカテゴリ
1ID が 1 のカテゴリの上層。
Category オブジェクトオブジェクトで表されるカテゴリの上層。
{# Fetch categories above this one #}
{% set categories = craft.categories()
    .ancestorOf(myCategory)
    .all() %}

TIP

どれだけ離れた先祖カテゴリを対象にするか制限したい場合、ancestorDist と組み合わせることができます。

anyStatus

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

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

asArray

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

{# Fetch categories as arrays #}
{% set categories = craft.categories()
    .asArray()
    .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 categories created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set categories = craft.categories()
    .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 categories updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

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

descendantDist

descendantOf で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。

{# Fetch categories below this one #}
{% set categories = craft.categories()
    .descendantOf(myCategory)
    .descendantDist(3)
    .all() %}

descendantOf

指定したカテゴリの子孫であるカテゴリだけに、クエリの結果を絞り込みます。

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

取得するカテゴリ
1ID が 1 のカテゴリの下層。
Category オブジェクトオブジェクトで表されるカテゴリの下層。
{# Fetch categories below this one #}
{% set categories = craft.categories()
    .descendantOf(myCategory)
    .all() %}

TIP

どれだけ離れた子孫カテゴリを対象にするか制限したい場合、descendantDist と組み合わせることができます。

enabledForSite

site パラメータごとに、照会されているサイトでカテゴリが有効になっているかどうかに基づいて、クエリの結果を絞り込みます。

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

取得するカテゴリ
1サイト内で有効になっているもの。
a \craft\elements\db\User objectサイト内で有効かどうかに関係なく。
{# Fetch all categories, including ones disabled for this site #}
{% set categories = craft.categories()
    .enabledForSite(false)
    .all() %}

fixedOrder

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

    {# Fetch categories in a specific order #}
    {% set categories = craft.categories()
        .id([1, 2, 3, 4, 5])
        .fixedOrder()
        .all() %}
    
    // Fetch categories in a specific order
    $categories = \craft\elements\Category::find()
        ->id([1, 2, 3, 4, 5])
        ->fixedOrder()
        ->all();
    

    :::

    group

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

      {# Fetch categories in the Foo group #}
      {% set categories = craft.categories()
          .group('foo')
          .all() %}
      
      // Fetch categories in the Foo group
      $categories = \craft\elements\Category::find()
          ->group('foo')
          ->all();
      

      :::

      groupId

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

      {# Fetch categories in the group with an ID of 1 #}
      {% set categories = craft.categories()
          .groupId(1)
          .all() %}
      

      hasDescendants

      カテゴリが子孫を持つかどうかに基づいて、クエリの結果を絞り込みます。

      (これは leaves の呼び出しと反対の効果を持っています。)

      取得するカテゴリ
      true(default)ID が 1。
      'not 1'ID が 1ではない。
      {# Fetch categories that have descendants #}
      {% set categories = craft.categories()
          .hasDescendants()
          .all() %}
      

      id

      カテゴリの ID に基づいて、クエリの結果を絞り込みます。

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

      {# Fetch the category by its ID #}
      {% set category = craft.categories()
          .id(1)
          .one() %}
      
      // Fetch the category by its ID
      $category = \craft\elements\Category::find()
          ->id(1)
          ->one();
      

      :::

      inReverse

      :::

      TIP

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

      取得するカテゴリ
      1レベルが 1。
      'not 1'レベルが 1 ではない。
      '>= 3'レベルが 3 以上。
      [1, 2]レベルが 1 または 2。
      a CategoryGroup objectレベルが 1 または 2 ではない。

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

      {# Fetch categories in reverse #}
      {% set categories = craft.categories()
          .inReverse()
          .all() %}
      
      // Fetch categories in reverse
      $categories = \craft\elements\Category::find()
          ->inReverse()
          ->all();
      

      :::

      leaves

      :::

      カテゴリが「leaves」(子孫のないカテゴリ)であるかどうかに基づいて、クエリの結果を絞り込みます。

      取得するカテゴリ
      1ID が 1 のカテゴリの後。
      'not 1'オブジェクトで表されるカテゴリの後。
      [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.

      (これは hasDescendants の呼び出しと反対の効果を持っています。)

      {# Fetch categories that have no descendants #}
      {% set categories = craft.categories()
          .leaves()
          .all() %}
      
      // Fetch categories that have no descendants
      $categories = \craft\elements\Category::find()
          ->leaves()
          ->all();
      

      :::

      level

      :::

      構造内のカテゴリのレベルに基づいて、クエリの結果を絞り込みます。

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

      {# Fetch categories positioned at level 3 or above #}
      {% set categories = craft.categories()
          .level('>= 3')
          .all() %}
      
      // Fetch categories positioned at level 3 or above
      $categories = \craft\elements\Category::find()
          ->level('>= 3')
          ->all();
      

      :::

      limit

      :::

      返されるカテゴリの数を決定します。

      取得するカテゴリ
      1ID が 1 のカテゴリの後。
      'not 1'オブジェクトで表されるカテゴリの後。
      [1, 2]with an ID of 1 or 2.
      ['not', 1, 2]not with an ID of 1 or 2.
      {# Fetch up to 10 categories  #}
      {% set categories = craft.categories()
          .limit(10)
          .all() %}
      

      指定したカテゴリの直後にあるカテゴリだけに、クエリの結果を絞り込みます。

      nextSiblingOf

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

      offset

        {# Fetch the next category #}
        {% set category = craft.categories()
            .nextSiblingOf(myCategory)
            .one() %}
        
        // Fetch the next category
        $category = \craft\elements\Category::find()
            ->nextSiblingOf($myCategory)
            ->one();
        

        :::

        orderBy

          返されるカテゴリの順序を決定します。

          {# Fetch all categories except for the first 3 #}
          {% set categories = craft.categories()
              .offset(3)
              .all() %}
          
          // Fetch all categories except for the first 3
          $categories = \craft\elements\Category::find()
              ->offset(3)
              ->all();
          

          :::

          positionedAfter

          :::

          指定したカテゴリの後に位置するカテゴリだけに、クエリの結果を絞り込みます。

          ValueFetches categories…
          1before the category with an ID of 1.
          'not 1'オブジェクトで表されるカテゴリの前。
          '>= 3'with a level greater than or equal to 3.
          [1, 2]with a level of 1 or 2
          ['not', 1, 2]not with level of 1 or 2.

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

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

          :::

          positionedBefore

          :::

          指定したカテゴリの前に位置するカテゴリだけに、クエリの結果を絞り込みます。

          {# Fetch categories after this one #}
          {% set categories = craft.categories()
              .positionedAfter(myCategory)
              .all() %}
          
          // Fetch categories after this one
          $categories = \craft\elements\Category::find()
              ->positionedAfter($myCategory)
              ->all();
          

          :::

          prevSiblingOf

            取得するカテゴリ
            1ID が 1 のカテゴリの前。
            Category オブジェクトオブジェクトで表されるカテゴリの前。

            指定したカテゴリの直前にあるカテゴリだけに、クエリの結果を絞り込みます。

            {# Fetch categories before this one #}
            {% set categories = craft.categories()
                .positionedBefore(myCategory)
                .all() %}
            
            // Fetch categories before this one
            $categories = \craft\elements\Category::find()
                ->positionedBefore($myCategory)
                ->all();
            

            :::

            relatedTo

              {# Fetch the previous category #}
              {% set category = craft.categories()
                  .prevSiblingOf(myCategory)
                  .one() %}
              
              // Fetch the previous category
              $category = \craft\elements\Category::find()
                  ->prevSiblingOf($myCategory)
                  ->one();
              

              :::

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

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

              siblingOf

              検索クエリにマッチするカテゴリだけに、クエリの結果を絞り込みます。

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

              取得するカテゴリ
              1ID が 1 のカテゴリの横。
              Category オブジェクトオブジェクトで表されるカテゴリの横。
              {# Get the search query from the 'q' query string param #}
              {% set searchQuery = craft.app.request.getQueryParam('q') %}
              
              {# Fetch all categories that match the search query #}
              {% set categories = craft.categories()
                  .search(searchQuery)
                  .all() %}
              

              site

              指定したカテゴリの兄弟であるカテゴリだけに、クエリの結果を絞り込みます。

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

              取得するカテゴリ
              foo'852.'foo'2303752'foo'ハンドルが foo のサイトから。
              \craft\elements\db\Site オブジェクトオブジェクトで表されるサイトから。
              {# Fetch categories beside this one #}
              {% set categories = craft.categories()
                  .siblingOf(myCategory)
                  .all() %}
              

              siteId

              カテゴリを照会するサイトを決定します。

              デフォルトでは、現在のサイトが使用されます。

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

              {# Fetch categories from the Foo site #}
              {% set categories = craft.categories()
                  .site('foo')
                  .all() %}
              

              slug

              サイトの ID ごとに、カテゴリを照会するサイトを決定します。

              デフォルトでは、現在のサイトが使用されます。

              取得するカテゴリ
              oo'e7c'foo'.277707'foo'7'foo'スラグが foo
              a Category objectスラグが foo ではじまる。
              {# Fetch categories from the site with an ID of 1 #}
              {% set categories = craft.categories()
                  .siteId(1)
                  .all() %}
              

              status

              カテゴリのスラグに基づいて、クエリの結果を絞り込みます。

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

              {# Get the requested category slug from the URL #}
              {% set requestedSlug = craft.app.request.getSegment(3) %}
              
              {# Fetch the category with that slug #}
              {% set category = craft.categories()
                  .slug(requestedSlug|literal)
                  .one() %}
              

              title

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

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

              取得するカテゴリ
              1有効になっているもの。
              a \craft\elements\db\User object無効になっているもの。
              {# Fetch disabled categories #}
              {% set categories = craft.categories()
                  .status('disabled')
                  .all() %}
              

              trashed

              カテゴリのタイトルに基づいて、クエリの結果を絞り込みます。

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

              取得するカテゴリ
              o'f7bd4.72649324'Foo'タイトルが Foo
              {# Fetch categories with a title that contains "Foo" #}
              {% set categories = craft.categories()
                  .title('*Foo*')
                  .all() %}
              

              uid

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

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

                :::

                uri

                  {# Fetch the category by its UID #}
                  {% set category = craft.categories()
                      .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
                      .one() %}
                  
                  // Fetch the category by its UID
                  $category = \craft\elements\Category::find()
                      ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
                      ->one();
                  

                  :::

                  with

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

                    {# Get the requested URI #}
                    {% set requestedUri = craft.app.request.getPathInfo() %}
                    
                    {# Fetch the category with that URI #}
                    {% set category = craft.categories()
                        .uri(requestedUri|literal)
                        .one() %}
                    
                    // Get the requested URI
                    $requestedUri = \Craft::$app->request->getPathInfo();
                    
                    // Fetch the category with that URI
                    $category = \craft\elements\Category::find()
                        ->uri(\craft\helpers\Db::escapeParam($requestedUri))
                        ->one();
                    

                    :::

                    siblingOf

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

                      {# Fetch categories eager-loaded with the "Related" field’s relations #}
                      {% set categories = craft.categories()
                          .with(['related'])
                          .all() %}
                      
                      // Fetch categories eager-loaded with the "Related" field’s relations
                      $categories = \craft\elements\Category::find()
                          ->with(['related'])
                          ->all();
                      

                      :::

                      site

                      Determines which site(s) the categories should be queried in.

                      The current site will be used by default.

                      Possible values include:

                      ValueFetches categories…
                      'foo'from the site with a handle of foo.
                      ['foo', 'bar']from a site with a handle of foo or bar.
                      ['not', 'foo', 'bar']not in a site with a handle of foo or bar.
                      a \craft\elements\db\Site objectfrom the site represented by the object.
                      '*'from any site.

                      TIP

                      If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use unique in conjunction with this.

                      {# Fetch categories from the Foo site #}
                      {% set categories = craft.categories()
                          .site('foo')
                          .all() %}
                      

                      siteId

                      Determines which site(s) the categories should be queried in, per the site’s ID.

                      The current site will be used by default.

                      {# Fetch categories from the site with an ID of 1 #}
                      {% set categories = craft.categories()
                          .siteId(1)
                          .all() %}
                      

                      slug

                      Narrows the query results based on the categories’ slugs.

                      Possible values include:

                      ValueFetches categories…
                      'foo'with a slug of foo.
                      'foo*'with a slug that begins with foo.
                      '*foo'with a slug that ends with foo.
                      '*foo*'with a slug that contains foo.
                      'not *foo*'with a slug that doesn’t contain foo.
                      ['*foo*', '*bar*']with a slug that contains foo or bar.
                      ['not', '*foo*', '*bar*']with a slug that doesn’t contain foo or bar.
                      {# Get the requested category slug from the URL #}
                      {% set requestedSlug = craft.app.request.getSegment(3) %}
                      
                      {# Fetch the category with that slug #}
                      {% set category = craft.categories()
                          .slug(requestedSlug|literal)
                          .one() %}
                      

                      status

                      Narrows the query results based on the categories’ statuses.

                      Possible values include:

                      ValueFetches categories…
                      'enabled'(default)that are enabled.
                      'disabled'that are disabled.
                      {# Fetch disabled categories #}
                      {% set categories = craft.categories()
                          .status('disabled')
                          .all() %}
                      

                      title

                      Narrows the query results based on the categories’ titles.

                      Possible values include:

                      ValueFetches categories…
                      'Foo'with a title of Foo.
                      'Foo*'with a title that begins with Foo.
                      '*Foo'with a title that ends with Foo.
                      '*Foo*'with a title that contains Foo.
                      'not *Foo*'with a title that doesn’t contain Foo.
                      ['*Foo*', '*Bar*']with a title that contains Foo or Bar.
                      ['not', '*Foo*', '*Bar*']with a title that doesn’t contain Foo or Bar.
                      {# Fetch categories with a title that contains "Foo" #}
                      {% set categories = craft.categories()
                          .title('*Foo*')
                          .all() %}
                      

                      trashed

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

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

                      uid

                      Narrows the query results based on the categories’ UIDs.

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

                      unique

                      Determines whether only elements with unique IDs should be returned by the query.

                      This should be used when querying elements from multiple sites at the same time, if “duplicate” results is not desired.

                      {# Fetch unique categories across all sites #}
                      {% set categories = craft.categories()
                          .site('*')
                          .unique()
                          .all() %}
                      

                      uri

                      Narrows the query results based on the categories’ URIs.

                      Possible values include:

                      ValueFetches categories…
                      'foo'with a URI of foo.
                      'foo*'with a URI that begins with foo.
                      '*foo'with a URI that ends with foo.
                      '*foo*'with a URI that contains foo.
                      'not *foo*'with a URI that doesn’t contain foo.
                      ['*foo*', '*bar*']with a URI that contains foo or bar.
                      ['not', '*foo*', '*bar*']with a URI that doesn’t contain foo or bar.
                      {# Get the requested URI #}
                      {% set requestedUri = craft.app.request.getPathInfo() %}
                      
                      {# Fetch the category with that URI #}
                      {% set category = craft.categories()
                          .uri(requestedUri|literal)
                          .one() %}
                      

                      with

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

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

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