☰
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