1. ホーム
  2. WordPress

【WordPress】wp_localize_script でPHPの値をJavaScriptに渡す方法

Share

WordPress でテーマやプラグインに JavaScript を組み込むとき、「PHP 側で持っている値を JavaScript に渡したい」という場面がよくあります。たとえば Ajax の送信先 URL やセキュリティ用のトークン、現在の投稿 ID などです。こうした値を安全に渡す仕組みが wp_localize_script() です。この記事では、その使い方と仕組みを初心者の方にも分かるように解説します。

wp_localize_script() とは

wp_localize_script() は、PHP の値を JavaScript から参照できるグローバル変数として出力する関数です。指定したオブジェクト名で、PHP の連想配列が JavaScript のオブジェクトとして書き出されます。

名前に「localize（ローカライズ＝翻訳・地域化）」とあるとおり、もともとは JavaScript 内の文字列を翻訳するための関数でした。しかし実際には、URL やナンス（後述するセキュリティ用トークン）などあらゆる値を JavaScript に受け渡す用途で広く使われています。

基本の使い方

wp_localize_script() は、必ず wp_enqueue_script() で読み込んだスクリプトに対して使います。3 つの引数を渡します。

引数意味
第1引数値を渡す対象スクリプトのハンドル名（wp_enqueue_script() で付けた名前）
第2引数JavaScript 側で使うオブジェクト名（グローバル変数名）
第3引数渡したい値をまとめた連想配列

実際に、functions.php でスクリプトを読み込み、そこへ値を渡してみましょう。

functions.php
function mytheme_enqueue_scripts() {
    // まずスクリプトを読み込む（ハンドル名は 'mytheme-main'）
    wp_enqueue_script(
        'mytheme-main',
        get_theme_file_uri( '/js/main.js' ),
        array(),
        '1.0.0',
        true
    );

    // そのスクリプトに値を渡す
    wp_localize_script(
        'mytheme-main',   // 対象スクリプトのハンドル名
        'myData',         // JavaScript 側のオブジェクト名
        array(
            'ajaxUrl' => admin_url( 'admin-ajax.php' ),
            'siteName' => get_bloginfo( 'name' ),
        )
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

これで、main.js の中から myData というオブジェクトを通して値を参照できます。

js/main.js
console.log(myData.ajaxUrl);  // 例: https://example.com/wp-admin/admin-ajax.php
console.log(myData.siteName); // 例: My WordPress Site

実際に出力される HTML

裏側で何が起きているのかを知っておくと理解が深まります。wp_localize_script() は、対象スクリプトが読み込まれる直前に、次のような <script> タグをページに出力します。

出力されるHTML
<script id="mytheme-main-js-extra">
var myData = {"ajaxUrl":"https:\/\/example.com\/wp-admin\/admin-ajax.php","siteName":"My WordPress Site"};
</script>

PHP の連想配列が、JavaScript のオブジェクトを表す変数定義として書き出されているのが分かります。だからこそ、後から読み込まれる main.js がこの変数を参照できるわけです。

Ajax のナンス（セキュリティトークン）を渡す

もっとも多い使い道のひとつが、Ajax 通信用のナンスを渡すことです。ナンスとは、なりすましリクエストを防ぐためにWordPress が発行する使い捨てのトークンです。サーバー側で検証することで、正規のページから送られたリクエストかどうかを確認できます。

functions.php
wp_localize_script(
    'mytheme-main',
    'myData',
    array(
        'ajaxUrl' => admin_url( 'admin-ajax.php' ),
        // Ajax 検証用のナンスを発行して渡す
        'nonce'   => wp_create_nonce( 'mytheme_ajax' ),
    )
);

JavaScript 側では、受け取った myData.nonce をリクエストに添えて送信します。サーバー側では check_ajax_referer() などで検証します。

js/main.js
const body = new URLSearchParams({
  action: 'mytheme_save',
  nonce: myData.nonce, // 受け取ったナンスを添える
});

fetch(myData.ajaxUrl, { method: 'POST', body })
  .then((res) => res.json())
  .then((data) => console.log(data));

値が undefined になるときに確認すること

ハンドル名が一致していない

第 1 引数のハンドル名は、wp_enqueue_script()（または wp_register_script()）で指定したものと完全に一致している必要があります。ここが食い違っていると、値を出力する <script> タグが書き出されず、JavaScript 側でオブジェクトが undefined になります。タイプミスがないか見直してみましょう。

そのスクリプトが実際に読み込まれていない

wp_localize_script() が出力する変数定義は、対象スクリプトが enqueue（実際にページへ出力）されて初めてページに現れます。条件分岐などで対象スクリプトが読み込まれていないページでは、当然この値も出力されません。値を使いたいページでスクリプトが読み込まれているかを確認してください。

参照のタイミングが早すぎる

変数定義は、対象スクリプト本体の直前に出力されます。そのため、対象スクリプトの中から参照する分には問題ありません。ただし、それより前に読み込まれる別のスクリプトから参照しようとすると、まだ変数が定義されておらず undefined になります。値を使う側のスクリプトに対して wp_localize_script() を呼ぶようにしましょう。

まとめ

wp_localize_script() は、PHP の値を JavaScript に安全に渡すための定番の方法です。要点を振り返ります。

  • 第1引数は wp_enqueue_script() のハンドル名と一致させる
  • 第2引数のオブジェクト名を通して、JavaScript から値を参照できる
  • Ajax の URL やナンスを渡す用途で特によく使われる

テーマやプラグインで JavaScript を扱うなら避けて通れない関数なので、ここでしっかり押さえておきましょう。

参考ページ