関数リファレンス/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 （最新版との差分）