- 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。（詳細）
関数リファレンス/get terms
指定されたタクソノミー（カスタム分類）またはタクソノミーのリストについて、それに含まれるタームを取得します。
タームのオブジェクトの配列を返します。 もしタクソノミーの何れかが存在しなければ WP_Error オブジェクトを返します。
使い方
<?php $terms = get_terms( $taxonomies, $args ); ?>
デフォルトの使い方
<?php
// タクソノミーにはデフォルト値がないので下記を例として使う。
$taxonomies = array(
'post_tag',
'my_tax',
);
$args = array(
'orderby' => 'name',
'order' => 'ASC',
'hide_empty' => true,
'exclude' => array(),
'exclude_tree' => array(),
'include' => array(),
'number' => '',
'fields' => 'all',
'slug' => '',
'parent' => '',
'hierarchical' => true,
'child_of' => 0,
'childless' => false,
'get' => '',
'name__like' => '',
'description__like' => '',
'pad_counts' => false,
'offset' => '',
'search' => '',
'cache_domain' => 'core'
);
$terms = get_terms( $taxonomies, $args );
?>
パラメータ
- $taxonomies
- （文字列|配列） （必須） タームを取得するタクソノミー。（参考：デフォルト分類）
- 初期値： なし
- $args
- （文字列|配列） （オプション） 戻り値の種類を変更。
- 初期値： 下記の指定できる引数を参照。
指定できる引数
- orderby
- (文字列) ソートするフィールド。
- id
- count
- name - デフォルト
- slug
- term_group - 実装が充分ではない（利用を避けること）
- none
- order
- (文字列) ソートする方向。
- ASC - デフォルト（昇順）
- DESC
- hide_empty
- (真偽値) 空の（投稿などのオブジェクトに付けられていない）タームを返しません。
- 1 (true) - デフォルト（空のタームを出力しない）
- 0 (false)
- exclude
- (整数|文字列|配列) 除外するタームの ID の配列。ID をコンマで区切って文字列として指定することもできます。
- exclude_tree
- (整数) 除外する親タームの ID の配列。
- include
- (整数) 含めるタームの ID の配列。空文字列を指定するとすべてのタームを対象にします。
- number
- (整数) 返すタームの最大個数。デフォルトではすべてのタームを返します。
- fields
- (文字列)
- all - タームオブジェクトの配列を返す - デフォルト
- ids - 整数（ターム ID）の配列を返す
- names - 文字列（ターム名）の配列を返す
- count - （バージョン 3.2 以上）見つかったタームの個数を返す
- id=>parent - 連想配列を返す。キーはターム ID、値は親タームの ID またはゼロ（親がない場合）
- id=>slug - 連想配列を返す。キーはターム ID、値はスラッグ
- id=>name - 連想配列を返す。キーはターム ID、値はターム名
- slug
- (文字列|配列) 指定した値がスラッグに一致するタームを返す。デフォルトは空文字列。
- parent
- (整数) 直近の子タームを返す（指定された値が親タームの ID であるタームのみ）。ゼロを指定するとトップレベルのタームのみを返す。デフォルトは空文字列。
- hierarchical
- (真偽値) 子タームを持つタームを含める（ 'hide_empty' が true のときでも）。
- 1 (true) - デフォルト
- 0 (false)
- child_of
- (整数) 指定したタームの子孫をすべて取得します。デフォルトは 0 です。参考： child_of と parent の違いは、parent が直近の子ターム（1 レベル下）のみを取得するのに対して、child_of はすべての子孫タームを取得します（存在するレベルすべて）。
- childless
- (真偽値) タクソノミーが階層有りの場合、子を持たないタームのみを返します。階層無しの場合、すべてのタームを対象とします。（バージョン 4.2 で追加されました。）
- get
- (文字列) デフォルトは空文字列です。この値を 'all' にすると 'hide_empty' と 'child_of' が無効になります（すべてのタームを取得します）。
- name__like
- (文字列) ターム名にマッチさせたい文字列。ターム名に対してのみ、データベースクエリの LIKE '%string%' を実行します。これは名前に 'name__like' の文字列を含むタームにマッチします。参考：これは WordPress 3.7 からの仕様です。以前は name__like の文字列で始まる名前のタームにマッチしていました。チケット #8214 を参照してください。
- description__like
- (文字列) タームの説明に 'description__like' の文字列を含む（大文字小文字を区別して）タームを返します。デフォルトは空文字列です。説明に対してのみ、データベースクエリの LIKE '%string%' を実行します。これは説明に 'description__like' の文字列を含むタームにマッチします。
- pad_counts
- (真偽値) true のとき、子孫タームすべてのカウント（投稿などのオブジェクトに付けられている回数）を合計します。
- 1 (true)
- 0 (false) - デフォルト
- offset
- (整数) 見つかったタームの先頭から指定の個数を読み飛ばして返します。必ず 'number' と一緒に使ってください。そうしないと 'offset' は無視されて結果すべてが返されます。
- search
- (文字列) ターム名にマッチさせたい文字列。ターム名とスラッグに対して、データベースクエリの LIKE '%search_string%' を実行します。これは 'search_string' の文字列を含むタームにマッチします。
- cache_domain
- (文字列) バージョン 3.2 以上で使えます。'cache_domain' 引数は、get_terms() が作成したクエリにユニークなキャッシュ用キーを付与できます。例えば、この関数のフィルターを使ってクエリを変更するとき（例えば 'terms_clauses'）、'cache_domain' にユニークな値を指定しておけば、キャッシュにある同様のクエリを上書きせず残しておけます。デフォルト値は 'core' です。
参考：引数は wp_parse_args() で使われる形式で与えます。
戻り値
- (配列|文字列|WP_Error)
- タームオブジェクトの配列。タームが見つからなければ空の配列を返します。$taxonomies の何れかが存在しなければ WP_Error を返します。'fields' 引数が 'count' の時は、見つかったタームの個数を文字列形式で返します。
返されるフィールドは以下のとおり：
- term_id （下記の「注意」を参照）
- name
- slug
- term_group
- term_taxonomy_id
- taxonomy
- description
- parent
- count
注意：文字列と整数の混同について！ フィールドの値は term_id も含めて文字列形式で返されます。それを使う前に、値が数値なら本物の整数に型変換してください。そうしないと WordPress は、ターム ID と、数字だけから成るスラッグを混同してしまいます！
例
すべての投稿のカテゴリーをカウント（投稿に付けられている回数）でソートして取得します。
文字列形式の引数：
$categories = get_terms( 'category', 'orderby=count&hide_empty=0' );
配列形式の引数：
$categories = get_terms( 'category', array( 'orderby' => 'count', 'hide_empty' => 0 ) );
リンクのカテゴリーをすべて取得します：
$mylinks_categories = get_terms( 'link_category', 'orderby=count&hide_empty=0' );
カスタム分類のタームをすべてリストします。リンクは付けません：
$terms = get_terms( 'my_taxonomy' );
if ( ! empty( $terms ) && !is_wp_error( $terms ) ){
echo '<ul>';
foreach ( $terms as $term ) {
echo '<li>' . $term->name . '</li>';
}
echo '</ul>';
}
すべてのタームを取得して、タームのアーカイブへのリンクを付け、中黒 (·) で区切って表示します：
$args = array( 'hide_empty=0' );
$terms = get_terms( 'my_term', $args );
if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
$count = count( $terms );
$i = 0;
$term_list = '<p class="my_term-archive">';
foreach ($terms as $term ) {
$i++;
$term_list .= '<a href="' . get_term_link( $term ) . '"';
$term_list .= ' title="' . sprintf( __('View all post filed under %s', 'my_localization_domain' ), $term->name ) . '">';
$term_list .= $term->name . '</a>';
if ( $count != $i ) {
$term_list .= ' · ';
}
else {
$term_list .= '</p>';
}
}
echo $term_list;
}
フィルター
クエリを実行せず結果を出力する時と、実行後の結果出力時に、フィルターを使ってカスタマイズを仕込むことができます。
'get_terms' フィルターは、タームがキャッシュにあるときに実行されます。見つかったタームと $taxonomies の配列と $args の配列が渡されます。
新たに検索して見つかったタームを返す前にも、同じフィルターが実行されます。タームの配列と $taxonomies と $args が渡されます。
'list_terms_exclusions' フィルターには、タームを除外するためのクエリの一部（NOT IN 句）と $taxonomies と $args が渡されます。
変更履歴
ソースファイル
get_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/get_terms （最新版との差分）
