add_post_meta()

add_post_meta() は、WordPress の投稿（カスタム投稿タイプを含む）にメタデータを追加する関数です。

メタデータとは、投稿に紐づく追加情報のことで、カスタムフィールドとして活用されます。例えば、記事に「閲覧回数」「カスタムタグ」「著者の補足情報」などを保存したい場合に使用します。投稿の詳細な情報を保存・管理するために不可欠な関数です。

機能の説明

add_post_meta() は、特定の投稿に対してカスタムフィールド（メタデータ）を追加します。以下のようなケースで利用されます。

主な用途

• 投稿にカスタムデータを追加する
• カスタムフィールドを手動で管理する
• 投稿ごとに異なる情報を保存・取得する

この関数を使うことで、独自のメタデータを保存し、テーマやプラグイン内で活用できます。

シンプルなコード例

add_post_meta(123, 'view_count', 1, true);

• 123：投稿 ID（この投稿にメタデータを追加する）
• 'view_count'：メタキー（保存するデータの名前）
• 1：メタ値（保存するデータ）
• true：ユニークなメタデータかどうか（true なら既存の同じキーがない場合のみ追加）

このコードは、投稿 ID 123 に view_count というメタデータを 1 という値で追加します。

引数と戻り値

使い方の説明

基本的な使い方

以下のコードは、投稿に custom_field というメタデータを追加します。

function add_custom_meta_data($post_id) {
    if (!add_post_meta($post_id, 'custom_field', 'カスタムデータ', true)) {
        update_post_meta($post_id, 'custom_field', 'カスタムデータ');
    }
}
add_action('save_post', 'add_custom_meta_data');

• add_post_meta() を使って custom_field というメタデータを追加
• もし既に custom_field が存在していた場合は update_post_meta() で値を更新
• save_post フックを使って、投稿の保存時に実行

複数のメタデータを追加する

false を指定すると、同じキーのメタデータを複数追加できます。

add_post_meta(123, 'related_article', '456', false);
add_post_meta(123, 'related_article', '789', false);

この場合、投稿 ID 123 に related_article というキーのデータが 2 つ追加されます。

一緒に使うことが多い関連タグ

get_post_meta()

メタデータを取得する。

$view_count = get_post_meta(123, 'view_count', true);
echo '閲覧回数: ' . $view_count;

update_post_meta()

既存のメタデータを更新する。

update_post_meta(123, 'view_count', 2);

delete_post_meta()

メタデータを削除する。

delete_post_meta(123, 'view_count');

追加情報で取得したい場合

すべてのメタデータを取得する

get_post_meta() の第三引数を false にすると、同じキーを持つすべてのメタデータが取得できます。

$meta_values = get_post_meta(123, 'related_article', false);
print_r($meta_values);

出力例

Array (
    [0] => 456
    [1] => 789
)

想定されるトラブル

メタデータが追加されない

解決方法

• 投稿 ID が正しいか確認する
• true を指定した場合、同じキーが既に存在していると追加されない（false に変更するか update_post_meta() を使う）

メタデータが意図せず複数追加される

解決方法

• true を指定して add_post_meta() を使う
• update_post_meta() を使用して既存データを更新する

Q＆A

$tags = array('PHP', 'WordPress', 'Meta');
add_post_meta(123, 'custom_tags', $tags, true);

update_post_meta(123, 'view_count', 5);

delete_post_meta_by_key('view_count');

まとめ

add_post_meta() は、投稿にカスタムデータを追加するための便利な関数です。

get_post_meta() や update_post_meta() などと組み合わせて、投稿ごとのメタ情報を柔軟に管理できます。データの追加・取得・更新・削除を適切に使い分けることで、WordPress の投稿をよりカスタマイズしやすくなります。