wp_get_post_terms() の使い方｜説明・引数・注意点

説明

基本構文

wp_get_post_terms( int $post_id = 0, string|string[] $taxonomy = 'post_tag', array $args = array() ): array|WP_Error

引数

• $post_id：投稿ID
• $taxonomy：タクソノミー名
• $args：fields、orderby など

戻り値

ターム（またはIDの配列）。

使い方（サンプル）

$ids = wp_get_post_terms( 123, 'category', array( 'fields' => 'ids' ) );

注意点

• fields に ids や names を指定すると、必要な情報だけ取得できます。

実務での使いどころ

• 投稿に付いたタームを、条件（並び順や、取得する項目）を指定して取得するとき。
• タームのIDだけを、取得するとき（'fields' => 'ids'）。

よくあるミスと対処

• get_the_terms() と違い、ターム（が1つもない）のとき、空の配列が返る。false を想定して書いている。
• $taxonomy の既定は post_tag。カスタムタクソノミーは、明示的に指定する。
• エラー時には WP_Error が返る。

NG例

$terms = wp_get_post_terms( $post_id ); // タグだけが対象になる

OK例

$terms = wp_get_post_terms( $post_id, 'news_cat', array( 'fields' => 'names' ) );
if ( ! is_wp_error( $terms ) ) {
	echo esc_html( implode( ', ', $terms ) );
}

使い分け早見表

関連項目

get_the_terms()、wp_set_post_terms()

公式リファレンス：wp_get_post_terms() | Function | WordPress Developer Resources