万が一、当サイトで重大な問題を発見した際などは、フォーラムや WordSlack #docs チャンネルでお知らせください。</p>
関数リファレンス/update post meta
この項目「関数リファレンス/update post meta」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。
目次
説明
update_post_meta() は、指定した投稿に存在するカスタムフィールドの値を更新します。add_post_meta() の代わりとしても使うことができます。この関数はまず、$post_id で ID を指定した投稿に $meta_key を持つカスタムフィールドが存在することを確認します。もし存在しなければ代わりに add_post_meta( $post_id, $meta_key, $meta_value )
を実行し、その結果を返します。
注意: もしデータベースの照合順序が大文字小文字を区別しない(照合順序名に _ci が付く)場合、update_post_meta()、delete_post_meta()、get_posts() は、大文字と小文字のキーを区別せずにレコードを更新・削除・クエリします。しかし get_post_meta() は大文字・小文字を区別する場合があります。これは WordPress のキャッシュ によるものです。詳しくは https://core.trac.wordpress.org/ticket/18210 を参照してください。大文字・小文字を混ぜないよう、気をつけてください。
使い方
<?php update_post_meta( $post_id, $meta_key, $meta_value, $prev_value ); ?>
パラメータ
- $post_id
- (整数) (必須) 更新したいカスタムフィールドを持つ投稿の ID。
- 初期値: なし
- $meta_key
- (文字列) (必須) 更新したいカスタムフィールドのキー。これは生の値でなければなりません(データベースクエリ時は無害化されます)。
- 初期値: なし
- $meta_value
- (mixed) (必須) カスタムフィールドの新しい値。配列を与えるとシリアル化されます。これは生の値でなければなりません(データベースクエリ時は無害化されます)。
- 初期値: なし
- $prev_value
- (mixed) (オプション) 更新したいカスタムフィールドの元の値。これは、同じキーを持つカスタムフィールドを区別するパラメータです。省略すると、指定したキーを持つカスタムフィールドはすべて値が更新されます。
- 初期値: ''
戻り値
- (mixed)
- カスタムフィールドが存在しなければ meta_id を返します(true と判定できます)。それ以外の場合、成功すれば true、失敗すれば false を返します。また、与えられた値がすでにデータベースにある値と一致したときも false を返します。
用例
デフォルトの使い方
ID が76の投稿で、キーが my_key のカスタムフィールドの値を Steve に変更します。
<?php update_post_meta(76, 'my_key', 'Steve'); ?>
その他の例
ID が 76 の投稿に、以下の 4 つのカスタムフィールドがある場合:
[key_1] => 'Happy'
[key_1] => 'Sad'
[key_2] => 'Gregory'
[my_key] => 'Steve'
key_2 のキーを持つカスタムフィールドの値を Hans に変更するには:
<?php update_post_meta( 76, 'key_2', 'Hans' ); ?>
key_1 のキーを持つカスタムフィールドで値を Sad から Warm に変更するには:
<?php update_post_meta( 76, 'key_1', 'Warm', 'Sad' ); ?>
この結果、カスタムフィールドは以下のようになります:
[key_1] => 'Happy'
[key_1] => 'Warm'
[key_2] => 'Hans'
[my_key] => 'Steve'
注: この関数は、条件に一致するすべてのカスタムフィールドを変更します。
最初の key_1 のキーを持つカスタムフィールドの値を Happy から Excited に変更するには:
<?php update_post_meta( 76, 'key_1', 'Excited', 'Happy' ); // または update_post_meta( 76, 'key_1', 'Excited' ); // キー "key_1" を持つすべてのフィールドを更新するには: $key1_values = get_post_custom_values( 'key_1', 76 ); foreach ( $key1_values as $value ) update_post_meta( 76, 'key_1', 'Excited', $value ); ?>
さらに詳しい例は post_meta 関数の例 を見てください。
文字のエスケープ
カスタムフィールドの値は stripslashes() 関数を通してから保存されるので、エスケープ文字「\」を含む値を渡すときは注意が必要です(例えば JSON)。
エスケープした値が保存されない
JSON の値が {"key":"value with \"escaped quotes\""} である場合:
<?php $escaped_json = '{"key":"value with \\"escaped quotes\\""}'; update_post_meta( $id, 'escaped_json', $escaped_json ); $broken = get_post_meta( $id, 'escaped_json', true ); /* $broken が stripslashes() を通されてパースできなくなる: {"key":"value with "escaped quotes""} */ ?>
回避方法
関数 wp_slash()(WordPress 3.6 で導入)を使って「\」によるエスケープを 1 レベル増やすことにより、stripslashes() の呼び出しを相殺できます:
<?php $escaped_json = '{"key":"value with \\"escaped quotes\\""}'; update_post_meta( $id, 'double_escaped_json', wp_slash( $escaped_json ) ); $fixed = get_post_meta( $id, 'double_escaped_json', true ); /* $fixed は stripslashes() の後に、思ったとおり保存される: {"key":"value with \"escaped quotes\""} */ ?>
参考
- この関数は update_metadata() /en を使用します。
ソースコード
update_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/update post meta (最新版との差分)