タグクエリ

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

{# Create a new tag query #}
{% set myTagQuery = craft.tags() %}

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

TIP

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

実例

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

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

{# Fetch the tags #}
{% set tags = myTagQuery.all() %}

{# Display the tag list #}
<ul>
    {% for tag in tags %}
        <li><a href="{{ url('blog/tags/'~tag.id) }}">{{ tag.title }}</a></li>
    {% endfor %}
</ul>

パラメータ

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

anyStatus

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

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

asArray

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

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

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

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

fixedOrder

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

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

    :::

    group

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

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

      :::

      groupId

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

        {# Fetch tags in the group with an ID of 1 #}
        {% set tags = craft.tags()
            .groupId(1)
            .all() %}
        
        // Fetch tags in the group with an ID of 1
        $tags = \craft\elements\Tag::find()
            ->groupId(1)
            ->all();
        

        :::

        id

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

        {# Fetch the tag by its ID #}
        {% set tag = craft.tags()
            .id(1)
            .one() %}
        

        inReverse

        TIP

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

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

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

        :::

        limit

        :::

        返されるタグの数を決定します。

        取得するタグ
        'foo'ハンドルが foo のサイトから。
        'not foo'オブジェクトで表されるサイトから。
        ['foo', 'bar']in a group with a handle of foo or bar.
        ['not', 'foo', 'bar']not in a group with a handle of foo or bar.
        a TagGroup objectin a group represented by the object.
        {# Fetch up to 10 tags  #}
        {% set tags = craft.tags()
            .limit(10)
            .all() %}
        

        offset

        結果からスキップされるタグの数を決定します。

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

          :::

          orderBy

            取得するタグ
            748040'foo'9'foo'URI が foo
            'foo*'URI が foo ではじまる。
            '*foo'URI が foo で終わる。
            '*foo*'URI が foo を含む。

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

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

            :::

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

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

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

              :::

              site

              :::

              タグを照会するサイトを決定します。

              {# Get the search query from the 'q' query string param #}
              {% set searchQuery = craft.app.request.getQueryParam('q') %}
              
              {# Fetch all tags that match the search query #}
              {% set tags = craft.tags()
                  .search(searchQuery)
                  .all() %}
              
              // Get the search query from the 'q' query string param
              $searchQuery = \Craft::$app->request->getQueryParam('q');
              
              // Fetch all tags that match the search query
              $tags = \craft\elements\Tag::find()
                  ->search($searchQuery)
                  ->all();
              

              :::

              siteId

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

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

              title

              サイトの ID ごとに、タグを照会するサイトを決定します。

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

              {# Fetch tags from the site with an ID of 1 #}
              {% set tags = craft.tags()
                  .siteId(1)
                  .all() %}
              
              // Fetch tags from the site with an ID of 1
              $tags = \craft\elements\Tag::find()
                  ->siteId(1)
                  ->all();
              

              :::

              trashed

              :::

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

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

              {# Fetch tags with a title that contains "Foo" #}
              {% set tags = craft.tags()
                  .title('*Foo*')
                  .all() %}
              

              uid

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

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

                :::

                uri

                  ValueFetches revisions…
                  1created by the user with an ID of 1.
                  a \craft\elements\db\User objectby the user represented by the object.

                  タグの URI に基づいて、クエリの結果を絞り込みます。

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

                  :::

                  with

                    ValueFetches revisions…
                    1for the revision with an ID of 1.

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

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

                    :::

                    revisionOf

                      ValueFetches revisions…
                      1for the tag with an ID of 1.
                      a Tag objectfor the tag represented by the object.
                      {# Fetch tags eager-loaded with the "Related" field’s relations #}
                      {% set tags = craft.tags()
                          .with(['related'])
                          .all() %}
                      

                      revisions

                      Narrows the query results to only revision tags.

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

                      search

                      Narrows the query results to only tags 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 tags that match the search query #}
                      {% set tags = craft.tags()
                          .search(searchQuery)
                          .all() %}
                      

                      site

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

                      The current site will be used by default.

                      Possible values include:

                      ValueFetches tags…
                      '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 tags from the Foo site #}
                      {% set tags = craft.tags()
                          .site('foo')
                          .all() %}
                      

                      siteId

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

                      The current site will be used by default.

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

                      title

                      Narrows the query results based on the tags’ titles.

                      Possible values include:

                      ValueFetches tags…
                      '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 tags with a title that contains "Foo" #}
                      {% set tags = craft.tags()
                          .title('*Foo*')
                          .all() %}
                      

                      trashed

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

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

                      uid

                      Narrows the query results based on the tags’ UIDs.

                      {# Fetch the tag by its UID #}
                      {% set tag = craft.tags()
                          .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 tags across all sites #}
                      {% set tags = craft.tags()
                          .site('*')
                          .unique()
                          .all() %}
                      

                      uri

                      Narrows the query results based on the tags’ URIs.

                      Possible values include:

                      ValueFetches tags…
                      '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 tag with that URI #}
                      {% set tag = craft.tags()
                          .uri(requestedUri|literal)
                          .one() %}
                      

                      with

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

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

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