関数リファレンス/wp set object terms

説明

投稿やリンクなどのオブジェクトをタームとタクソノミータイプ（タグ、カテゴリー等）に関連づけます。 タームとタクソノミーの関連づけが存在しない場合、それも作成します。

後者の「関連づけ」とは、タームがタクソノミーによってグループ化されている（属している）状態です。 タームが属するタクソノミーを定義することによってコンテキストが与えられるまで、タームは意味を持ちません。

使用法

<?php wp_set_object_terms( $object_id, $terms, $taxonomy, $append ) ?>

パラメータ

$object_id

（整数） （必須） 投稿 ID など、関連づけるオブジェクト。

初期値： なし

$terms

（配列|整数|文字列） （必須） タームのスラッグまたは ID（例えばカテゴリーやタグの ID）。タクソノミー内のタームで関連づけられているものをすべて、このタームで置き換えます。オブジェクトからすべてのタームをクリアまたは削除するには、空文字列または NULL を指定します。整数はタームの ID と見なされます。注意：一部の関数はターム ID を文字列として返すため、ターム ID が数字だけから成るスラッグと解釈される場合があります！

初期値： なし

$taxonomy

（配列|文字列） （必須） タームをオブジェクトに関連づけるコンテキスト。カテゴリー（'category'）、投稿タグ（'post_tag'）、または他のタクソノミー名を指定できます。

初期値： なし

$append

（真偽値） （オプション） true ならタームがオブジェクトに追加されます。false なら既存のタグを置き換えます。

初期値： False

戻り値

(mixed) 

• (配列) 成功した場合、変更されたターム（term_taxonomy_id として！）の配列。
• (配列) $terms 引数が NULLもしくは空の場合、空の配列。 - タームの除去による成功メッセージ
• (WP_Error) 無効なタクソノミーの場合、WordPress Error オブジェクト（'invalid_taxonomy'）。
• (文字列) $terms パラメータに指定されたタームの何れかが誤って名付けられていた場合、最初の無効なターム（ただし、無効なターム ID は受け入れられ、挿入されます）。

フック

• アクション set_object_terms が wp-includes/taxonomy.php にあります。

例

投稿のカテゴリーをセット

ID 42 の投稿にカテゴリーを追加したい場合：

<?php
// 投稿に持たせたいカテゴリーの ID の配列。
$cat_ids = array( 6,8 );

/*
 * もし上記の値がデータベースや他のソースから来た場合は、整数であることを確かめる必要がある：

$cat_ids = array_map( 'intval', $cat_ids );
$cat_ids = array_unique( $cat_ids );

*/

$term_taxonomy_ids = wp_set_object_terms( 42, $cat_ids, 'category' );

if ( is_wp_error( $term_taxonomy_ids ) ) {
	// どこかにエラーがあり、タームをセットできなかった。
} else {
	// 成功！ 投稿のカテゴリーをセットできた。
}
?>

上記の例は、投稿のカテゴリーをぴったり配列で指定したものにします。 投稿が元々持っていたカテゴリーは外されます。 次の例も見てください。

投稿にカテゴリーを追加

以前のカテゴリーを残しつつ投稿にカテゴリーを追加するには、$append パラメータに true を指定します：

<?php

// 投稿に追加したいカテゴリーの ID の配列。
$cat_ids = array( 6, 8 );

/*
 * もし上記の値がデータベースや他のソースから来た場合は、整数であることを確かめる必要がある：

$cat_ids = array_map( 'intval', $cat_ids );
$cat_ids = array_unique( $cat_ids );

 */

// カテゴリーを追加する。最後の引数が true であることに注意。
$term_taxonomy_ids = wp_set_object_terms( 42, $cat_ids, 'category', true );

if ( is_wp_error( $term_taxonomy_ids ) ) {
	// どこかにエラーがあり、タームを追加できなかった。
} else {
	// 成功！ 投稿にカテゴリーを追加できた。
}
?>

投稿からすべてのカテゴリーを削除

投稿からすべてのカテゴリーをクリア（削除）するには、$terms に null を指定します：

<?php wp_set_object_terms( 42, null, 'category' ); ?>

改訂履歴

• 3.5.0 にて、データベース挿入に失敗した時は WP_Error オブジェクトを返すように改訂されました。
• 2.3.0 にて導入されました。

参考

• wp_set_object_terms() does not check if there is a a relationship between the object (=post type) and the taxonomy (like post_tag, category or a custom taxonomy). Because of that, any existing term will be paired with the object, whether or not there is a connection between the object and the taxonomy (of this particular term)!! ( Further information in german)

• おそらく wp_set_post_terms() の方が、より使いやすい関数といえるでしょう。それは値をチェックして、コンマで区切られたタームを変換し、整数で指定された階層のあるタームを検証するからです。

• 混乱するかもしれませんが、戻り値の配列はターム ID の代わりに term_taxonomy_id が要素になります。

ソースファイル

wp_set_object_terms() は wp-includes/taxonomy.php にあります。

関連項目

タームタグ: is_term(), term_exists(), get_objects_in_term(), get_term(), get_term_by(), get_term_children(), get_term_link(), get_terms(), get_the_terms(), get_the_term_list(), has_term(), sanitize_term(), the_terms(), get_object_taxonomies() is_object_in_taxonomy() the_taxonomies() wp_get_object_terms(), wp_set_object_terms(), wp_get_post_terms(), wp_set_post_terms(), wp_delete_object_term_relationships()

関数リファレンス、テンプレートタグ目次もご覧ください。

最新英語版： WordPress Codex » Function Reference/wp set object terms （最新版との差分）