• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

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

提供: WordPress Codex 日本語版
移動先: 案内検索

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

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

使用法

<?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 は受け入れられ、挿入されます)。

フック

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

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最新版との差分