- 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細)
関数リファレンス/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' ); ?>
改訂履歴
参考
- 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 (最新版との差分)