☰
WORDPRESS / PRACTICE

Надёжная передача конфигурации в JavaScript WordPress

Надёжная передача конфигурации в JavaScript WordPress

Ошибки вроде `undefined is not a function`, отсутствие nonce или нестабильная работа после оптимизации JavaScript часто возникают не из-за самого кода, а из-за неправильного порядка его выполнения. Скрипт может запуститься раньше зависимости или попытаться прочитать конфигурацию, которой ещё нет на странице.

В WordPress эту проблему решают два правила: зависимости нужно регистрировать явно, а данные для JavaScript — добавлять к конкретному script handle через API WordPress. Такой подход лучше работает с Gutenberg, WooCommerce, кэшированием, объединением файлов и отложенной загрузкой.

Почему порядок выполнения JavaScript в WordPress имеет значение

Браузер выполняет JavaScript в определённой последовательности. Если `checkout.js` использует `wp.apiFetch`, но файл с этим объектом ещё не загружен, в консоли появится ошибка. Аналогичная ситуация возникает, когда основной скрипт ожидает `window.checkoutConfig`, а переменная объявляется позже или вообще не выводится.

Дополнительные риски создают оптимизаторы: они могут объединять файлы, изменять способ загрузки, добавлять `defer` или откладывать выполнение. Если зависимость и конфигурация не описаны через механизмы WordPress, оптимизация может изменить порядок, на который рассчитывал разработчик.

  • зависимость загружается после скрипта, который её использует;
  • конфигурация появляется в глобальной области случайно или имеет конфликтующее имя;
  • один handle регистрируется несколько раз с разными файлами или версиями;
  • inline-код добавляется на страницу отдельно и теряет связь с основным скриптом.

Регистрируйте зависимости через wp_enqueue_script

В массиве зависимостей нужно указать handles скриптов, которые должны быть доступны раньше. WordPress использует эту информацию, чтобы построить порядок подключения. Не полагайтесь на то, что нужный файл уже добавила тема или другой плагин: это может измениться после обновления или в другом шаблоне страницы.

Сначала зарегистрируйте или поставьте в очередь основной файл. В примере `checkout-app` зависит от `wp-api-fetch`, поэтому WordPress выведет API Fetch перед кодом приложения.

  • Используйте стабильный уникальный handle, например `my-plugin-checkout`.
  • Указывайте реальные handles, а не названия файлов. Handle `api-fetch.js` и handle `wp-api-fetch` — не одно и то же.
  • Передавайте версию скрипта для корректного обновления кэша после изменений.
  • Подключайте файл в нужном контексте — только на страницах, где он действительно нужен.
<?php
wp_enqueue_script(
    'checkout-app',
    plugin_dir_url(__FILE__) . 'assets/checkout.js',
    array('wp-api-fetch'),
    '1.0.0',
    array('in_footer' => true)
);

Передавайте конфигурацию через wp_add_inline_script

`wp_add_inline_script()` связывает добавленный код с конкретным handle. Если использовать позицию `before`, конфигурация будет выведена перед основным файлом. Это правильный вариант, когда `checkout.js` читает данные сразу при выполнении.

Название параметра `before` важно: оно означает «перед связанным скриптом», а не после вызова PHP-функции. Если конфигурация нужна только после завершения основного файла, можно использовать `after`, но для начальных настроек это часто слишком поздно.

  • Добавляйте inline-код после регистрации или постановки handle в очередь.
  • Привязывайте конфигурацию именно к тому handle, который её использует.
  • Не создавайте десятки независимых глобальных переменных — используйте одно пространство имён.
  • Не передавайте через браузер секретные ключи, пароли или приватные токены.
<?php
$config = array(
    'nonce'    => wp_create_nonce('wp_rest'),
    'currency' => function_exists('get_woocommerce_currency')
        ? get_woocommerce_currency()
        : 'USD',
);

wp_add_inline_script(
    'checkout-app',
    'window.checkoutConfig = ' . wp_json_encode($config) . ';',
    'before'
);

Безопасно сериализуйте данные с помощью wp_json_encode

Не вставляйте значения PHP в JavaScript конкатенацией без кодирования. Строки могут содержать кавычки, переносы, специальные символы или значения, которые изменят синтаксис скрипта. `wp_json_encode()` преобразует PHP-массив в корректный JSON, который браузер может прочитать как JavaScript-объект.

Перед передачей данных проверяйте их состав. Конфигурация для фронтенда доступна пользователю страницы, поэтому nonce, URL REST API, валюта, идентификаторы товаров или публичные настройки — это одно, а секретный API-ключ — совсем другое.

  • Формируйте конфигурацию как массив PHP, а не как готовую строку JavaScript.
  • Проверяйте функции и зависимости плагинов, если код может выполняться без WooCommerce.
  • Не используйте `esc_js()` как замену JSON-сериализации массива.
  • Для вложенных структур также передавайте массив в `wp_json_encode()` — он сохранит вложенные объекты и списки.
<?php
$config = array(
    'restUrl'  => esc_url_raw(rest_url('my-plugin/v1/')), 
    'currency' => 'UAH',
    'features' => array(
        'guestCheckout' => true,
        'coupons'       => false,
    ),
);

wp_add_inline_script(
    'checkout-app',
    'window.MyPlugin = window.MyPlugin || {};'
        . 'window.MyPlugin.checkout = ' . wp_json_encode($config) . ';',
    'before'
);

Как читать конфигурацию в файле JavaScript

Основной файл должен ожидать согласованную структуру данных и не прекращать работу полностью, если необязательное поле отсутствует. Проверяйте объект перед использованием, особенно если некоторые страницы могут загружаться без нужного плагина.

Глобальная переменная допустима для небольшой конфигурации, но лучше использовать уникальное пространство имён. Так снижается вероятность конфликта с темой, другим плагином или сторонней библиотекой.

  • Задайте понятную структуру: URL, nonce, валюта и функциональные флаги.
  • Не меняйте названия полей без одновременного обновления PHP и JavaScript.
  • Отделяйте конфигурацию от бизнес-логики: данные передаются inline, а поведение остаётся в файле.
  • Если nonce обновляется или становится недействительным, предусмотрите обработку ответа сервера и повторное получение nonce.
(() => {
    const config = window.MyPlugin?.checkout;

    if (!config) {
        console.error('Конфигурация checkout не найдена.');
        return;
    }

    console.log('Валюта:', config.currency);

    // Для REST-запросов используйте config.restUrl и config.nonce.
})();

Почему wp_localize_script не стоит использовать для любых данных

`wp_localize_script()` исторически предназначен для передачи переводов из PHP в JavaScript. Он действительно может создать глобальный объект и технически передать произвольные значения, но для общей конфигурации это нечёткий и менее выразительный подход.

Для настроек приложения, URL, функциональных флагов и других структурированных данных используйте `wp_add_inline_script()` вместе с `wp_json_encode()`. `wp_localize_script()` оставляйте для локализованных строк и связанных с ними данных перевода.

  • Не передавайте через `wp_localize_script()` большие массивы товаров или результаты сложных запросов.
  • Не называйте объект слишком общо, например `config` или `data`.
  • Помните, что и локализованные данные, и inline-конфигурация всё равно попадают в исходный HTML.

Проверяйте порядок загрузки и типичные ошибки

После подключения откройте DevTools браузера и проверьте не только отсутствие ошибок, но и фактический порядок. На вкладке Network можно увидеть загрузку файлов, в Sources или Elements — inline-код и теги `script`, а в Console — ошибки доступа к зависимостям или конфигурации.

Тестируйте страницу в режиме без кэша, после очистки кэша оптимизатора и с включёнными настройками отложенной загрузки. Оптимизатор может изменить поведение, даже если в исходном PHP порядок задан правильно.

  • Убедитесь, что `wp-api-fetch` или другая зависимость действительно присутствует на странице.
  • Найдите в HTML inline-конфигурацию и проверьте, что она расположена перед `checkout.js`, если использовано `before`.
  • Проверьте, не выводится ли один handle дважды с разными URL или версиями.
  • Сравните страницы авторизованного и неавторизованного пользователя: nonce и доступность данных могут отличаться.
  • Временно отключите объединение и отложенное выполнение JS, чтобы отделить ошибку кода от ошибки оптимизации.

Симптомы и вероятные причины

Если вы видите `checkoutConfig is not defined`, inline-код не был выведен, привязан к другому handle или появился после выполнения основного файла. Ошибка `wp.apiFetch is not a function` обычно означает отсутствующую или неправильно указанную зависимость.

Если всё работает без оптимизатора, но ломается после его включения, проверьте настройки `defer`, задержки выполнения, объединения и исключения для зависимых скриптов. Не исправляйте проблему добавлением случайных `setTimeout`: это маскирует ошибку порядка, но не устраняет её.

Частые вопросы

Нужно ли всегда использовать глобальную переменную для конфигурации?

Нет, но для небольшого объёма серверных данных это простой вариант. Используйте уникальное пространство имён, например `window.MyPlugin.checkout`, и не храните там секреты. Для более сложных интеграций часть данных можно получать через REST API.

Когда в wp_add_inline_script нужно использовать after?

`after` подходит для кода, который должен выполниться после основного файла: например, для инициализации или вызова функции, объявленной в скрипте. Если файл читает конфигурацию при загрузке, используйте `before`.

Является ли nonce секретным значением?

Nonce не следует воспринимать как пароль или полноценный механизм аутентификации. Он помогает проверить запрос в контексте WordPress, но сервер всё равно должен проверять права пользователя. Не передавайте вместе с ним секретные ключи.

Почему код работает в теме, но не работает в Gutenberg или WooCommerce?

В разных контекстах могут отличаться страницы, handles, момент выполнения и набор зависимостей. Проверьте, что скрипт подключается именно там, где нужен, его зависимости зарегистрированы, а конфигурация привязана к правильному handle.

Вывод

Надёжное взаимодействие PHP и JavaScript в WordPress начинается с явного описания зависимостей. Подключайте скрипты через `wp_enqueue_script()`, передавайте конфигурацию через `wp_add_inline_script()` и сериализуйте её с помощью `wp_json_encode()`.

После этого проверьте фактический HTML, порядок выполнения и поведение с оптимизаторами. Такой подход устраняет случайные глобальные переменные, уменьшает количество ошибок `undefined` и делает код более предсказуемым в плагинах, темах, Gutenberg и WooCommerce.

← Все материалы WordPress