get_terms

説明

array get_terms( mixed $args = array(), mixed $deprecated = '' mixed $taxonomies, [ mixed $args = '' ] )
条件を指定してタクソノミー情報を検索し、マッチしたすべてのデータを取得する。

パラメータ

バージョン4.5.0以降のパラメータは次の通り。

  • $args
    検索条件を指定する文字列または連想配列。主なキーワードは次の通り。
    キーワード意味
    taxonomyタクソノミーを示すcategory、post_tagなど
    orderbyソート対象を示すcount、name、slug、term_group、none、idなど(省略時は'name')
    orderソート順を示すASCかDESC(省略時はASC)
    hide_empty投稿記事がないタクソノミーを取得しない場合はtrue(1)、投稿記事がないタクソノミーも取得する場合はfalse(0)を指定(省略時はtrue)
    exclude取得したくないタクソノミーのID(複数指定する場合は,で区切る)
    exclude_tree取得したくないタクソノミーのID(複数指定する場合は,で区切る)。指定されたIDのタクソノミーが子タクソノミーを持っている場合、それらの子カテゴリーも除外される。
    include取得したいタクソノミーのID(複数指定する場合は,で区切る)
    number取得件数(省略時は条件にマッチするすべてを取得する)
    offset取得開始位置(省略時は0:先頭)
    fields情報項目を示すall、count、ids、namesなどを指定(省略時はall)
    slug取得したいタクソノミーのスラッグを指定
    hierarchicaltrue(1)またはfalse(0)を指定(省略時はtrue)
    search取得したいタクソノミーの名前(その一部)を指定
    name__like取得したいタクソノミーの名前の先頭部分を指定
    pad_counts子タクソノミーの投稿件数を親タクソノミーに加算する場合はtrue(1)を指定(省略時はfalse)
    getすべてのカテゴリー情報を取得する場合にallを指定
    child_ofカテゴリーのIDを指定(そのIDのタクソノミーの子孫がすべて対象となる)
    parentカテゴリーのIDを指定(そのIDのタクソノミーの子カテゴリーのみが対象となる)
    suppress_filter[4.8.0]フィルター処理しない場合はtrueを指定(省略時はfalse)
  • $deprecated
    非推奨(互換性維持のため存在)

バージョン4.4.3以前のパラメータは次の通り。

  • $taxonomies
    タクソノミー名。複数指定する場合は配列で指定。
    タクソノミー名意味
    categoryカテゴリー
    post_tag投稿タグ
    nav_menuメニュー
    link_categoryリンクのカテゴリー
  • $args
    検索条件を指定する文字列または連想配列。主なキーワードは次の通り。
    キーワード意味
    orderbyソート対象を示すcount、name、slug、term_group、none、idなど(省略時は'name')
    orderソート順を示すASCかDESC(省略時はASC)
    hide_empty投稿記事がないタクソノミーを取得しない場合はtrue(1)、投稿記事がないタクソノミーも取得する場合はfalse(0)を指定(省略時はtrue)
    exclude取得したくないタクソノミーのID(複数指定する場合は,で区切る)
    exclude_tree取得したくないタクソノミーのID(複数指定する場合は,で区切る)。指定されたIDのタクソノミーが子タクソノミーを持っている場合、それらの子カテゴリーも除外される。
    include取得したいタクソノミーのID(複数指定する場合は,で区切る)
    number取得件数(省略時は条件にマッチするすべてを取得する)
    offset取得開始位置(省略時は0:先頭)
    fields情報項目を示すall、count、ids、namesなどを指定(省略時はall)
    slug取得したいタクソノミーのスラッグを指定
    hierarchicaltrue(1)またはfalse(0)を指定(省略時はtrue)
    search取得したいタクソノミーの名前(その一部)を指定
    name__like取得したいタクソノミーの名前の先頭部分を指定
    pad_counts子タクソノミーの投稿件数を親タクソノミーに加算する場合はtrue(1)を指定(省略時はfalse)
    getすべてのカテゴリー情報を取得する場合にallを指定
    child_ofカテゴリーのIDを指定(そのIDのタクソノミーの子孫がすべて対象となる)
    parentカテゴリーのIDを指定(そのIDのタクソノミーの子カテゴリーのみが対象となる)

返り値

マッチしたすべてのデータが格納された配列を返す。タクソノミー情報のメンバー変数は次の通り。
プロパティ名データ型意味
term_idintID
namestring名前
slugstringスラッグ
term_groupintグループID
term_taxonomy_idintタクソノミーID
taxonomystringタクソノミー名
descriptionstring説明
parentint親タクソノミーのID。親タクソノミーがない場合は0となる
countint投稿数

注意

タクソノミー情報は、投稿記事の付随情報のことで、カテゴリーや投稿タグなどが含まれている。 get_categories get_tagsでは、このget_termsを使用して情報を取得している。
パラメータ$argsで指定する検索条件はデフォルトでは'hide_empty'がtrueのため、投稿のないタクソノミーは取得できない。投稿数に関係なくすべてのカテゴリー情報を取得する場合は、'get=all'を指定するのが便利。
なお'parent'が指定された場合は、'child_of=0'、'hierarchical=false'、'pad_counts=false'へと強制的に変更される。
また'get=all'が指定された場合は、'child_of=0'、'hide_empty=0'、'hierarchical=false'、'pad_counts=false'へと強制的に変更される。

[4.5.0]パラメータの仕様が変更となり、基本的に第1パラメータのみを使用するようになった(ただし、互換性維持のためそれ以前のパラメータでも動作している)。

[4.6.0]検索機能を備えたWP_Term_Queryクラスの登場により、'get_terms'以外のフィルターはそちらに移動。'get_terms'フィルターのパラメータに検索に使用したWP_Term_Queryオブジェクトが追加された。

[4.8.0]suppress_filterが追加され、get_termsフィルターの処理前の内容を取得できるようになった。


使用例

  • すべてのカテゴリー情報を取得する。
    <?php
    // 4.5.0以降
    $categories = get_terms( array( 'taxonomy'=>'category', 'get'=>'all' ) );
    
    // 4.4.3以前
    $categories = get_terms( 'category', 'get=all' ) );
    ?>
  • すべての投稿タグ情報を取得する。
    <?php
    // 4.5.0以降
    $tags = get_terms( array( 'taxonomy'=>'post_tag', 'get'=>'all' ) ); 
    
    // 4.4.3以前
    $tags = get_terms( 'post_tag', 'get=all' ) ); 
    ?>

フィルター

[4.4.0]パラメータ$argsとマージする前にデフォルトのクエリー条件を調整する'get_terms_defaults'フィルターを呼び出す。パラメータ$defaultsにはデフォルトのクエリー条件(連想配列)が、$taxonomiesには本関数が受け取った内容がfalseが格納される。
$args = wp_parse_args( $args, apply_filters( 'get_terms_defaults', $defaults, $taxonomies ) );
[3.1.0]パラメータ$argsの初期値を調整するために'get_terms_args'フィルターを呼び出す。パラメータ$args$taxonomiesには本関数が受け取った内容が格納される。
$args = apply_filters( 'get_terms_args', $args, $taxonomies );
[2.8.0]ソート対象を確定するために'get_terms_orderby'フィルターを呼び出す。パラメータ$orderbyはソート対象、$taxonomiesは本関数が受け取った内容が、$argsはフィルター処理済みの内容が格納される。
$orderby = apply_filters( 'get_terms_orderby', $orderby, $args, $taxonomies );
[2.3.0]除外するターム情報を確定するために'list_terms_exclusions'フィルターを呼び出す。パラメータ$exclusionsは除外する条件文、$taxonomiesは本関数が受け取った内容が、$argsはフィルター処理済みの内容が格納される。
$exclusions = apply_filters( 'list_terms_exclusions', $exclusions, $args, $taxonomies );
[2.8.0]ターム情報の取得する項目を確定するために'get_terms_fields'フィルターを呼び出す。パラメータ$selectsは項目の配列、$taxonomiesは本関数が受け取った内容が、$argsはフィルター処理済みの内容が格納される。
$selects = apply_filters( 'get_terms_fields', $selects, $args, $taxonomies );
[3.1.0]ターム情報の取得前に'terms_clauses'フィルターを呼び出す。パラメータ$clausesは検索項目の連想配列、$taxonomiesは本関数が受け取った内容が、$argsはフィルター処理済みの内容が格納される。
$clauses = apply_filters( 'terms_clauses', $clauses, $taxonomies, $args );
[2.3.0]ターム情報の配列を返す直前に'get_terms'フィルターを呼び出す。パラメータ$termsはターム情報の配列、$taxonomiesは本関数が受け取った内容が、$argsはフィルター処理済みの内容が格納される。[4.6.0]パラメータ$term_queryが追加され、検索に使用したWP_Term_Queryオブジェクトが格納される。
$terms = apply_filters( 'get_terms', $terms, $taxonomies, $args, $term_query );

アクション

実行するアクションはありません。

ソースファイル

/wp-includes/taxonomy.php

最終更新 : 2018年05月27日 10:51



お勧め

投稿画面のウェジェットを2列にする(2013年4月17日 更新)

ダッシュボード画面ではスクリーンレイアウトを最大4列まで選択できるのに、投稿画面は1列か2列のどちらか。高解像度のディスプレイを使っていると、投稿画面では大画面のメリットを生かせていない理由がここにあるのではと感じ、3列対応にしてみた。

プラグインの設定ページもレスポンシブ対応(2014年6月3日 更新)

レスポンシブ対応したWordPressの管理画面。プラグインやテーマのカスタマイズで管理画面を拡張しているなら、切り替わるタイミングはきっちり押さえておきたいところではないだろうか。

投稿一覧に独自リンクを追加する(2013年10月16日 更新)

管理者ページの「投稿一覧」や「固定ページ一覧」の各投稿記事はマウスポインタを移動すると、「編集」や「クイック編集」といったリンクが表示される。このリンクに独自のリンクを追加する方法を調べてみた。

Slightly troublesome permalink:プラグイン作ってみました(2017年12月17日 更新)

カテゴリーを含んだパーマリンクを設定している場合、複数のカテゴリーを指定した投稿記事のパーマリンクのURLに目的のカテゴリーとは異なるカテゴリーが適用された経験はないだろうか。このプラグインは、パーマリンクに適用されるカテゴリーをコントロールし、希望通りのパーマリンクを設定します。

HTML編集モードに定型文ボタンを追加する(2011年6月1日 更新)

投稿編集ページにはビジュアル編集モードとHTML編集モードがあり、それらを拡張するプラグインも多数存在している。そういったプラグインを利用するのもいいのだが、仕組みを理解するのも悪くないはず。というわけで、ここではHTML編集モードのボタンの仕組みと定型文を挿入するボタンを追加する方法を紹介する。