add_post_meta() の使い方｜説明・引数・注意点

説明

基本構文

add_post_meta( int $post_id, string $meta_key, mixed $meta_value, bool $unique = false ): int|false

引数

• $post_id：投稿ID
• $meta_key：メタキー
• $meta_value：値
• $unique：true で同じキーの重複登録を防ぐ

戻り値

成功すればメタID、失敗すれば false。

使い方（サンプル）

add_post_meta( 123, 'tag_color', 'blue', true );

注意点

• 同じキーを複数登録できます。重複させたくないときは $unique を true にします。
• 既存の値を置き換えたいときは update_post_meta() を使います。

実務での使いどころ

• 同じキーに、複数の値を持たせたいとき（タグのような複数の値）。
• すでにキーがあっても、別の値を追加したいとき。

よくあるミスと対処

• 1つの値を保存するつもりで、繰り返し呼び、同じキーの行が増えていく。1つの値なら、update_post_meta() を使う。
• $unique を指定していない。既定の false では、同じキーが重複して追加される。
• 戻り値を確認していない。

NG例

add_post_meta( $post_id, 'price', 1000 ); // 呼ぶたびに、行が増える

OK例

update_post_meta( $post_id, 'price', 1000 );
// または、重複を防ぐ
add_post_meta( $post_id, 'price', 1000, true );

使い分け早見表

関連項目

update_post_meta()、get_post_meta()

公式リファレンス：add_post_meta() | Function | WordPress Developer Resources