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

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

関数リファレンス/get terms

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

指定されたタクソノミー(カスタム分類)またはタクソノミーのリストについて、それに含まれるタームを取得します。

タームのオブジェクトの配列を返します。 もしタクソノミーの何れかが存在しなければ 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_ofparent の違いは、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 .= ' &middot; ';
        }
        else {
            $term_list .= '</p>';
        }
    }
    echo $term_list;
}

フィルター

クエリを実行せず結果を出力する時と、実行後の結果出力時に、フィルターを使ってカスタマイズを仕込むことができます。

'get_terms' フィルターは、タームがキャッシュにあるときに実行されます。見つかったタームと $taxonomies の配列と $args の配列が渡されます。

新たに検索して見つかったタームを返す前にも、同じフィルターが実行されます。タームの配列と $taxonomies と $args が渡されます。

'list_terms_exclusions' フィルターには、タームを除外するためのクエリの一部(NOT IN 句)と $taxonomies と $args が渡されます。

変更履歴

  • 4.2 : 引数 childless を追加。
  • 2.3 : 新規導入。

ソースファイル

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