【WordPress】wp_localize_scriptの使い方|JavaScriptにPHPの値を渡す方法

WordPress

WordPressでJavaScriptを扱う際、PHPの値をそのまま渡したい場面は多くあります。AjaxのURLやセキュリティ用のnonce、テーマやプラグインの設定値などをフロント側に渡す方法として便利なのがwp_localize_scriptです。ここではその基本的な使い方と実用例を解説します。

スポンサーリンク

wp_localize_scriptとは

wp_localize_scriptは、PHPからJavaScriptにデータを渡すためのWordPress関数です。本来は翻訳用に作られた関数ですが、連想配列をJavaScriptオブジェクトとして出力できるため、スクリプトとサーバー側の値を橋渡しする用途に広く利用されています。

基本的な書き方

まずはテーマやプラグインのfunctions.phpでスクリプトを登録し、その後にwp_localize_scriptでデータを渡します。

functions.php:スクリプトとPHPの値の受け渡し
<?php
function my_enqueue_scripts() {
  // JSファイルを読み込み
  wp_enqueue_script(
    'my-script',
    get_template_directory_uri() . '/assets/js/my-script.js',
    ['jquery'],
    '1.0.0',
    true
  );

  // PHPの値を渡す
  wp_localize_script('my-script', 'MyData', [
    'ajaxUrl' => admin_url('admin-ajax.php'),
    'nonce'   => wp_create_nonce('my_nonce'),
    'message' => 'こんにちは、JavaScript!'
  ]);
}
add_action('wp_enqueue_scripts', 'my_enqueue_scripts');

上記のコードにより、JavaScript側では以下のようにアクセスできます。

JavaScript:渡された値の参照
console.log(MyData.ajaxUrl); // Ajax送信先URL
console.log(MyData.nonce);   // セキュリティ用nonce
console.log(MyData.message); // 任意の文字列

Ajaxでの利用例

フロントエンドからAjax通信を行う際に、admin-ajax.phpのURLやnonceを渡すのが定番の使い方です。

my-script.js:Ajax送信
// my-script.js
jQuery(function($) {
  $('#send').on('click', function() {
    $.post(MyData.ajaxUrl, {
      action: 'my_action',
      _ajax_nonce: MyData.nonce,
      value: 'テスト送信'
    }, function(response) {
      alert(response);
    });
  });
});

サーバー側ではAjaxフックを登録して処理を記述します。

functions.php:Ajaxハンドラー
<?php
function my_ajax_handler() {
  check_ajax_referer('my_nonce');

  $value = sanitize_text_field($_POST['value']);
  wp_send_json_success("受け取った値: " . $value);
}
add_action('wp_ajax_my_action', 'my_ajax_handler');
add_action('wp_ajax_nopriv_my_action', 'my_ajax_handler');

複数のデータをまとめて渡す

連想配列にまとめて定義すれば、複数の値を一度に渡すことができます。URLやテキスト、設定値などを整理して渡すのがおすすめです。

functions.php:複数データの受け渡し
wp_localize_script('my-script', 'MyData', [
  'endpoints' => [
    'ajax' => admin_url('admin-ajax.php'),
    'rest' => esc_url(rest_url())
  ],
  'user' => [
    'id'   => get_current_user_id(),
    'name' => wp_get_current_user()->display_name
  ],
  'settings' => [
    'themeColor' => '#02a1cd'
  ]
]);

注意点

  • wp_enqueue_scriptで登録したスクリプトのハンドル名を正しく指定する必要があります
  • wp_localize_scriptは必ずwp_enqueue_scriptの後に呼び出してください
  • 出力されるのはグローバル変数になるため、名前の衝突を避けるためにユニークなオブジェクト名を付けるのが望ましい
値の型はトップレベルと配列の中で異なる
wp_localize_scriptは、トップレベルの値だけを文字列に変換して渡します。たとえば'count' => 5は"5"、'flag' => trueは"1"、falseは空文字になります。一方、配列の中にネストした値('user' => ['id' => 5]など)は型が保たれ、数値のまま渡されます。JavaScript側で数値や真偽値を扱う際は、この違いを意識して判定や変換を行ってください。

よくある質問(FAQ)

Qwp_localize_scriptでオブジェクトを渡す場合の注意点は?
Aトップレベルの値は文字列に変換されて渡されます(真偽値trueは”1″、falseは空文字)。配列の中にネストした値は型が保たれます。数値や真偽値をJavaScript側で扱う際は、トップレベルの値であればparseInt()などで変換し、必要に応じて配列にまとめて渡す設計を検討してください。
Qwp_localize_scriptはどのタイミングで呼び出す必要がありますか?
Awp_enqueue_scriptで対象スクリプトを登録した後、wp_enqueue_scriptsフック内で呼び出してください。スクリプト登録前に呼ぶと機能しません。
Qwp_localize_scriptのデータをセキュアに渡すには?
Aユーザー入力由来の値はesc_html()やintval()でサニタイズしてから渡してください。nonce(wp_create_nonce())を含めてAJAX通信の認証に使うことが推奨です。

まとめ

wp_localize_scriptを使えば、PHPからJavaScriptへ値を安全かつ簡単に渡せます。特にAjax処理やテーマ設定のフロント反映などで役立つため、WordPressでのフロントエンド開発には欠かせないテクニックです。親オブジェクト名を工夫し、必要なデータだけを渡す設計を心がけると、より保守性の高いコードになります。