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

説明

基本構文

wp_set_post_terms( int $post_id = 0, string|array $terms = '', string $taxonomy = 'post_tag', bool $append = false ): array|false|WP_Error

引数

• $post_id：投稿ID
• $terms：ターム（ID、名前の配列など）
• $taxonomy：タクソノミー名
• $append：true で追加、false で置き換え

戻り値

ターム関連IDの配列。失敗時は false。

使い方（サンプル）

wp_set_post_terms( 123, array( 'rock', 'jazz' ), 'genre' );

注意点

• 階層型タクソノミー（カテゴリーなど）では、名前ではなくIDを渡します。
• $append が false だと、既存のタームは置き換えられます。

実務での使いどころ

• 投稿に、タームを設定するとき（置き換え、または追加）。
• インポートや、フォームからの投稿で、ターム（タグなど）を付けるとき。

よくあるミスと対処

• $append を指定せず、既存のタームがすべて置き換わる。追加したいときは、true を指定する。
• 階層ありのタクソノミーに、ターム名を渡している。階層ありでは、タームのIDを渡す。
• タームのIDを、文字列で渡している。IDは、整数で渡す（階層ありのタクソノミーでは、文字列も整数に変換されるが、タグなどの階層なしでは、名前として扱われる）。

NG例

wp_set_post_terms( $post_id, array( 'news' ), 'category' ); // 階層ありのタクソノミーに名前を渡している。既存のカテゴリーも置き換わる

OK例

wp_set_post_terms( $post_id, array( 5, 8 ), 'category', true ); // IDを渡し、追加する

使い分け早見表

関連項目

wp_set_object_terms()、wp_get_post_terms()

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