1. ホーム
  2. WordPress

【WordPress】get_terms で分類（ターム）の一覧を取得する方法

Share

カテゴリーやタグ、独自に作った分類（カスタムタクソノミー）の一覧をテーマ内で表示したい場面はよくあります。WordPress には登録されたターム（分類の項目）を柔軟に取得できる get_terms() という関数があります。この記事では get_terms() の基本的な使い方と、よく使う引数、投稿数ゼロのタームを含める方法、つまずきやすい点までをコード例つきで解説します。

get_terms() でできること

「ターム」とは、カテゴリーやタグなどの分類に属する1つ1つの項目のことです（例: カテゴリーの「お知らせ」「ブログ」など）。get_terms() は、指定したタクソノミー（分類の種類）に登録されたタームを配列で取得します。取得した一覧をループで回して、サイドバーのカテゴリー一覧やタグクラウドのような表示を自分で組み立てられます。

基本の使い方

もっともシンプルな使い方は、引数に taxonomy（タクソノミー名）を指定する形です。カテゴリーなら category、タグなら post_tag を指定します。戻り値は WP_Term オブジェクトの配列です。

sidebar.php
<?php
// カテゴリーの一覧を取得
$terms = get_terms( array(
    'taxonomy' => 'category',
) );

// エラーチェック（取得失敗時は WP_Error が返る）
if ( ! is_wp_error( $terms ) && ! empty( $terms ) ) {
    echo '<ul>';
    foreach ( $terms as $term ) {
        printf(
            '<li><a href="%s">%s（%d）</a></li>',
            esc_url( get_term_link( $term ) ),  // タームのリンク
            esc_html( $term->name ),            // ターム名
            $term->count                        // 投稿数
        );
    }
    echo '</ul>';
}

各 WP_Term からは name（名前）、slug（スラッグ）、term_id（ID）、count（その分類に属する投稿数）などが取り出せます。リンクは get_term_link() で生成します。出力時は esc_html() や esc_url() でエスケープするのを忘れないようにしましょう。

よく使う引数

get_terms() は引数の配列で取得条件を細かく指定できます。代表的なものをまとめます。

引数説明
taxonomy取得する分類名（category / post_tag / 独自の分類名）
hide_empty投稿が無いタームを隠すか。初期値は true
orderby並び替えの基準（name / count / term_id など）
order並び順（ASC 昇順 / DESC 降順）
number取得する件数の上限
parent指定した親タームの直下の子だけを取得

たとえば「投稿数の多い順に上位5件」を取得するなら、次のように書きます。

popular-terms.php
<?php
$terms = get_terms( array(
    'taxonomy' => 'category',
    'orderby'  => 'count', // 投稿数で並べる
    'order'    => 'DESC',  // 多い順
    'number'   => 5,       // 上位5件
) );

投稿数ゼロのタームも取得する

get_terms() は初期状態で hide_empty が true のため、投稿が1件も紐付いていないタームは結果に含まれません。「まだ投稿がないカテゴリーも含めて全部表示したい」ときは、hide_empty を false にします。

all-terms.php
<?php
$terms = get_terms( array(
    'taxonomy'   => 'category',
    'hide_empty' => false, // 投稿が無いタームも含める
) );

カスタムタクソノミーの管理用に全項目を一覧したいときや、セレクトボックスの選択肢として使いたいときに役立ちます。

特定の投稿が持つタームを取得する

get_terms() はサイト全体のタームを取得する関数です。「ある投稿に設定されているタームだけ」が欲しい場合は get_terms() ではなく get_the_terms() を使います。混同しやすいので使い分けに注意してください。

single.php
<?php
// 表示中の投稿に設定された「genre」タクソノミーのタームを取得
$terms = get_the_terms( get_the_ID(), 'genre' );

if ( $terms && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        echo esc_html( $term->name ) . ' ';
    }
}

タームが取得できないとき

空配列が返ってくる

結果が空になる原因で多いのが、hide_empty の初期値です。投稿が紐付いていないタームは既定で除外されるため、登録したばかりのタームは表示されません。全件取得したいときは hide_empty => false を指定してください。また、taxonomy 名のスペルミスでも空になります。カスタムタクソノミーの場合は register_taxonomy() で登録した名前と一致しているか確認しましょう。

カスタムタクソノミーが反映されない

独自の分類を get_terms() で取得するには、その前に register_taxonomy() による登録が済んでいる必要があります。登録は init フックで行うのが基本です。テーマやプラグインの読み込み順によっては、登録より前に get_terms() が呼ばれて取得できないことがあるので、テンプレート側で呼ぶようにすると安全です。

まとめ

get_terms() は、分類のタームを自由に取得して一覧表示するための便利な関数です。

  • taxonomy を指定して、登録済みのタームを配列で取得できる
  • 各 WP_Term から name / slug / count などが取り出せる
  • orderby / order / number で並び替えや件数を制御できる
  • 投稿が無いタームも欲しいときは hide_empty => false
  • 特定の投稿のタームが欲しいときは get_the_terms() を使う

カテゴリー一覧やカスタム分類のメニューを自作するときは、get_terms() を使うと表示を自由にカスタマイズできます。引数の組み合わせを試しながら、欲しい一覧を作ってみてください。

参考ページ