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

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

関数リファレンス/get term by

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

タームのフィールドと検索条件を指定して、タームの全データをデータベースから取得します。

注意: $field が 'name' であっても、$value は HTML タグのエスケープ処理を受けません。必要な場合はご自分で行ってください。

$field のデフォルトは 'id' ですので、null を指定することもできますが、わざわざそうするのはお勧めしません。

$value が存在しない場合、false が返されます。 $taxonomy が存在し、かつ $field$value の組み合わせも存在すると、タームが返されます。

使い方

<?php get_term_by( $field, $value, $taxonomy, $output, $filter ) ?>

パラメータ

$field
文字列) (必須) 'id', 'slug', 'name', または 'term_taxonomy_id' の何れか。
初期値: 'id'
$value
文字列|整数) (必須) この値を検索。
初期値: なし
$taxonomy
文字列) (必須) タクソノミー名。category, post_tag, link_category またはカスタム分類の名前。
初期値: なし
$output
文字列) (オプション) 定数 OBJECT, ARRAY_A, ARRAY_N の何れか。
初期値: OBJECT
$filter
文字列) (オプション) デフォルトは raw で、その場合 WordPress の既定のフィルターはどれも適用されない。
初期値: 'raw'

戻り値

(mixed) 
データベースから取得したタームの行(オブジェクトまたは配列)。$taxonomy が存在しないか $term が見つからなければ false を返す。そうでなければ $output パラメータに基づいてオブジェクト(デフォルト)またはフィールドの配列を返す。

返されるフィールドは以下のとおり:

  • term_id (下記の「注意」を参照)
  • name
  • slug
  • term_group
  • term_taxonomy_id
  • taxonomy
  • description
  • parent
  • count

注意:文字列と整数の混同について! フィールドの値は term_id も含めて文字列形式で返されます。それを使う前に、値が数値なら本物の整数に型変換してください。そうしないと WordPress は、ターム ID と、数字だけから成るスラッグを混同してしまいます!

タクソノミー名は、タームの名前とは違います。また、必須項目です。 ID (term_id) はタームの ID であり、投稿 ID ではありません。

これを覚えておいてください:
↓ タクソノミーの種類(例えば post_tag )
「タクソノミー」に含まれるターム:
→ news
→ webdev
→ ...

名前とタクソノミーの種類(タクソノミー名が category, post_tag またはカスタム分類)を指定してタームを取得する例です。

// Get term by name ''news'' in Categories taxonomy.
$category = get_term_by('name', 'news', 'category')

// Get term by name ''news'' in Tags taxonomy.
$tag = get_term_by('name', 'news', 'post_tag')

// Get term by name ''news'' in Custom taxonomy.
$term = get_term_by('name', 'news', 'my_custom_taxonomy')

// Get term by name ''Default Menu'' from theme's nav menus.
// (Alternative to using wp_get_nav_menu_items)
$menu = get_term_by('name', 'Default Menu', 'nav_menu');

ID で取得する場合(投稿 ID ではありません):

// カテゴリー(投稿のカテゴリー)から ID (''term_id'') でタームを取得。
get_term_by('id', 12, 'category')

...


間違った使い方

注意:下記の例は間違いです(参考のため残してあります):

get_term_by('id', (int)$post->ID, 'taxonomy_name'); // 戻り値は null

この例はタームを取得するのに、ID (term_id) に投稿 ID を、それからタクソノミー taxonomy_name を指定しています。 このタクソノミーと ID の組み合わせは間違っています。

正しいバージョンの例は次のとおりです:

// get_term_by('id', category_id, 'category')

$postCategories = get_the_category($post->ID);
foreach ( $postCategories as $postCategory ) {
$myCategories[] = get_term_by('id', $postCategory->cat_ID, 'category');
}
// または:
$myCategory = get_term_by('id', $postCategories[0]->cat_ID, 'category');

参考

  • 注意: $field が 'name' であっても $value はエスケープ処理されません。必要な場合は自分で行ってください。
  • $filter パラメータに指定可能な値は、sanitize_term_field()$context パラメータのリストを見てください。
  • タームを返す前に、sanitize_term() を使用して、$filter のコンテキストに基づいて無害化します。
  • グローバル変数 (object) $wpdb を使用します。

変更履歴

バージョン 2.3.0 にて導入されました。

ソースファイル

get_term_by()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/get term by最新版との差分