get_terms

（2.3.0以降）
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	取得したいタクソノミーのスラッグを指定
hierarchical	true(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 リンクのカテゴリー

タクソノミー名	意味
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	取得したいタクソノミーのスラッグを指定
hierarchical	true(1)またはfalse(0)を指定（省略時はtrue）
search	取得したいタクソノミーの名前（その一部）を指定
name__like	取得したいタクソノミーの名前の先頭部分を指定
pad_counts	子タクソノミーの投稿件数を親タクソノミーに加算する場合はtrue(1)を指定（省略時はfalse）
get	すべてのカテゴリー情報を取得する場合にallを指定
child_of	カテゴリーのIDを指定（そのIDのタクソノミーの子孫がすべて対象となる）
parent	カテゴリーのIDを指定（そのIDのタクソノミーの子カテゴリーのみが対象となる）

返り値

マッチしたすべてのデータが格納された配列を返す。タクソノミー情報のメンバー変数は次の通り。

プロパティ名	データ型	意味
term_id	int	ID
name	string	名前
slug	string	スラッグ
term_group	int	グループID
term_taxonomy_id	int	タクソノミーID
taxonomy	string	タクソノミー名
description	string	説明
parent	int	親タクソノミーのID。親タクソノミーがない場合は0となる
count	int	投稿数

注意

タクソノミー情報は、投稿記事の付随情報のことで、カテゴリーや投稿タグなどが含まれている。 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

最終更新 : 2023年08月02日 11:21

参考

Code Reference: get_terms

お勧め

カテゴリー専用の投稿一覧と新規投稿メニューを追加する（2012年1月23日更新）

サイト更新の1クリックを省くため、特定カテゴリーの投稿に対して同じようにメニューを追加してみた。カスタム投稿タイプの専用投稿メニューみたいな感じである。

ブロックエディターの文字サイズ設定を変えてみる（2019年12月12日更新）

今回は「前回投稿した内容」の続きブロックエディターの文字サイズ設定を変えようと思う。参考にするテーマはもちろん「Twenty Twenty」である。

4.2で始まるiOSの絵文字ケア（2018年5月27日更新）

WordPress 4.2のベータ1、ベータ2が立て続けにリリースされ、4.2の正式版リリースが近づいています。4.2のポイントの1つは絵文字のクロスブラウザ対応です。ここでの絵文字とは、UTF-8で4バイトのコードが割り当てられている（基本的にはiOSの）絵文字を指します。この絵文字を含んだ投稿が正しく保存できなかったり、iOS以外の環境で意図した通りに表示できないといった問題があり、4.2ではそのような問題を対処をコードが組み込まれています。

「不明な書式」って何ですか。（2024年11月13日更新）

オートコンプリート機能を利用して四字熟語を挿入するプラグインを作った際、ツールバーに「不明な書式をクリア（Clear Unknown Formatting）」ボタンが表示されるようになった。この「書式」、何を指しているのかわからないんだが。

決まった値を返すだけの関数群（2018年5月27日更新）

WordPressのソースコードを眺めているとフィルター関数名で'__return_○○'が指定されている部分を時々見かけます。それらの関数定義を見てみると、すべて決まった値を単純に返すだけでした。これらの関数がちょっと気になったので、まとめてみました。

説明