• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/add post meta

提供: WordPress Codex 日本語版
移動先: 案内検索

この項目「関数リファレンス/add post meta」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

add_post_meta() は、指定した投稿や固定ページへカスタムフィールド(「メタデータ」とも呼ばれます)を追加します。どんな投稿タイプの投稿でも構いません。ひとつのカスタムフィールドは、実際にはキーと値の組です。

$unique パラメータに true を指定しており、そのキーが既に存在している場合、この関数は何もしないで false を返します。それ以外の場合は、同じキーでカスタムフィールドを追加して true を返します。すでに存在しているカスタムフィールドの値を更新したいときは、代わりに update_post_meta() を使ってください。

使い方

<?php add_post_meta( $post_id, $meta_key, $meta_value, $unique ); ?>

パラメータ

$post_id
整数) (必須) カスタムフィールドを追加する投稿の ID。
初期値: なし
$meta_key
文字列) (必須) カスタムフィールドのキー。
初期値: なし
$meta_value
mixed) (必須) カスタムフィールドの値。配列を与えるとシリアライズされて文字列が格納されます。
初期値: なし
$unique
真偽値) (オプション) キーをユニークにするかどうか。true のときは、指定した投稿に $meta_key を持つカスタムフィールドが無いときのみ追加し、すでにカスタムフィールドが存在していれば追加されません。
初期値: false

戻り値

(真偽値|整数) 
成功すると、追加された行(カスタムフィールド)の ID を返します。これは true として判定できます。$unique 引数が true で、指定されたキーを持つカスタムフィールドが既にあると、false を返します。

用例

デフォルトの使い方

ID が 68 の投稿に、キーが my_key で値が 47 のカスタムフィールドを追加します。

<?php add_post_meta( 68, 'my_key', 47 ); ?>

参考: 既に my_key というキーを持つカスタムフィールドが存在していても追加します。

ユニークなカスタムフィールドの追加または更新

キーが存在しない場合は新しくカスタムフィールドを追加し、キーが存在する場合はカスタムフィールドを更新します。

<?php
if ( ! add_post_meta( 7, 'fruit', 'banana', true ) ) { 
   update_post_meta ( 7, 'fruit', 'banana' );
}

その他の例

my_key というキーを持つカスタムフィールドが存在しないときだけ追加する:

<?php add_post_meta( 68, 'my_key', '47', true ); ?>

my_key というキーを持つカスタムフィールドを複数追加する:

<?php add_post_meta( 68, 'my_key', '47' ); ?>
<?php add_post_meta( 68, 'my_key', '682' ); ?>
<?php add_post_meta( 68, 'my_key', 'The quick, brown fox jumped over the lazy dog.' ); ?>
...

さらに詳しい例は post_meta 関数の例 を見てください。

見えない カスタムフィールドを作る

プラグインやテーマの開発者なら、カスタムフィールドをプラグインやテーマ用のパラメータを保存するために使いたいことがあるかもしれません。"_"(アンダースコア)で始まるキーを持つカスタムフィールドは、投稿や固定ページの編集画面に表示されず、the_meta() では取得されないので、そのような内部的な 見えない パラメータを扱うのに適しています。

以下の例は、キーが _color で値が red のユニークなカスタムフィールドを追加しますが、投稿や固定ページの編集画面には表示されません。

<?php add_post_meta(68, '_color', 'red', true); ?>

隠された配列

さらに、$meta_value 引数が配列だった場合、キー名がアンダースコアで始まらなくても投稿や固定ページの編集画面に表示されません。

参考

文字のエスケープ

カスタムフィールドの値は stripslashes() 関数を通して渡されるので、「\」(バックスラッシュ)でエスケープされたコンテンツについて注意する必要があります。この動作内容と、対応方法の例については、update_post_meta() の説明をご覧ください。

ソースコード

add_post_meta()wp-includes/post.php にあります。

更新履歴

新規導入: 1.5.0


カスタムフィールド: the_meta(), get_post_meta(), add_post_meta(), update_post_meta(), delete_post_meta(), get_post_custom(), get_post_custom_values(), get_post_custom_keys() (post_meta 関数の例 /en も参照)


関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/add post meta最新版との差分