以前のSitePoint記事『How to List Categories in WordPress Using the Categories API』でwp_list_categories()関数を紹介しました。記事に書いたとおりこの関数は多種多様なオプションを搭載していて、カテゴリーをリスト表示したいときに使うと大きなメリットがあります。
しかし、考えられるすべてのケースに対してwp_list_categories()関数だけでは対応できないので、カテゴリーAPIのほかの関数も使います。それらの関数を使うと、サイトのカテゴリーに関するHTMLリストの代替として生データ、つまりカテゴリーを格納した配列を取得できます。
結果的に、DOMツリーでイメージできるどのようなデータでもよりシンプルにしかもきちんと表示できます。始めにカテゴリー関連のすべてのデータを格納したオブジェクトを返す関数を紹介し、そのあと、特定の情報だけを返す関数の解説をします。
カテゴリーをオブジェクトとして取得する
リンクマネージャーでのリンクのように、すべてのプロパティを格納したオブジェクトとしてカテゴリーを取得できます。はじめに単一のカテゴリーのみを返す関数の説明します。新たに得た知識を活用すれば、必要なカテゴリーをすべて扱えるようになるでしょう。
IDを使って所定のカテゴリーを取得する
最初に紹介する関数はget_category()です。基本的に、パラメーターとしてIDを渡すとそのカテゴリーを表すオブジェクトを取得できる関数です。
$cat = get_category(14);
上のコードで$catに目的のオブジェクトが格納されます。注目すべきプロパティを説明します。
■カテゴリーID
最初に必要なのはカテゴリーIDです。この値はcat_IDプロパティ内にあります。
$id = $cat->cat_ID;
関数のパラメーターとして渡したこのIDはすでに分かっているので、いまはそれほど役に立ちません。あとで述べるようにカテゴリーの取得方法はほかにもあり、場合によってはカテゴリーオブジェクト内のIDの取得方法を知っておくと役立ちます。
扱っているのが別のカテゴリーの子カテゴリーであるなら、category_parentプロパティを使って親カテゴリーのIDも取得できます。親カテゴリーが存在しない場合、この値は0に設定されています。
■データをすべて取得！
カテゴリーについての情報を表示する際、重要な部分となるのはカテゴリー名です。cat_nameプロパティを使ってカテゴリー名を、category_descriptionプロパティを使ってカテゴリーの説明文を取得できます。
<h1><?php echo $cat->cat_name; ?></h1>
<p><?php echo $cat->category_description; ?></p>
カテゴリーの識別情報には、IDだけでなく文字列形式のスラッグ（一般にカテゴリー名を小文字でスペースと特殊文字を使わずに表記したもの）もあります。スラッグはcategory_nicename、またはslugプロパティで取得できます（どちらも有効です）。
さらにcategory_countプロパティでカテゴリー内の投稿数も取得できます。このプロパティでは子カテゴリー内に存在する投稿数はカウントされません。
■うそをついていました
見出しを「うそをついていた」としたのは、実はカテゴリーの表示に使えるのはオブジェクトだけではないからです。get_category()の2番目の引数を使って、配列の形で取得するという選択肢もあります。
// Get an object (default behavior)
$cat = get_category(15, OBJECT);
// Get an associative array
$cat = get_category(15, ARRAY_A);
// Get an numbered array
$cat = get_category(15, ARRAY_N);
連想配列（associative array）のキーはオブジェクトのプロパティです。しかし、インデックス配列（numbered array）では、順番は同じですがインデックスが分かりにくいためいくらか複雑になります。
■IDを使わずにカテゴリーを取得する
先に述べたように、カテゴリーの識別情報はIDだけではありません。カテゴリーのスラッグもカテゴリー情報の取得に使用でき、get_category_by_slug()関数で取得します。すでに分かっていると思いますが、この関数はスラッグをパラメーターとして受け取ります。
$cat = get_category_by_slug('my-goldfish');
返されるオブジェクトは、get_category()で説明したものと同じなので取り上げません。しかし、この関数では、選択の余地なくオブジェクト形式のみが利用可能で、配列は取得できません。さらに指定されたスラッグを持つカテゴリーが存在しない場合、get_category_by_slug()はfalseを返します。
複数のカテゴリーを取得する
カテゴリーの任意のリストの取得をする関数、所定の投稿に関連したカテゴリーの取得に役立つ関数を紹介します。
必要なカテゴリーをすべて取得する
ここまで読み進んできたら、get_categories()で返される値は分かるでしょう。なぜなら、この関数は必要なカテゴリーをすべて列挙する配列を返し、それぞれのカテゴリーは、これまでに説明してきたオブジェクトによって表されるからです。
引数なしでは、この関数は作成済みのすべてのカテゴリーを返します。下のように記述すると、
$cats = get_categories();
$catsにすべてのカテゴリーをアルファベット順に格納する配列が入ります。たとえば、2番目のカテゴリーの名前を取得する場合、$cats[1]->cat_nameと記述するだけでです（カテゴリーのオブジェクトについては先の詳しい説明を参照してください）。
変数$catsでprint_r()を実行すると、奇妙なことに気づくかもしれません。この配列には「穴」が開いている場合があるのです。たとえばインデックスに1、2、3がなく、0の次がすぐ4になっていることがあります。なにが起きたのでしょうか。この奇妙なカウントはどのようなことなのでしょうか。
実はこれは奇妙なことではありません。このいわゆる「バグ」に首尾よく気づいた人は、おそらく欠落しているカテゴリーがまさに「空」であることにも気づいたでしょう。デフォルトでWordPressは空のカテゴリーを表示しません。大丈夫、バグではないのです！
ほかのカスタマイズと合わせて、get_categories()に渡せる引数を使って修正できます。通常、この固有の引数は目的とするすべてのオプションを格納する配列です。
wp_list_categories()について説明したカテゴリーAPIに関する過去記事を参考にしてください。実際get_categories()で利用できる、ほとんどすべてのオプションはwp_list_categories()と同じなのでここでは省略します。
wp_list_categories()では、orderbyとorderを使って希望の順序を選択したり、numberを使って返されるカテゴリー数を制限したり、さらにhide_emptyを使って空カテゴリーの取得を選択したりできます。includeとexcludeの使用によっても適切なカテゴリーを取得できます。
hierarchicalオプションについては説明が必要かもしれません。デフォルトで1に設定されていますが、0に設定して無効にできます。1に設定すると、hide_emptyが1に設定されている場合でも空カテゴリーを返す場合があります。とはいえ、表示されるのは空カテゴリーのうち空でない子カテゴリーを持つものだけです（これによりツリー全体を構築できます）。
さらにpad_countsもchild_ofもあります。さらに新しいオプションとしてparentもあります。これはchild_ofと似ていますが、parentは選択されたカテゴリーの直接の子カテゴリーのみを返す点で違います。直接の子カテゴリーがさらに子カテゴリーを持つ場合、それら（孫）は返されません。
投稿関連カテゴリーを取得する
1つの投稿に複数のカテゴリーを関連付けられます。get_the_category()を使えば、所定の投稿用に設定されたカテゴリーをすべて列挙する配列を取得できます。
デフォルトで、この関数は現在の投稿に関連したカテゴリーをすべて返します（ループ内でこの反応を有効にする必要があります）。パラメーターとして任意の投稿のIDを渡せば、その投稿に関連するカテゴリーを取得できます。
// Get the categories of the post with ID 139
$cats = get_the_category(139);
特定のデータを取得する
ときどき、カテゴリー名やIDなど特定の情報のみが必要な場合があります。このようなケースでは、一部の情報だけを得るためにオブジェクト全体を取得するのは無駄です。こうした特定の情報の取得に応える別の関数があります。
■カテゴリーIDを取得する
実装とおりであれば決して重複しないカテゴリーIDを記憶するより、カテゴリー名を記憶するほうが簡単です。幸い、カテゴリー名が分かっていればそのカテゴリーのIDを取得できます。get_cat_ID()関数を使って実現できます。この関数にカテゴリー名を渡すとそのカテゴリーのIDが返されます。カテゴリーが見つからなかった場合の戻り値は0です。
// Yes, I love this category
$cat_id = get_cat_ID('My goldfish');
すでにIDが分かっているカテゴリーの親カテゴリーのIDが分からない場合、get_ancestors()も使えます。この関数はもっとも近いものからもっとも遠いものまで、すべての「祖先」を格納する配列を返します。
例で説明すると、より分かりやすいでしょう。「My life」（ID：14）の子カテゴリーとして「My goldfish」（ID：15）があるとします。ここで「My goldfish」に子カテゴリー「The feed of my goldfish」（ID：16）を追加します。次のように記述すると、
$cats_id = get_ancestors(16, 'category');
以下のように返されます。
Array
(
[0] => 15
[1] => 14
)
ところで、get_ancestors()はカテゴリーを扱っていることを示す必要があります。なぜなら、この関数は一般的で、カテゴリー以外の分野にも対応しているからです。しかし、これはいま注目しているカテゴリー分野とは関係ありません。
■文字列を取得する
カテゴリー名からカテゴリーIDを取得できますが、get_cat_name()を使えばその逆もできます。
// Returns the name of the category with ID 15
$cat_name = get_cat_name(15);
カテゴリーの説明文についても、category_description()を使えば取得できます。
// Returns the description of the category with ID 15
$cat_desc = category_description(15);
ここまででカテゴリーのURLについて説明してこなかったことに気づいたでしょうか。実装（URLリライティングを使うかどうか）によってURLが変わる場合があるので、興味深いことです。率直に言って、先に説明したオブジェクトにURL情報が含まれていない理由は分かりません。しかし、get_category_link()を使えばカテゴリーのURLを取得できます。
// I want to display a link to my favorite category
$cat_id = get_cat_ID('My goldfish');
$cat_link = get_category_link($cat_id);
あとは正しいURLを格納した$cat_linkを使うだけです。
<a href="<?php echo $cat_link; ?>">My goldfish</a>
ショートリスト
WordPressのテーマを開発してきた人なら、おそらくthe_category()は知っているでしょう。この関数を使って現在の（または任意の）投稿に使用されているカテゴリーのリストを出力（echo）できます。リストは文字列で、すべてのリンクが順に希望の文字列（第1パラメータで指定）で区切って表示されます。
// Get a comma-separated list of the used categories
the_category(', ');
この関数の第3パラメーターは目的とする投稿のIDです。ループ内で使用しないなら、このパラメーターは必須です。第2パラメーターはとても特殊です。
第2パラメータは親カテゴリーと子カテゴリーの間のリンクの表示方法を管理するので、関係している投稿が親カテゴリーを持つカテゴリー内に存在している場合にのみ役立ちます。デフォルトではこのパラメーターに空の文字列が設定されていて、子カテゴリーだけが表示されます。パラメーターをsingleに変更すると、子カテゴリーの同一リンク内に親カテゴリーのカテゴリー名も表示されるようになります。multipleにも設定でき、親カテゴリーと子カテゴリーが2つのリンクに分かれて表示されます。
出力前に結果を変数に格納しておきたい場合、代わりにget_the_category_list()が使えます（使用法はthe_category()と同じです）。
最後に
カテゴリーAPIは包括的で、とても使い勝手の良い関数をたくさん搭載しています。カテゴリーについてなにが必要になっても、既存の関数を使える可能性が大です。
実際、もっとも一般的に使われている関数を選んで説明してきましたが、このAPIにはほかにも多くの関数が搭載されています。たとえば投稿がカテゴリー内にあるかどうかチェックする関数もあります。さらにカテゴリーごとのチェックボックスで構成されたリストを表示する関数もあります（管理画面で使うと便利です）。
（原文：Mastering the WordPress Categories API）
［翻訳：新岡祐佳子／編集：Livit］
