メニュー

WEBMEMOする。とあるクリエイターの個人的な備忘録。

サイドバーやフッターでカテゴリ一覧など表示させたい時に使える、WordPressで登録済みのカテゴリ・タグ・タクソノミーのタームを一覧取得する方法をまとめていこうと思います。

主に以下のような方法があります。

  • get_categories(), get_tags(), get_terms()といったget_関数を使用する
  • wp_list_categories() を使用する(カテゴリのみ)
  • WP_Term_Query を使用する

今回はターム一覧を取得する方法についてメモしていきますが、WordPressでは、カテゴリの取得だけでも状況に合わせて使用する関数が変わります。

その他のパターンについては以下をご覧ください。

投稿に紐付いているカテゴリなどの情報を取得する方法

タームIDを指定することでカテゴリなどの情報を取得する方法

目次

    get_○○s シリーズ

    WordPressには、使用方法も名前もよく似ている以下のような関数があります。

    • get_categories()
    • get_tags()
    • get_terms()

    これら3種の関数は、いずれも取得したいタームに関する条件を配列で指定し、タームオブジェクトを戻り値として得るためのものです。

    それぞれカテゴリ・タグ・タクソノミーに対応しています。

    ・使用方法(取得した情報を変数に代入する)

    $categories = get_categories( $args );
    $tags       = get_tags( $args );
    $terms      = get_terms( $taxonomies, $args );
    

    左辺の変数に、右辺の関数によって取得した情報を代入しています。

    引数 説明
    $args 取得したいタームの条件を指定する配列です。get_○○s系の関数では共通して必要となる引数です。
    $taxonomies タクソノミー名を指定します。(get_terms() のみ、第一引数にこの引数が必要。)
     ‘category’ を指定するとカテゴリー、’post_tag’ を指定するとタグ情報を取得できます。その他のカスタムタクソノミー名を取得したい場合は、そのタクソノミー名のスラッグを指定します。

    $argsで指定できるもの

    3つの関数で引数に渡す$argsの中身について見てみます。

    それぞれのパラメータの初期値と簡単な説明

    $args = array(
      'orderby'            => 'name',  //何でソートするか
      'order'              => 'ASC',   //ソートの昇順or降順
      'hide_empty'         => true,    //投稿のないタームも取得するかどうか
      'exclude'            => array(), //除外するタームの ID の配列または文字列
      'exclude_tree'       => array(), //除外する親タームの ID の配列
      'include'            => array(), //含めるタームの ID の配列
      'number'             => '',      //返すタームの最大個数
      'fields'             => 'all',   //戻り値に何を返すか
      'slug'               => '',      //指定したスラッグに一致するタームを返す
      'parent'             => '',      //直近の子タームを返すかどうか
      'hierarchical'       => true,    //子タームを持つタームを含めるかどうか
      'child_of'           => 0,       //指定したタームの子孫をすべて取得する
      'childless'          => false,   //タクソノミーが階層有りの場合、子を持たないタームのみを返すかどうか
      'get'                => '',      //この値を 'all' にすると 'hide_empty' と 'child_of' が無効に
      'name__like'         => '',      //ターム名にマッチさせたい文字列
      'description__like'  => '',      //タームの説明に指定した文字列が含まれるタームを返す
      'pad_counts'         => false,   //子孫タームすべてのカウントを合計するかどうか
      'offset'             => '',      //numberが指定されている時、見つかったタームの先頭から指定の個数を読み飛ばして返す
      'search'             => '',      //ターム名とスラッグにマッチさせたい文字列
      'cache_domain'       => 'core'   //作成したクエリにユニークなキャッシュ用キーを付与できる
    ); 

    *上記はget_temrsに指定できるものをまとめています。get_categoriesやget_tagsについて指定できるパラメータについてはget_termsで指定できるものよりいくつか少ないとしている記事が多かったのですが、その内容にはばらつきがありました。使用頻度の多いものに関しては共通で指定可能なので、とりあえず上記のパラメータを覚えておき、もしget_tagsなどで動作しないものがあれば、あ、これはget_terms専用のものなんだな、と思ってください。

    さて、それぞれのパラメータに関する詳細な説明は以下の通りです。

    パラメータ名 説明
    orderby (string) 何でソートするか
    • id
    • count
    • name (デフォルト)
    • slug
    • term_group (実装が充分ではないので利用は避けるべき)
    • none
    order (string) ソートする方向。
    • ASC : 昇順 (デフォルト)
    • DESC : 降順
    hide_empty (bool) まだ投稿のないタームを返さないのかどうか
    exclude (int|string|array) 除外するタームIDの配列、またはIDをコンマで区切りで指定。
    exclude_tree (int|array) 除外する親タームIDの配列
    include (int|array) 取得したいタームIDの配列。空文字列を指定するとすべてのタームを対象にします。
    number (int|array) 取得するタームの最大個数。デフォルト(null)ではすべてのタームを返します。
    fields (string) 戻り値に何を返すか
    • all : タームオブジェクトの配列を返す (デフォルト)
    • ids : タームIDの配列を返す
    • names : ターム名の配列を返す
    • count : 見つかったタームの個数を返す
    • id=>parent : 連想配列を返す(キーはタームID、値は親タームID)。親がない場合の値は0
    • id=>slug : 連想配列を返す(キーはタームID、値はスラッグ)。
    • id=>name : 連想配列を返す(キーはタームID、値はターム名)。
    slug (string|array) 指定した値がスラッグに一致するタームを返す。
    parent (int) 指定した値が親タームのIDである場合に、直近の子タームを返す。0 を指定すると第一階層(トップレベル)のタームのみを返す。
    hierarchical (bool) 子タームを持つタームを含めるかどうか。
    child_of (int) 指定したタームの子孫をすべて取得する。
    *child_of と parent の違い : parent が直近(1階層下)の子タームのみを取得するのに対し、child_of はすべての子孫タームを取得する。
    childless (bool) タクソノミーが階層有りの場合、 子を持たないタームのみを返すかどうか。
    階層無しの場合はすべてのタームを取得
    get (string) ‘all’ を指定すると、’hide_empty’ と ‘child_of’ が無効になる(すべてのタームを取得する)。
    name__like (string) 指定した文字列がターム名にマッチするものを取得する。ターム名に対してのみ、データベースクエリの LIKE ‘%string%’ を実行する。
    description__like (string) 指定した文字列がタームの説明にマッチするものを取得する。説明に対してのみ、データベースクエリの LIKE ‘%string%’ を実行する。
    pad_counts (bool) 子孫タームすべてのカウント(紐づけられている投稿数)を合計するかどうか。
    offset (int) ‘number’が指定されている場合、見つかったタームの先頭から指定の個数を読み飛ばして取得する。
    search (string) 指定した文字列がターム名またはスラッグにマッチするものを取得する。ターム名とスラッグにデータベースクエリの LIKE ‘%search_string%’ を実行する。
    cache_domain (string) get_〇〇s() が作成したクエリにユニークなキャッシュ用キーを付与できる。
    例えば、この関数のフィルターを使ってクエリを変更するとき、この値にユニークな値を指定しておけばキャッシュにある同様のクエリを上書きせず残しておける。

    使用例

    だーっとたくさんパラメータを列挙しましたが、実際に使用する時はそんなにたくさんのパラメータを指定することはあまりないかと思います。

    例: 投稿がまだ無いものも含めて、かつ第一階層カテゴリ(親カテゴリまたは小カテゴリを持たないもの)だけを取得する

    $args = array(
      'hide_empty' => false,
      'parent' => 0
    );
    $categories = get_categories($args);

    戻り値(タームオブジェクト)の中身

    次は上記の関数によって返される値についてみていきましょう。

    基本的には、戻り値にはタームオブジェクトが返されますので、オブジェクト内にどんな情報が含まれるかを整理してみます。

    * ‘fields’パラメータに「all」以外が指定されている場合はその値に合わせた戻り値になります。

    ・タームオブジェクトの中身

    object(WP_Term)#{
      ["term_id"]           => int()    //タームID
      ["name"]              => string() //ターム名
      ["slug"]              => string() //"タームスラッグ
      ["term_group"]        => int()    //タームグループID
      ["term_taxonomy_id"]  => int()    //タームタクソノミーID
      ["taxonomy"]          => string() //タクソノミー
      ["description"]       => string() //ターム説明
      ["parent"]            => int()    //親
      ["count"]             => int()    //投稿数
      ["filter"]            => string() //フィルタ
    
      //get_categories()を使用したときのみ以下も含まれる
      ["cat_ID"]                =>int()     //カテゴリID = ["term_ID"]
      ["category_count"]        =>int()     //投稿数 = ["count"]
      ["category_description"]  =>string()  //カテゴリ説明 = ["description"]
      ["cat_name"]              =>string()  //カテゴリ名 = ["name"]
      ["category_nicename"]     =>string()  //カテゴリスラッグ = ["slug"]
      ["category_parent"]       =>int()     //親 = ["parent"]
    }

    以上のような情報がオブェクトとして取得できます。

    WP_Term_Query

    次に、ver.4.6以降で追加されたWP_Term_Queryを使用する方法をまとめていきます。

    取得できる情報や条件の指定などはget_〇〇s関数とよく似ており、使用方法はWP_Queryとよく似ています。

    初見ではループを回して情報を処理していくので少し複雑に見えますが、非常に便利で強力なため、これまで紹介してきた複数の関数を覚えておく必要がなくなり、WP_Term_Queryさえ覚えておけば柔軟に対応することができるというメリットがあります。

    ・基本的な使用方法

    <?php
      $args = array(
        //条件の指定
      );  
      $the_query = new WP_Term_Query($args);
      foreach($the_query->get_terms() as $term){
        //ループ処理 
      }
    ?>

    WP_Queryをよく使う方には見慣れた形式かもしれませんが、the_post()を回す必要がない分、少しシンプルです。

    $args に指定できる条件については、get_〇〇sと同じだと思われます。

    * 使用できるパラメータについて、詳細に紹介されている記事などを見つけることができませんでした。

    ・使用例

    例:タグ一覧を取得し、タグ名とその投稿数をリンク付きでリスト表示する ( 条件 : 名前順でソートし、空タグ含む)

    <ul>
    <?php
      $args = array(
        'taxonomy' => 'post_tags',
        'orderby' => 'name',
        'hide_empty' => false,
      );
      $the_query = new WP_Term_Query($args);
      foreach($the_query->get_terms() as $term):
        $term_link = get_term_link($term->slug,'post_tags'); // リンク先URL
    
        echo '<li><a href="'.$term_link.'">'.$term->name.' ('.$term->count.')</a></li>';
    
      endforeach;
      ?>
    </ul>

    $argsの中身を変えれば取得できる情報が変わります。

    例: 第一階層のカテゴリ一覧を取得する( 条件 : 空カテゴリは含めずにid順でソートし、idが10のカテゴリを除く)

    $args = array(
      'taxonomy' => 'category'
      'orderby' => 'id',
      'hide_empty' => true,
      'parent' => 0,
      'exclude' => 10
    );

    wp_list_categories()

    最後に、カテゴリを一覧で出力してくれる関数、wp_list_categories() についてメモしていきます。

    get_〇〇sのようにwp_list_tags()などもあるかなと思ったのですが、調べたところないみたいですね。

    wp_list_categories() は、WordPress 2.1 で非推奨となった list_cats() および wp_list_cats() の後継で、この二つとほぼ同じように動作します。

    ・使用方法

    wp_list_categories( $args ); 

    引数には取得したいカテゴリに関する条件を配列で指定できます。

    これまでと違う点は、出力までしてくれることです。そのため、条件に指定できるパラメータも少し異なります。

    ・$argsに指定できるパラメータそれぞれの初期値

    <?php 
    $args = array(
      'show_option_all' => '',
      'orderby' => 'name',
      'order' => 'ASC',
      'style' => 'list',
      'show_count' => 0,
      'hide_empty' => 1,
      'use_desc_for_title' => 1,
      'child_of' => 0,
      'feed' => '',
      'feed_type' => '',
      'feed_image' => '',
      'exclude' => '',
      'exclude_tree' => '',
      'include' => '',
      'hierarchical' => 1,
      'title_li' => __( 'Categories' ),
      'show_option_none' => __( '' ),
      'number' => null,
      'echo' => 1,
      'depth' => 0,
      'current_category' => 0,
      'pad_counts' => 0,
      'taxonomy' => 'category',
      'walker' => null
    );
    wp_list_categories( $args ); 
    ?>

    get_〇〇s 関数のシリーズの時にはなかったものがいくつかありますね。

    各パラメータの説明は以下の通りです

    show_option_all (string) 空文字以外の文字列を設定すると、トップページへのリンクがリストの先頭に表示される。リンクテキストは指定した文字列。
    orderby (string) 何でソートするか。有効な値は’ID’,’name’,’slug’,’count’,’term_group’
    order (string) ソート順。有効な値は’ASC’,’DESC’
    style (string) カテゴリーリストの表示形式。
    • list – 箇条書き(<li>)(初期値)
    • none – 表示形式なし(各カテゴリーは <br>(改行)で区切られる)
    show_count (bool) 各カテゴリーに投稿数を表示するかどうか。初期値は false。
    hide_empty (bool) 投稿のないカテゴリーを非表示にするかどうか。初期値は true
    use_desc_for_title (bool) カテゴリーの説明をリンクの title 属性に挿入するかどうか。初期値は true
    child_of (int) このパラメータで指定したカテゴリーID の子カテゴリーのみ表示。
    (このパラメータを使うと、’hide_empty’ パラメータには false がセットされる。
    feed (string)空文字以外を指定すると各カテゴリーの rss-2 フィードへのリンクを表示する(リンクテキストは指定した文字列)。
    feed_type (string)フィードタイプ
    feed_image (string) 各カテゴリーの rss-2 フィードへのリンクを画像で表示したいとき、その画像の URI を指定。このパラメータは ‘feed’ パラメータより優先される。
    exclude (string) 指定したカテゴリーをリストから除外。複数指定する場合はカテゴリーIDをコンマ区切りで指定する。’child_of’ パラメータは自動的に無効となる。
    exclude_tree (string) 結果から除外するカテゴリーツリー。除外するツリーの最上位親カテゴリーID をコンマ区切りで指定。 注意点 : ‘include’ パラメータは空にすること。また、’hierarchical’ パラメータが true の場合、’exclude_tree’ の代わりに ‘exclude’ が使われる。
    include (string) 指定したカテゴリーID のみリストに表示する。複数の場合はコンマ区切りで指定。
    hierarchical (bool)サブカテゴリーを箇条書き項目の内側に表示するかどうか。(つまり、箇条書きを入れ子・ツリー表示にするかどうか。)
    初期値は true
    title_li (string) 箇条書きの外側に表示するタイトルと表示形式。デフォルトは “Categories” (日本語化ファイルで定義されていればそのstring)。空文字を指定すると何も表示しない。
    show_option_none (文字列) 表示するカテゴリーが一つも無いときに代わりに表示する文字列。デフォルトは “No categories” (日本語化ファイルで定義されていればそのstring)。
    number (int) 表示するカテゴリーの個数を設定(SQL の LIMIT 値)。初期値では無制限。
    echo (bool) 結果を表示するか、変数等へ値を返すか。初期値は true
    depth (int) カテゴリー階層のどのレベルまでをカテゴリーリストに出力するかを指定。初期値は 0<code>(全ての親子カテゴリーを出力)。
    • <code>0 – 全ての親子カテゴリーを出力 (初期値)
    • -1 – 全てのカテゴリーをフラット(インデントなし)形式で出力(’hierarchical’ パラメータより優先)
    • 1 – 最上位カテゴリーのみ出力
    • n – n(int)階層目までを出力。’2′ と指定すれば、最上位とすぐ下の子カテゴリーまでを出力。
    (‘hierarchical’と’depth’の関係がなんかややこしいみたい。意図した結果が得られない場合は調べてみる。)
    current_category (int) カテゴリーアーカイブページ以外で “current-cat” を表示させる。普通はカテゴリーアーカイブページのみで current-cat がセットされるが、それとは別の使い方をしたり、他のカテゴリーをハイライトしたい場合、このパラメータ(カテゴリー ID を指定)で関数による「現在」のカテゴリーの判断を上書きできる。
    pad_counts (bool) 子カテゴリーからの値を含めてリンク数または投稿数を計算するかどうか。初期値は false
    ‘show_counts’ と ‘hierarchical’ がどちらも true なら、自動的に true に設定される。
    taxonomy (string) カテゴリーを取得するタクソノミーの名前。
    walker (obj) リストをレンダリングする Walker クラス。有効な値は、Walker_Category en または Walker enを拡張するクラスのインスタンス

    デフォルトでの出力

    <li class="categories">カテゴリー
    <ul>
      <li class="cat-item cat-item-{ID}">
        <a href="カテゴリアーカイブへのリンク" title="カテゴリー概要があればその内容">カテゴリー名</a>
      </li>
      <li class="cat-item cat-item-{ID}">
        <a href="カテゴリアーカイブへのリンク">カテゴリー名</a>
        <ul class="children">
          <li class="cat-item cat-item-{ID}"><a href="カテゴリアーカイブへのリンク">子カテゴリー名</a></li>
          <li class="cat-item cat-item-{ID}"><a href="カテゴリアーカイブへのリンク">子カテゴリー名</a></li>
        </ul>
      </li>
    </ul>
    </li>

    ulタグの外側にliタグがあるので構造的におかしな状態で出力されてしまうことに注意が必要です。

     ‘title_li’ は空文字にすることを推奨します。

    ・使用例 (空カテゴリなし・第二階層まで表示・カウント数を表示)

    <ul>
      <?php
        $args = array(
          'title_li' => "",
          'depth' => 2,
          'hide_empty' => true,
          'show_count' => true
        );
        wp_list_categories($args);
      ?>
    </ul>
    
    
    <ul>
      <?php wp_list_categories('title_li=&depth=2&hide_empty=1&show_count=1'); ?>
    </ul>

    上記のように、’title_li’を空文字にする場合、ulタグは自分で記述しなければなりません。

    ちなみに、当サイトのサイドバーに表示しているカテゴリ一覧のリストはこの設定で出力したものです。

    また、’show_count’をtrueにしたときに表示される投稿数はデフォルトではaタグの外に出されていますが、当サイトではaタグの中に表示するようにカスタマイズしています。

    後日、その方法もメモしておこうと思います。

    まとめ

    少し情報量が多くてややこしかったかもしれないですが、個人的には WP_Term_Query wp_list_categories() だけを覚えておけばいいと思います。

    get_〇〇s 関数でできることはWP_Term_Queryでできるので。

    よきWordPress ライフを!

    - Thank you for reading this to the end. -

    コメントする

    CAPTCHA


    TOPへ Top