webkul/inertia

Серверный адаптер Inertia.js для PHP, не зависящий от фреймворка и прозрачно интегрирующийся с WordPress. Реализует полный протокол: от первичного HTML с данными до частичных перезагрузок и проверки версий ресурсов.

Категория:

Что это

Серверный адаптер протокола Inertia.js на чистом PHP. Пакет не привязан к конкретному фреймворку — работает в любом PHP-приложении. Если в окружении загружен WordPress, адаптер автоматически подхватывает его функции (wp_json_encode, status_header, sanitize_text_field) и учитывает настройку кодировки из опции blog_charset.

Адаптер реализует полный цикл взаимодействия Inertia:

  • Первое и обычное посещение — формирует HTML-документ с JSON-объектом страницы, встроенным в тег <script> (соглашение Inertia v3).
  • Inertia-посещение (XHR с заголовком X-Inertia: true) — отдаёт чистый JSON, без HTML, чтобы клиент мог обновить компоненты без перезагрузки.
  • Устаревшие ресурсы — при несовпадении заголовка X-Inertia-Version возвращает статус 409 и заголовок X-Inertia-Location, вызывая однократную жёсткую перезагрузку для получения свежих сборок.
  • Частичные перезагрузки — фильтрует свойства по заголовкам X-Inertia-Partial-Data и X-Inertia-Partial-Except. Свойства-замыкания вычисляются лениво после фильтрации, поэтому пропущенные поля не порождают лишних вычислений.

Назначение и сценарии использования

Адаптер упрощает построение SPA-интерфейсов на PHP без создания отдельного API. Основные сценарии:

  • Чистые PHP-приложения, где нужен реактивный фронтенд, но нет желания разворачивать Laravel или другой фреймворк с готовой интеграцией Inertia.
  • Сайты и плагины WordPress: позволяет встроить Inertia.js прямо в панель администратора или в публичную часть, используя привычную инфраструктуру хуков и функций.
  • Проекты, чувствительные к производительности: благодаря частичным перезагрузкам и ленивым свойствам сервер выполняет только ту работу, которая действительно нужна клиенту.

Составляющие и особенности

Установка

composer require webkul/inertia

Если пакет подключается как локальный репозиторий (тип path), в composer.json добавляют:

{
  "repositories": [
    { "type": "path", "url": "packages/inertia" }
  ],
  "require": {
    "webkul/inertia": "@dev"
  }
}

Конфигурация

Основной класс WebkulInertiaInertia предоставляет несколько методов для настройки:

Метод Назначение
`set_version(string callable $version)`
set_root_view(callable $renderer) Отрисовщик HTML-оболочки для стандартных посещений. Получает (string $page_json, array $page), должен вывести полный документ.
set_app_id(string $id) Идентификатор контейнера, используемый встроенной оболочкой по умолчанию (значение по умолчанию — app). Актуален, если не задан root view.
set_charset(string $charset) Кодировка ответа (по умолчанию UTF-8). В среде WordPress приоритет имеет blog_charset.

Базовое использование

Вызов render($component, $props) завершает запрос, отдавая нужный ответ в зависимости от типа запроса.

Чистый PHP:

use WebkulInertiaInertia;

$inertia = Inertia::instance()
    ->set_version('1.0.0')
    ->set_app_id('app');

$inertia->render('Order', [
    'orders'  => fn() => fetch_orders(), // ленивая загрузка
    'filters' => $filters,
]);

WordPress с кастомной оболочкой:

use WebkulInertiaInertia;

$inertia = Inertia::instance()
    ->set_version(MY_PLUGIN_SCRIPT_VERSION)
    ->set_root_view([My_Template::instance(), 'render_ui_template']);

if (!$inertia->is_inertia_request()) {
    my_plugin_enqueue_app_assets();
}

Если корневое представление не задано, используется минимальная оболочка: тег <script> с JSON-данными и пустой <div> с указанным app_id. В WordPress в неё автоматически добавляются вызовы wp_head(), wp_footer() и body_class().

Практические примеры

В директории examples репозитория находятся два готовых мини-приложения:

  • examples/react — клиентская часть на официальном адаптере @inertiajs/react (React 18), демонстрирует SPA-ссылки и частичные перезагрузки через router.reload({ only: [...] }).
  • examples/vanilla-js — около 70 строк самодельного клиента, показывающего сырой протокол: загрузка из JSON-тега, fetch-посещения с заголовками X-Inertia, обработка 409 с жёсткой перезагрузкой, частичные перезагрузки, поддержка переходов вперёд/назад.

Каждый пример запускается командой php -S localhost:8000 index.php.

Кому и для чего полезно

  • PHP-разработчикам, которые хотят использовать Inertia.js без привязки к Laravel или Symfony, получая лёгкую и бесшовную SPA-интеграцию.
  • Авторам плагинов и тем для WordPress, стремящимся к реактивным интерфейсам в админке или на фронтенде без глубокой перестройки серверной логики.
  • Тем, кто ценит производительность: ленивое вычисление свойств и частичные перезагрузки позволяют серверу отвечать только необходимыми данными.

Ограничения

  • Это только серверная часть протокола Inertia; нужна клиентская библиотека (React, Vue, Svelte) или самописный адаптер на стороне браузера.
  • Готовый роутинг отсутствует — маршруты необходимо определять самостоятельно на стороне PHP.
  • Автоматическая HTML-оболочка в WordPress (с wp_head/wp_footer) может конфликтовать с некоторыми темами; в таких случаях рекомендуется задать собственный root_view.
  • Версию ресурсов (set_version) нужно обновлять вручную при каждом изменении клиентских ассетов, иначе механизм 409 не сработает корректно.

Похожие