投稿に付けたタグをテーマのテンプレートに表示したいとき、WordPress には目的の違ういくつかの関数が用意されています。この記事では、タグをそのまま出力する the_tags()、タグの配列を取得してループ処理する get_the_tags()、任意のタクソノミーに対応した get_the_term_list() の3つを中心に、正確な使い方と使い分けを解説します。初心者から中級者の方が、single.php などで自由にタグ表示を組み立てられるようになることを目指します。
目次
そもそもタグとカテゴリーは何が違うのか
WordPress の投稿には、標準で「カテゴリー」と「タグ」という2種類の分類が付けられます。カテゴリーは階層を持つ大分類で、タグは階層を持たない自由なキーワードです。内部的にはどちらも「タクソノミー（分類）」の一種で、カテゴリーは category、タグは post_tag というタクソノミー名で管理されています。
カテゴリーの取得・表示については get_the_category() や the_category() を使いますが、この記事で扱うのはタグ（post_tag）側の関数です。役割はよく似ているので、迷ったら「カテゴリー用か、タグ用か」を意識すると整理しやすくなります。
the_tags() でタグをそのまま出力する
一番手軽なのが the_tags() です。この関数はループの中で呼ぶと、現在の投稿に付いたタグをリンク付きで直接出力します。戻り値を受け取るのではなく、その場で echo される点がポイントです。
<?php
// 前後のテキストや区切り文字を指定して出力
the_tags( 'タグ：', '、', '' );
?>引数を省略すると、デフォルトでは先頭に「タグ:」というラベルが付き、各タグは , （カンマと半角スペース）で区切られて出力されます。引数はそれぞれ次の意味を持ちます。
| 引数 | 意味 |
|---|---|
$before | タグ一覧の前に出力する文字列（デフォルトは 'Tags: '／日本語版では「タグ: 」） |
$sep | 各タグの間に入れる区切り文字（デフォルトは ', '） |
$after | タグ一覧の後ろに出力する文字列（デフォルトは空文字） |
大切な性質として、the_tags() は投稿にタグが1つも付いていない場合、$before や $after を含めて何も出力しません。そのため「タグがあるときだけラベルを表示する」といった条件分岐を自分で書かなくても、余計なラベルだけが残る心配がありません。手早くタグ行を表示したいときに向いています。
get_the_tags() でタグを配列として取得する
出力ではなく、タグの情報をプログラムで扱いたいときは get_the_tags() を使います。この関数は現在（または指定した投稿ID）の投稿に付いたタグを WP_Term オブジェクトの配列として返します。タグが1つも無い場合や投稿が存在しない場合は false、内部エラー時は WP_Error を返します。
取得した各 WP_Term オブジェクトからは、タグ名（name）、スラッグ（slug）、ターム ID（term_id）などのプロパティを取り出せます。リンク URL は get_tag_link() にターム ID を渡して生成します。
<?php
// 現在の投稿のタグを配列で取得（無ければ false）
$tags = get_the_tags();
if ( $tags ) {
foreach ( $tags as $tag ) {
// タグ名とスラッグ、リンクURLを取り出す
$name = $tag->name;
$slug = $tag->slug;
$url = get_tag_link( $tag->term_id );
printf(
'<a href="%s">%s</a>',
esc_url( $url ),
esc_html( $name )
);
}
}
?>特定の投稿を対象にしたいときは、第1引数に投稿 ID を渡します。get_the_tags( 123 ) のように書くと、ID が 123 の投稿のタグを取得できます。省略した場合はループ内の現在の投稿が対象になります。
このように配列で受け取れると、区切り文字や HTML を細かく自分でコントロールできます。次のように ul と li でリスト形式のタグ表示も作れます。
<?php
$tags = get_the_tags();
if ( $tags ) : ?>
<ul class="post-tags">
<?php foreach ( $tags as $tag ) : ?>
<li>
<a href="<?php echo esc_url( get_tag_link( $tag->term_id ) ); ?>">
#<?php echo esc_html( $tag->name ); ?>
</a>
</li>
<?php endforeach; ?>
</ul>
<?php endif; ?>タグ名の前に # を付けたり、CSS でバッジ風のデザインにしたりと、マークアップを自由に組めるのが配列取得の利点です。出力する値は必ず esc_html()、URL は esc_url() でエスケープしておきましょう。タグ名は投稿者が自由に入力できるため、そのまま出力するとレイアウト崩れや意図しない HTML の混入につながる可能性があります。
get_the_term_list() で任意のタクソノミーに対応する
get_the_term_list() は、タグに限らず任意のタクソノミーに対して、リンク付きのタグ一覧を文字列として返す関数です。the_tags() がタグ専用だったのに対し、こちらはタクソノミー名を引数で指定できるため、カスタム分類にもそのまま使えます。
<?php
// 投稿ID、タクソノミー、前・区切り・後の順で指定
$list = get_the_term_list(
get_the_ID(), // 投稿ID
'post_tag', // タクソノミー（タグ）
'タグ：', // 前に付ける文字列
'、', // 区切り文字
'' // 後ろに付ける文字列
);
// 戻り値は文字列。false や WP_Error でないときだけ出力
if ( $list && ! is_wp_error( $list ) ) {
echo $list;
}
?>ここで注意したいのは、get_ が付いた関数なので値を「返す」だけで、自動では出力されないという点です。表示するには echo が必要です。引数は次のとおりです。
| 引数 | 意味 |
|---|---|
$id | 対象の投稿 ID |
$taxonomy | タクソノミー名。タグなら 'post_tag'、カテゴリーなら 'category'、カスタム分類ならその名前 |
$before | 一覧の前に付ける文字列 |
$sep | 各タームの区切り文字 |
$after | 一覧の後ろに付ける文字列 |
この関数は、対象のタームが無ければ false、無効なタクソノミーを指定すると WP_Error を返します。そのため上のコードのように is_wp_error() と組み合わせてチェックしてから出力すると安全です。生成される各リンクには rel="tag" 属性が付き、タグ名は内部で esc_html() によりエスケープされて返されるので、返ってきた文字列をそのまま echo して問題ありません。
出力までまとめて行いたい場合は、対になる出力版の the_terms() があります。the_terms( $id, $taxonomy, $before, $sep, $after ) は get_the_term_list() の結果をそのまま echo するイメージで、戻り値を受け取る必要がないぶん記述が短くなります。文字列を加工したいなら get_the_term_list()、そのまま表示するだけなら the_terms()、と覚えておくとよいでしょう。
3つの関数をどう使い分けるか
ここまで見てきた関数は、目的によって向き不向きがはっきり分かれます。とにかく手早くタグ行を出したいだけなら the_tags() が最短で、タグが無いときに何も出力しない気配りも効いています。一方、タグ名やリンクを1件ずつ加工したり、独自の HTML でマークアップを組みたいなら、配列を返す get_the_tags() が最も柔軟です。
そして、標準のタグだけでなくカスタムタクソノミーにも同じ書き方で対応したい場合は、タクソノミー名を指定できる get_the_term_list()（または the_terms()）が便利です。実際、get_the_term_list() の第2引数に 'category' を渡せばカテゴリー一覧も同じ関数で作れます。「タグかカテゴリーか」を意識せず1つの仕組みでまとめたいときに役立ちます。
なお、投稿単位のタグ表示ではなく、サイト全体でよく使われるタグを一覧化したいときは wp_tag_cloud() というタグクラウド用の関数もあります。こちらは特定の投稿ではなくサイト全体のタグを対象にする点が異なるので、目的に応じて選んでください。
タグが表示されないときに確認すること
ループの外で呼び出していないか
the_tags() や get_the_tags() を引数なしで使うときは、「現在の投稿」がループによって設定されている必要があります。while ( have_posts() ) : the_post(); の内側で呼ぶか、外で使う場合は投稿 ID を明示的に渡してください。ループの外で ID を省略して呼ぶと、対象の投稿が定まらず期待どおりに動きません。
そもそもタグが付いていない
投稿にタグが1件も設定されていなければ、the_tags() は何も出力せず、get_the_tags() と get_the_term_list() は false を返します。表示が空になったときは、まず管理画面の投稿編集画面でタグが登録されているかを確認しましょう。コードのミスではなくデータ側の問題であることが少なくありません。
get_ 系なのに echo を忘れている
get_the_tags() や get_the_term_list() は値を返すだけの関数です。the_tags() のように書いて画面に何も出ないときは、echo が抜けていないかを疑ってください。get_ が付く関数は取得用、付かない関数は出力用、という命名の規則を意識すると混乱を防げます。
まとめ
投稿のタグを表示するには、用途に合わせて3つの関数を使い分けます。the_tags( $before, $sep, $after ) はタグをリンク付きで直接出力し、タグが無ければ何も出さない手軽な関数です。get_the_tags( $id ) は WP_Term の配列（無ければ false）を返すので、get_tag_link() と組み合わせて自由なマークアップを組めます。get_the_term_list( $id, $taxonomy, $before, $sep, $after ) は任意のタクソノミーに対応した文字列を返し、echo して表示します。出力だけでよいなら the_terms() も選べます。いずれの場合も、自前で出力する値は esc_html() や esc_url() でエスケープすることを忘れないようにしましょう。