WordPress 4.4のterm metaは分類項目へ追加dataを保存する

WordPress 4.4では、カテゴリー、タグ、独自taxonomyのtermへ追加dataを保存できます。追加はadd_term_meta()、取得はget_term_meta()、変更はupdate_term_meta()、削除はdelete_term_meta()を使います。

ただし、分類名や説明として保存できる内容を、何でもmetaへ逃がさないでください。dataの意味、値の型、削除条件、既存pluginとの重複を決めてから実装します。

termとterm metaの役割を分ける

WordPress 4.4のtaxonomy変更に関する開発資料では、termへ任意のdataを保存するterm meta APIが導入されています。

termは「お知らせ」「製品」などの分類項目です。term metaは、その分類項目に追加する値です。たとえば、カテゴリーごとの代表画像ID、表示色の識別子、外部systemで使うcodeなどが候補になります。

次は、カテゴリーの代表画像IDを保存して読む説明用の仮例です。

$term_id  = 42;
$image_id = 123;

update_term_meta( $term_id, 'category_image_id', $image_id );

$saved_image_id = get_term_meta(
    $term_id,
    'category_image_id',
    true
);

画像URLではなくattachment IDを保存すれば、表示時にWordPressの画像情報を取得できます。ただし、外部画像を使う要件なら同じ設計にはなりません。保存する値は、後から何へ結び付けるかで決めます。

仮例の42や123は、実サイトの値ではありません。実装では、保存する前に対象のtermと画像が存在するかを確認し、他のtaxonomyのtermや使えない値をそのまま受け取らないようにします。画像を削除した後も古いIDが残る場合に、画面で何を表示するかも決めます。値を保存できることと、存在しない値を扱えることは別です。

追加と更新を使い分ける

add_term_meta()は、新しいmetaを追加します。第四引数をtrueにすると、同じkeyを一つだけに制限できます。

$result = add_term_meta(
    $term_id,
    'category_image_id',
    $image_id,
    true
);

既存値を新しい値へ置き換える用途なら、update_term_meta()を使います。同じkeyに複数値を持たせるのか、一つの正本だけを持たせるのかを先に決めてください。

get_term_meta()の第三引数をtrueにすると、指定keyの単一値を返します。falseなら値の配列です。保存方針と取得方法がずれると、数値を期待した場所へ配列が渡るため、code reviewでは引数まで確認します。

不要になった値はdelete_term_meta()で削除します。term自体を削除することと、termへ付けた一つのmetaを削除することは別の操作です。

meta keyと値の仕様をsite側で持つ

meta keyは、pluginやthemeのほかの機能と衝突しにくい名前にします。一般名のcolorやimageだけにせず、機能を示すprefixと意味を含めます。

一つのmetaごとに、次を記録してください。

保存APIだけを実装しても、管理画面の入力、権限、validation、escapeは自動では決まりません。入力値を保存前に検証し、表示する場所に合う方法でescapeします。

既存のterm meta実装と衝突しないか調べる

WordPress 4.4より前から、pluginや独自codeでterm metadataを実装しているsiteがあります。既存実装の移行に関するWordPress Core資料は、function名とdatabase tableの衝突を確認するよう案内しています。

更新前に、次の文字列をpluginとthemeから検索します。

add_term_meta
get_term_meta
update_term_meta
delete_term_meta
termmeta
term_meta

独自codeがprefixなしで同名functionを定義していれば、WordPress Coreのfunctionと衝突する可能性があります。wp_termmeta相当のtableをplugin停止時に削除する処理も確認してください。Coreが使うdataをpluginの都合で消してはいけません。

既存pluginが別tableへ保存している場合は、Coreのterm metaへ自動で移るとは限りません。旧data、新data、移行script、戻し方を分け、backupを取ってから少数のtermで試します。

meta_queryは検索条件と表示目的を決めてから使う

WordPress 4.4では、get_terms()とwp_get_object_terms()でmeta_queryを使えます。term metaを条件に分類項目を絞り込めます。

便利だからという理由で、すべての一覧をmeta検索へ変えないでください。何件のtermから何を探すのか、通常のtaxonomy設計で表せないのか、結果をどこへ表示するのかを先に決めます。

制作会社やplugin開発者へ委託する場合は、meta key一覧、値の型、対象taxonomy、入力画面、移行方法、削除処理、backupを引き渡し条件にします。codeを任せても、追加dataの意味と保持期間を決める責任はsite側に残ります。

最初の一手は、pluginとthemeからtermmeta、term_meta、四つのAPI function名を検索することです。既存実装がなければ、追加したいdataを一件だけ選び、key、型、対象taxonomy、削除条件を決めてから試してください。