⚡ Esora Документация

esrc.js — серверные интерактивные интерфейсы без SPA

esrc.js — небольшой runtime Esora для progressive enhancement. Он позволяет описать HTTP-запрос и место обновления прямо в HTML-атрибутах. Браузер продолжает работать с обычными ссылками и формами, а при загруженном JavaScript отправляет запрос асинхронно и заменяет только нужный фрагмент страницы.

Это не замена полноценному frontend-приложению. esrc.js подходит, когда состояние в основном находится на сервере: формы, фильтры, пагинация, удаление строк, inline-редактирование, навигация по документации и небольшие интерактивные компоненты.

Когда использовать

Используйте esrc.js, если:

  • сервер уже умеет отрисовывать HTML-фрагменты;
  • после действия нужно обновить один блок, а не весь документ;
  • состояние должно оставаться на сервере;
  • не хочется добавлять SPA-роутер и отдельный frontend-state;
  • нужна рабочая страница даже при отключённом JavaScript.

Используйте обычный JavaScript или полноценный frontend, если компонент имеет сложное локальное состояние, drag-and-drop, большой граф редактора, offline-режим или десятки независимых клиентских состояний.

Модальные окна и alert

После подключения esrc.js доступен независимый runtime window.esora. Он не требует дополнительных зависимостей и поддерживает role="dialog", aria-modal, восстановление фокуса, ловушку Tab и закрытие по Escape.

JavaScript API

// Alert: Promise завершается после нажатия OK.
await esora.alert('Профиль сохранён', { type: 'success', title: 'Готово' });

// Confirm: Promise возвращает true для Yes и false для No, Escape или backdrop.
const allowed = await esora.confirm('Удалить запись?', {
    type: 'warning',
    title: 'Подтвердите действие',
    okLabel: 'Yes',
    cancelLabel: 'No',
});

// Произвольный HTML. Возвращаемый объект содержит element, result, close() и focus().
const modal = esora.modal({
    type: 'info',
    title: 'Детали',
    html: true,
    content: '<p><strong>HTML-контент</strong> из доверенного источника.</p>',
    buttons: { Close: null },
});
await modal.result;

Поддерживаемые типы: info, success, warning, error. По умолчанию alert и confirm вставляют сообщение как текст (html: false). Для modal HTML разрешён явно; не передавайте в него непроверенный пользовательский ввод.

Data-атрибуты

<button type="button"
        data-esora-alert="Синхронизация завершена"
        data-esora-alert-type="success"
        data-esora-title="Успешно">
    Показать alert
</button>

<button type="button"
        data-esora-confirm="Удалить черновик?"
        data-esora-alert-type="warning">
    Удалить
</button>

<button type="button"
        data-esora-modal="#help-modal"
        data-esora-title="Справка"
        data-esora-alert-type="info">
    Открыть modal
</button>
<template id="help-modal"><p>Произвольный HTML из шаблона.</p></template>

Для data-esora-modal значение, начинающееся с #, трактуется как селектор элемента; его innerHTML копируется в modal. Остальные значения трактуются как HTML-строка. После esrc-swap runtime повторно сканирует вставленный фрагмент, поэтому новые data-атрибуты работают без ручной инициализации.

data-esrc-confirm использует esora.confirm, если runtime подключён. При отсутствии этого API сохраняется обратная совместимость с нативным window.confirm.

Установка и подключение

1. Опубликовать runtime

В проекте Esora выполните:

php bin/console assets:publish

Команда публикует esrc.js в public/assets/js/esrc.js. После изменения исходников ассетов в production повторите публикацию.

2. Подключить runtime в layout

Подключите скрипт после HTML-разметки или с атрибутом defer:

<body>
    <!-- страница и элементы с data-esrc-* -->

    <script src="/assets/js/esrc.js"></script>
</body>

Runtime автоматически сканирует DOM после DOMContentLoaded. Повторный вызов esrc.scan() безопасен: уже привязанные элементы повторно не подписываются.

3. Добавить endpoint

Контроллер должен вернуть HTML, который можно вставить в target:

use Esora\Http\ResponseFactory;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

public function ping(ServerRequestInterface $request): ResponseInterface
{
    return ResponseFactory::html(
        '<span class="status status--ok">Сервер отвечает</span>'
    );
}

Маршрут:

$router->get('/api/ping', [StatusController::class, 'ping']);

Для HTML-ответа используйте ResponseFactory::html(). Runtime получает тело ответа как текст и передаёт его в выбранную swap-стратегию.

Первый пример: GET и innerHTML

<button
    type="button"
    data-esrc-get="/api/ping"
    data-esrc-target="#ping-result"
>
    Проверить соединение
</button>

<div id="ping-result" aria-live="polite">
    Проверка ещё не выполнялась.
</div>

Что произойдёт:

  1. runtime найдёт data-esrc-get;
  2. для button по умолчанию выберет событие click;
  3. отправит GET /api/ping;
  4. возьмёт ответ сервера;
  5. установит его как innerHTML элемента #ping-result.

data-esrc-target — CSS-селектор. Если target не найден, запрос всё равно отправится, но визуально результат никуда не попадёт. Поэтому ID или селектор target нужно проверять особенно внимательно.

Атрибуты запросов

HTTP-метод и URL

Используйте один атрибут метода на элементе:

<button data-esrc-get="/users/42">Загрузить</button>
<form data-esrc-post="/users">...</form>
<button data-esrc-put="/users/42">Сохранить</button>
<button data-esrc-delete="/users/42">Удалить</button>

Поддерживаются:

  • data-esrc-get → GET;
  • data-esrc-post → POST;
  • data-esrc-put → PUT;
  • data-esrc-delete → DELETE.

Runtime использует URL как есть. Query string можно указать прямо в атрибуте:

<button data-esrc-get="/reports?period=week" data-esrc-target="#report">
    За неделю
</button>

Target

<div id="result"></div>

<button
    data-esrc-get="/fragment"
    data-esrc-target="#result"
>
    Обновить
</button>

Кроме обычного CSS-селектора, поддерживаются два относительных варианта:

<!-- target — ближайшая карточка с классом .card -->
<button data-esrc-get="/status" data-esrc-target="closest .card">
    Обновить карточку
</button>

<!-- target — элемент #content внутри текущего элемента -->
<div data-esrc-get="/status" data-esrc-target="find #content">
    <div id="content"></div>
</div>

Если data-esrc-target не указан, target-ом считается сам элемент, инициировавший запрос. Для кнопок обычно лучше указывать отдельный target, иначе ответ заменит содержимое самой кнопки.

Swap-стратегии

По умолчанию используется innerHTML:

<button
    data-esrc-get="/cart"
    data-esrc-target="#cart"
    data-esrc-swap="innerHTML"
>
    Обновить корзину
</button>

Доступные значения:

  • innerHTML — заменяет содержимое target.
  • outerHTML — заменяет сам target новым HTML.
  • beforebegin — вставляет HTML перед target.
  • afterbegin — вставляет HTML в начало target.
  • beforeend — добавляет HTML в конец списка.
  • afterend — вставляет HTML после target.
  • none — выполняет запрос, но не меняет DOM.

Примеры:

<!-- Ответ становится новым содержимым списка -->
<div id="notifications"></div>
<button data-esrc-get="/notifications" data-esrc-target="#notifications">
    Обновить уведомления
</button>

<!-- Ответ добавляется новой строкой в конец списка -->
<ul id="messages">
    <li>Старое сообщение</li>
</ul>
<button
    data-esrc-get="/messages/latest"
    data-esrc-target="#messages"
    data-esrc-swap="beforeend"
>
    Загрузить ещё
</button>

После вставки runtime снова сканирует добавленный DOM. Поэтому элементы с data-esrc-*, пришедшие в HTML-ответе, начинают работать без ручной инициализации.

Формы и отправка данных

Для формы runtime по умолчанию использует событие submit и сериализует поля через FormData.

POST-форма

<form
    data-esrc-post="/profile"
    data-esrc-target="#profile-result"
>
    <label>
        Имя
        <input name="name" required>
    </label>

    <label>
        Email
        <input name="email" type="email" required>
    </label>

    <button type="submit">Сохранить</button>
</form>

<div id="profile-result" aria-live="polite"></div>

Контроллер получает данные через PSR-7 request:

public function update(ServerRequestInterface $request): ResponseInterface
{
    $body = $request->getParsedBody();
    $data = is_array($body) ? $body : [];

    $name = htmlspecialchars((string) ($data['name'] ?? ''), ENT_QUOTES, 'UTF-8');

    return ResponseFactory::html(
        '<p class="notice">Профиль сохранён: ' . $name . '</p>'
    );
}

Для GET-формы поля превращаются в query-параметры:

<form data-esrc-get="/search" data-esrc-target="#results">
    <input name="q" placeholder="Поиск">
    <select name="status">
        <option value="open">Открытые</option>
        <option value="closed">Закрытые</option>
    </select>
    <button type="submit">Найти</button>
</form>

В результате runtime отправит запрос вида /search?q=...&status=open.

Передача дополнительных полей через include

Если инициатором является не форма, поля можно подключить через data-esrc-include:

<input id="filter" name="q" value="esora">
<select id="sort" name="sort">
    <option value="newest">Сначала новые</option>
    <option value="oldest">Сначала старые</option>
</select>

<button
    data-esrc-get="/articles"
    data-esrc-include="#filter, #sort"
    data-esrc-target="#articles"
>
    Применить фильтр
</button>

<div id="articles"></div>

Runtime соберёт элементы из CSS-селектора, возьмёт их name и value, а для GET добавит их в query string. Для POST/PUT/DELETE эти поля войдут в FormData.

События и пользовательские сценарии

Изменить trigger

Для кнопок и ссылок default trigger — click, для форм — submit, для input, select и textarea — change. Явное событие задаётся так:

<select
    name="category"
    data-esrc-get="/products"
    data-esrc-trigger="change"
    data-esrc-target="#products"
>
    <option value="books">Книги</option>
    <option value="tools">Инструменты</option>
</select>

data-esrc-trigger поддерживает события click, submit, change, input и специальное load.

Загрузка блока при открытии страницы

<section
    data-esrc-get="/dashboard/summary"
    data-esrc-trigger="load"
    data-esrc-target="this"
>
    Загружаем сводку…
</section>

При load запрос запускается сразу после инициализации runtime. Не используйте этот режим для большого количества блоков без необходимости: каждый блок создаёт отдельный запрос.

Ссылка без полной перезагрузки

Обычная ссылка сохраняет fallback-навигацию:

<a
    href="/docs/database"
    data-esrc-get="/docs/database"
    data-esrc-target="article.doc"
    data-esrc-push-url="true"
>
    База данных
</a>

С включённым runtime HTML-ответ заменит только article.doc, а history.pushState() добавит новый URL. Без JavaScript браузер перейдёт по href как обычно.

Индикаторы и подтверждение действия

Индикатор загрузки

Укажите CSS-селектор элемента, которому во время запроса добавляется класс esrc-loading:

<span id="spinner" hidden>Загрузка…</span>

<button
    data-esrc-post="/export"
    data-esrc-target="#export-result"
    data-esrc-indicator="#spinner"
>
    Запустить экспорт
</button>

CSS может управлять отображением:

#spinner { display: none; }
#spinner.esrc-loading { display: inline; }

На элементе, который отправляет запрос, во время выполнения также появляется класс esrc-requesting.

Подтверждение опасного действия

<button
    data-esrc-delete="/projects/42"
    data-esrc-target="closest .project-row"
    data-esrc-swap="outerHTML"
    data-esrc-confirm="Удалить проект без возможности восстановления?"
>
    Удалить
</button>

Перед запросом runtime вызовет стандартный window.confirm(). При отмене запрос не отправляется.

CSRF и изменяющие запросы

GET, HEAD и OPTIONS считаются безопасными методами и не требуют CSRF-заголовка от esrc.js. Для POST, PUT и DELETE runtime читает cookie nqphp_csrf и, если токен найден, отправляет его как X-CSRF-Token.

Пример серверного middleware с формой:

<form data-esrc-post="/settings" data-esrc-target="#result">
    <input type="hidden" name="_token" value="<?= htmlspecialchars($csrfToken) ?>">
    <input name="timezone" value="UTC">
    <button>Сохранить</button>
</form>

На стороне приложения CSRF middleware также может проверить токен из _token или заголовка. Если сервер вернул 419, проверьте:

  1. middleware добавляет CSRF-cookie на страницу;
  2. форма содержит актуальный _token, если приложение использует поле формы;
  3. cookie доступна текущему домену;
  4. запрос отправляется на тот же origin;
  5. в DevTools Network присутствует X-CSRF-Token.

Не отключайте CSRF только ради работы демо. Исключение endpoint из проверки оправдано только для осознанно публичного, безопасного API.

Lifecycle и события JavaScript

Для каждого запроса lifecycle выглядит так:

  1. пользователь вызывает trigger;
  2. runtime определяет method, URL, target и swap;
  3. добавляется Accept: text/html, application/xhtml+xml;
  4. добавляется X-NQPHP-Request: true;
  5. для изменяющего метода добавляется CSRF-заголовок, если токен найден;
  6. отправляется fetch();
  7. срабатывает nq:beforeRequest;
  8. ответ вставляется в target;
  9. при наличии data-esrc-push-url="true" обновляется history;
  10. срабатывает nq:afterRequest.

Можно отменить запрос в nq:beforeRequest:

<script>
document.addEventListener('nq:beforeRequest', (event) => {
    const { element } = event.detail;

    if (element.matches('[data-requires-online]') && !navigator.onLine) {
        event.preventDefault();
        document.querySelector('#result').textContent = 'Нет соединения.';
    }
});
</script>

Отслеживание успешного ответа:

<script>
document.addEventListener('nq:afterRequest', (event) => {
    const { status, element, responseText } = event.detail;

    console.log('esrc request completed', {
        status,
        url: element.getAttribute('data-esrc-get')
            || element.getAttribute('data-esrc-post'),
        responseText,
    });
});
</script>

Ошибки доступны через nq:error:

<script>
document.addEventListener('nq:error', (event) => {
    const { status, responseText, error } = event.detail;
    console.error('esrc request failed', { status, responseText, error });
});
</script>

nq:error срабатывает для HTTP-ответа с кодом не из диапазона 2xx, а также для сетевой ошибки. Сам runtime всё равно получает текст ответа и применяет swap; если нужно особое поведение для 422 или 419, обработайте событие и выберите подходящую разметку ответа.

Ответы сервера и безопасность HTML

Обычно endpoint для esrc возвращает HTML-фрагмент:

return ResponseFactory::html(
    '<div class="alert">Операция выполнена.</div>'
);

Значения пользователя обязательно экранируйте до вставки в HTML:

$name = htmlspecialchars(
    (string) ($data['name'] ?? ''),
    ENT_QUOTES,
    'UTF-8'
);

return ResponseFactory::html('<p>Привет, ' . $name . '</p>');

Не вставляйте непроверенный пользовательский HTML. innerHTML, outerHTML и остальные swap-стратегии вставляют ответ как HTML. Если endpoint возвращает JSON, esrc.js не преобразует его в объект и не форматирует автоматически — верните HTML-фрагмент либо подпишитесь на nq:afterRequest и обработайте responseText самостоятельно.

Динамические элементы и повторное сканирование

Ответ может содержать новый управляемый элемент:

return ResponseFactory::html(<<<'HTML'
    <button data-esrc-get="/tasks/next" data-esrc-target="#tasks">
        Показать ещё
    </button>
HTML);

После innerHTML, beforeend, afterbegin и других swap-операций runtime вызывает внутренний scan для добавленного DOM. В большинстве случаев дополнительный код не нужен. Если разметка добавлена сторонним скриптом напрямую, вызовите:

<script>
    window.esrc?.scan();
</script>

Полный пример: список задач

Маршруты

$router->get('/tasks', [TaskController::class, 'index']);
$router->post('/tasks', [TaskController::class, 'store']);
$router->delete('/tasks/{id}', [TaskController::class, 'destroy']);

Контроллер

public function store(ServerRequestInterface $request): ResponseInterface
{
    $body = $request->getParsedBody();
    $title = is_array($body) ? trim((string) ($body['title'] ?? '')) : '';

    if ($title === '') {
        return ResponseFactory::html(
            '<p class="alert alert--error">Введите название задачи.</p>',
            422
        );
    }

    // Сохранение через модель или Query Builder.
    $safeTitle = htmlspecialchars($title, ENT_QUOTES, 'UTF-8');

    return ResponseFactory::html(
        '<li class="task"><span>' . $safeTitle . '</span>'
        . '<button data-esrc-delete="/tasks/1" '
        . 'data-esrc-target="closest .task" '
        . 'data-esrc-swap="outerHTML" '
        . 'data-esrc-confirm="Удалить задачу?">Удалить</button></li>'
    );
}

Шаблон

<form data-esrc-post="/tasks" data-esrc-target="#task-result">
    <input name="title" placeholder="Название задачи">
    <button type="submit">Добавить</button>
</form>
<div id="task-result"></div>

<ul id="tasks">
    <li class="task">
        Разобрать документацию
        <button
            data-esrc-delete="/tasks/1"
            data-esrc-target="closest .task"
            data-esrc-swap="outerHTML"
            data-esrc-confirm="Удалить задачу?"
        >
            Удалить
        </button>
    </li>
</ul>

В production вместо фиксированного ID используйте ID созданной записи и экранируйте каждое значение, пришедшее из базы данных.

Диагностика

Нажатие ничего не делает

Проверьте:

  • загружен ли /assets/js/esrc.js со статусом 200;
  • присутствует ли data-esrc-get, data-esrc-post, data-esrc-put или data-esrc-delete;
  • нет ли одновременно нескольких конфликтующих method-атрибутов;
  • есть ли у формы button type="submit";
  • нет ли ошибки JavaScript в Console.

Запрос есть, но блок пустой

Проверьте:

  • корректен ли data-esrc-target;
  • действительно ли endpoint возвращает HTML;
  • не возвращает ли контроллер полный layout вместо fragment;
  • не используется ли data-esrc-swap="none";
  • какой текст и статус видны в Network.

Сработала полная перезагрузка

Это обычно означает, что JavaScript не загрузился, элемент не был просканирован или ссылка не получила data-esrc-*. Это штатный fallback: после исправления загрузки runtime та же ссылка начнёт работать без перезагрузки.

Endpoint возвращает 419, 422 или 500

  • 419: CSRF-токен отсутствует или устарел;
  • 422: сервер отклонил данные, верните понятный HTML с ошибками;
  • 500: смотрите логи приложения и сначала вызовите endpoint напрямую через Network/curl.

Для проверки endpoint отдельно:

curl -i -X POST https://example.test/tasks \
    -H 'Accept: text/html' \
    -H 'X-NQPHP-Request: true' \
    --data 'title=Первая задача'

Краткая памятка

<!-- GET и обновление блока -->
<button data-esrc-get="/fragment" data-esrc-target="#result">Load</button>

<!-- POST-форма -->
<form data-esrc-post="/save" data-esrc-target="#result">...</form>

<!-- Удаление строки -->
<button data-esrc-delete="/items/1" data-esrc-target="closest .row" data-esrc-swap="outerHTML">
    Delete
</button>

<!-- Навигация с URL без полной перезагрузки -->
<a href="/docs/next" data-esrc-get="/docs/next" data-esrc-target="article.doc" data-esrc-push-url="true">
    Next
</a>

Связанные разделы: Маршрутизация, Контроллеры, Валидация, Безопасность, Vite.