関数リファレンス/wp nonce field

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

解説

フォームへ hidden フィールドとして追加するために nonce を取得または表示します。

nonce フィールドは、フォームの内容が現在のサイトから来たものであり、他のサイトからではないということを認証するために使われます。nonce は完全な保護を提供するものではありませんが、ほとんどの場合に有効な保護になります。フォーム内で nonce フィールドを使うのはとても重要です。

$action と $name はオプションですが、セキュリティを高めたければこの 2 つのパラメータを設定することを強く推奨します。nonce のセキュリティ方式はパラメータが必須ではないので、パラメータなしで関数を呼び出すのは簡単ですが、デフォルト値が何かを知っているクラッカーがあなたの nonce を推測して被害を与えるのが簡単になってしまいます。

input 要素の name 属性は $name に設定した値になり、value 属性は wp_create_nonce() 関数を使って生成された nonce の値になります。

使い方

<?php wp_nonce_field( $action, $name, $referer, $echo ) ?>

パラメータ

$action

（文字列） （オプション） アクションの名前。実行中のコンテキストを与えてください。オプションですが推奨します。

初期値： -1

$name

（文字列） （オプション） nonce の名前。作成される hidden フィールドの name 属性になります。フォームが送信されると、生成された nonce 値を $_POST[$name] で参照できます。

初期値： '_wpnonce'

$referer

（真偽値） （オプション） wp_referer_field() 関数を使って、リファラーを表す hidden フィールドを生成するかどうか。

初期値： true

$echo

（真偽値） （オプション） hidden フィールドを表示する（true）か値として返す（false）か。nonce の hidden フィールドと、$referer が true ならリファラーの hidden フィールドも含まれます。

初期値： true

戻り値

(文字列) 

$echo が ture の場合のみ。nonce の hidden フォームフィールドと、$referer が true ならリファラーの hidden フィールドも含まれます。

例

これは、後の例よりセキュリティは低いですが、すべての引数を省略した一番シンプルな実装です。フォームに次の内容を含めます：

    <?php wp_nonce_field(); ?>

フォーム内でアクションと nonce に名前をつけるとよいでしょう。1 番目と 2 番目の引数に値を入れて、必要な hidden フィールドを表示します：

<form method="post">
    <!-- some inputs here ... -->
    <?php wp_nonce_field( 'アクションの名前', 'nonce フィールドの名前' ); ?>
</form>

フォームが送信された先のページで、wp_verify_nonce() 関数を使ってそれを認証できます。注意: nonce は自分でコードを書いて取得する必要があります（この例では $_POST 配列から）。また、アクションの名前は先頭ではなく 2 番目のパラメータにします：

<?php
if ( 
    ! isset( $_POST['nonce フィールドの名前'] ) 
    || ! wp_verify_nonce( $_POST['nonce フィールドの名前'], 'アクションの名前' ) 
) {
    print 'ごめんなさい、nonce を認証できませんでした。';
    exit;
} else {
    // フォームのデータを処理する
}

WordPress の管理画面内でフォームを送信して処理する場合は、check_admin_referer() 関数を使って nonce を認証します：

<?php
// 失敗すると check_admin_referer() は自動的に "failed" ページを表示して終了 (die) します。
if ( ! empty( $_POST ) && check_admin_referer( 'アクションの名前', 'nonce フィールドの名前' ) ) {
    // フォームのデータを処理する
}

参考

$echo を falseに、$referer を trueにした場合は、wp_referer_field() を使ってリファラーのフィールドを取得する必要があります。$echo を true にして nonce フィールドを出力した場合は、リファラーフィールドも出力されます。

変更履歴

• 2.0.4 : 新規導入

ソースファイル

wp_nonce_field() は wp-includes/functions.php にあります。

関連項目

WordPress Nonce

Nonce関数: wp_explain_nonce() /en, wp_nonce_ays() /en, wp_nonce_field(), wp_nonce_url(), wp_verify_nonce(), wp_create_nonce() /en, check_admin_referer() /en, check_ajax_referer() /en, wp_referer_field() /en

外部リソース

• Mark Jaquith - WordPress Nonces
• Vladimir Prelovac - Using Nonces in WordPress Plugins
• Wikipedia: ノンス

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

最新英語版： WordPress Codex » Function Reference/wp_nonce_field （最新版との差分）