WordPressでターム情報を取得するのによく使われる、get_term()、get_terms()、get_the_terms()の使い方です。取得するときの状況によって使い分けます。
get_term($term_id, $taxonomy):あるタームを取得
get_term()は、あるタームの情報を取得するテンプレートタグです。
termが単数形で書いてあることから分かるように、ある1つだけのターム情報を取得します。その1つを限定するために、タームのIDを使います。
// areaタクソノミーのID5のタームを取得する
$term = get_term(5, 'area');
echo $term->name; // (例)広島
echo $term->slug; // (例)hiroshima
areaタクソノミーのID5のタームを取得する例です。タームの名前やスラッグを表示できます。
取得できる情報(プロパティ)の一覧は以下の通りです。
プロパティ | 説明 |
---|---|
term_id | タームのID |
name | タームの名前 |
slug | タームのスラッグ |
term_group | 親タームのID(parentと同じ) |
term_taxonomy_id | 属するタクソノミーのID |
taxonomy | 属するタクソノミーの名前 |
description | タームの説明 |
parent | 親タームのID(term_groupと同じ) |
count | このタームに属している記事数 |
タームが見つからなかった場合は、nullが返ってきます。タクソノミーが見つからなかった場合は、エラーが返ってきます。
オプションの第3引数と第4引数
get_term()の第3引数で、返却される値の形式を設定できます。設定しなければ、オブジェクト形式で返却されます。
設定できる形式は以下の3つです。
設定値 | 返却される形式 |
---|---|
OBJECT | オブジェクト |
ARRAY_A | 連想配列 |
ARRAY_N | 配列 |
第4引数は、フィルターを設定できます。
第3引数と第4引数は、特別な事情がなければ設定する必要はありません。
get_terms($taxonomy, $args):あるタクソノミーに含まれるタームを取得
get_terms()は、あるタクソノミーに含まれるタームの情報を取得するテンプレートタグです。
先ほどのget_term()と違い、termsが複数形で書いてあります。つまり、あるタクソノミーに含まれるタームを複数取得します。複数のターム情報なので、配列形式で値が返ってきます。配列には、オブジェクト形式で各タームの情報が入っています。
第1引数で、タクソノミーを指定します。1つだけの場合は、そのまま文字列で書きます。複数のタクソノミーを指定することも可能で、その場合は配列形式で書きます。
第1引数で指定したタクソノミーに含まれるタームの情報を取得します。存在しないタクソノミーがあった場合は、エラーが返ってきます。
第2引数で、取得するときの条件を指定します。第2引数はオプションなので、デフォルトのままで良ければ指定する必要はありません。
<?php
// areaタクソノミーのターム一覧を取得する
$args = [
'hide_empty' => false,
];
$terms = get_terms('area', $args);
if( $terms ):
?>
<ul class="term-list">
<?php foreach( $terms as $term ): ?>
<li class="term-list__item"><?php echo $term->name; ?></li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
areaタクソノミーに含まれるタームの一覧を取得する例です。
3~5行目で、取得するときの条件を指定して$argsに入れています。そして、その$argsをget_terms()の第2引数に入れています。今回の例では、hide_emptyをfalseにしています。これは、「そのタームに属する記事が投稿されていない場合、そのタームは取得しない」という条件です。デフォルトではtrueなので、ここではfalseにしています。これにより、記事の有無に関係なく全てのタームを取得できます。
指定できる条件の一覧は下記サイトに書いてあります。
関数リファレンス/get terms – WordPress Codex 日本語版
指定できる条件の中にfieldsというプロパティがあり、その指定によってはタームのIDや名前あるいは個数だけ返却させることも可能です。デフォルトでは全ての情報がオブジェクト形式で返却されるので、特に事情が無ければ指定せずにそのまま使います。
タームが見つからなかったら空の配列が返却されるので、8行目でif文を使って、タームが見つかった時だけ表示処理を行っています。
取得されたタームオブジェクトの内容は、get_term()で取得したときと同じです。nameやslugなどに同じ要領でアクセスできます。
get_the_terms($post_id, $taxonomy):ある記事が属しているタームを取得
get_the_terms()は、ある記事が属しているタームの情報を取得するテンプレートタグです。
先ほどのget_terms()にtheがついた関数です。get_terms()は指定されたターム全てを取得しましたが、get_the_terms()はある記事に割り当てられたタームに限定されます。ある記事を特定するために、第1引数に記事IDを指定します。そして第2引数には、タクソノミーを指定します。
<?php
// ある記事が属するareaタクソノミーのタームを取得する
$terms = get_the_terms($post->ID, 'area');
if( $terms ):
?>
<ul class="term-list">
<?php foreach( $terms as $term ): ?>
<li class="term-list__item"><?php echo $term->name; ?></li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
ある記事が属するareaタクソノミーのタームを取得する例です。
get_terms()と使い方が似ています。各タームのオブジェクトが配列形式で返却されるので、foreach文でループさせています。記事がどのタームにも属していなければ、falseが返ってきます。そのため、5行目でif文を使って、タームを取得したときだけ表示処理を行っています。
第2引数に存在しないタクソノミーを指定した場合は、エラーが返ってきます。
各タームのオブジェクトは、get_term()やget_terms()と同じです。nameやslugなどに同じ要領でアクセスできます。