FetchIt

Легковесный компонент для обработки и отправки форм с помощью Fetch API
Версия 4.0.0-pl
Дата выпуска 25.09.2026
Загрузки 1 174
FetchIt отправляет формы сайта через Fetch API: без перезагрузки страницы, без jQuery и других библиотек. Формы обрабатывает FormIt со всеми своими хуками и валидацией — или ваш собственный сниппет. Каждая форма защищена от спама с первой минуты: одноразовый токен, время заполнения, поле-ловушка и лимит отправок, а когда нужно — доказательство работы и капча. Один пакет ставится и на MODX 2.8, и на MODX 3.

Вызов сниппета


Вызов обязательно некэшируемый: у каждого вывода формы свой токен.

[[!FetchIt?
  &form=`myForm.tpl`
  &hooks=`email`
  &emailTo=`info@example.com`
  &validate=`name:required,email:email:required`
  &successMessage=`Сообщение отправлено`
]]
Свойства &hooks, &validate, &emailTo и остальные уходят в FormIt как есть, без обёрток. Вместо FormIt можно указать свой сниппет — он получит отправленные поля и ответит через $FetchIt->success() или $FetchIt->error().

Ваша вёрстка


Готовой формы компонент не навязывает: нужен чанк с атрибутами. data-error="name" получает ошибку поля, само поле — aria-invalid и класс из настройки, data-success и data-validation-error — сообщение формы.

<form action="[[~[[*id]]]]" method="post">
  <input type="email" name="email" value="[[+fi.email]]">
  <span data-error="email">[[+fi.error.email]]</span>
  <button type="submit">Отправить</button>
</form>
Чанки через pdoTools — с Fenom и @FILE, на MODX 2 и MODX 3. Готовый пример ставится вместе с пакетом: tpl.FetchIt.example.

Защита от спама из коробки


Проверки идут до FormIt и до вашего сниппета — и для отправки через FetchIt, и для формы, отправленной без JavaScript.

  • Токен. В форме скрытое поле с подписью ключа формы, времени вывода и случайного числа. Токен одноразовый, сессия для него не нужна. Новый выдаётся только в ответ на верно подписанный токен той же формы, так что отправить форму, не загрузив страницу, бот не может.
  • Время заполнения. Форма, отправленная быстрее, чем через fetchit.protection.min_time секунд после вывода страницы (по умолчанию 3), не принимается.
  • Ловушка. Скрытое поле со случайным именем, своим на каждой установке: люди его не видят, автозаполнение браузера не узнаёт. Бот, который его заполнил, получает успешный ответ, но форма не обрабатывается и письмо не уходит.
  • Лимит. Не больше fetchit.protection.rate_limit отправок формы с одного адреса за fetchit.protection.rate_window секунд — по умолчанию 10 за 10 минут. Считаются все попытки с верно подписанным токеном, отклонённые тоже.
Служебные поля удаляются из $_POST до FormIt и в письма не попадают. Ключ подписи генерируется при установке. За прокси и CDN адрес посетителя берётся из заголовка, перечисленного в настройках, — иначе лимит стал бы общим на весь сайт.

Отказ приходит обычной ошибкой формы: сообщение из лексикона, событие fetchit:error и уведомление. Если токен страницы устарел — страница из кэша, открыта давно, сменился ключ, — FetchIt сам отправляет форму заново с новым токеном, и посетитель ничего не замечает.

Доказательство работы и капча


Оба выключены по умолчанию и нужны, когда спам проходит основные проверки.

Доказательство работы. fetchit.protection.pow задаёт сложность в битах. Браузер ищет число, у которого SHA-256 от токен:число начинается с нужного количества нулевых битов, и отправляет его вместе с формой. Счёт начинается, как только посетитель зашёл в форму, поэтому к нажатию кнопки решение обычно готово, а каждая отправка стоит боту процессорного времени. 16 бит — это около 65 тысяч хэшей, примерно треть секунды на компьютере; каждый бит удваивает время.

Капча. Cloudflare Turnstile, Google reCAPTCHA v3 или Yandex SmartCaptcha — выбирается настройкой, ключи берутся в кабинете провайдера. FetchIt сам подключает скрипт провайдера, получает ответ перед отправкой и проверяет его на сервере последней из проверок, так что боты без токена до провайдера не доходят. Если провайдер недоступен или не принял ключ, форма отклоняется с отдельным сообщением, а причина пишется в лог.

Работает и без JavaScript


С FormIt форма отправляется обычным способом, а сообщения и введённые значения возвращаются его плейсхолдерами. Защита работает и здесь. Исключение — доказательство работы и капча: им JavaScript нужен.

Уведомления


Настройкой fetchit.frontend.default.notifier ответы сервера показываются уведомлениями в углу страницы. Своих библиотек компонент не тянет: уведомления собственные.

Уведомления FetchIt: ошибка и успешная отправка

Их читают скринридеры — на странице две скрытые live-области, ошибка объявляется сразу, успех когда читалка свободна. Уведомление закрывается кнопкой или само через шесть секунд, под курсором и в фокусе отсчёт останавливается. Цвета — CSS-переменные, по умолчанию пастельные оттенки Tailwind CSS 4 с контрастом текста около 6.5:1. Если на сайте свой показ сообщений — FetchIt.Message с любой библиотекой: Bootstrap, SweetAlert2, что угодно.

События и TypeScript


fetchit:before, fetchit:after, fetchit:success, fetchit:error и fetchit:reset — на document, с формой, данными и ответом сервера в detail. Любое можно отменить: добавить поля перед отправкой, показать модальное окно, отправить событие в аналитику.

document.addEventListener('fetchit:success', ({ detail }) => {
  gtag('event', 'form_submit', { form_id: detail.form.id })
})
Рядом со скриптом лежат типы TypeScript — fetchit.d.ts с классом, экземплярами форм и detail каждого события. Сам скрипт проверяется по этому же файлу, поэтому типы и код не расходятся.

Без зависимостей


Скрипт не требует jQuery и других библиотек: нативные Fetch API и FormData, файлы в том числе. Минифицированный — 19 КБ, около 7 КБ по сети в gzip. Подключается с defer и ничего больше не загружает, кроме скрипта капчи, когда она включена. На странице может быть сколько угодно форм, у каждой свой ключ и свой обработчик.

Один пакет для MODX 2.8 и MODX 3


Раньше их было два: линия 1.x для MODX 2 и 3.x для MODX 3. FetchIt 4 ставится поверх любой из них, системные настройки и чанки остаются на месте; вызовы сниппета на страницах менять не нужно. API прежних версий работает на обеих версиях MODX: FetchIt::service($modx), класс FetchIt\FetchIt, прежние имена методов.

Что может задеть ваш код: форма получает служебные поля защиты, поэтому свой скрипт вместо штатного должен отправлять токен; уведомления больше не грузят Notyf; fetchit:error теперь срабатывает и при сетевой ошибке. Полный список — в истории изменений и в README на GitHub.

История изменений FetchIt

Здесь описаны все заметные изменения проекта. Формат основан на Keep a Changelog, проект следует семантическому версионированию.

FetchIt 1.x был пакетом для MODX 2, FetchIt 3.x — пакетом для MODX 3. FetchIt 4 заменяет оба одним пакетом и ставится поверх любого из них.

4.0.0 - 2026-09-25

Один пакет для MODX 2.8 и MODX 3, с защитой от спама, включённой по умолчанию. Ставится поверх FetchIt 1.x на MODX 2 и FetchIt 3.x на MODX 3; системные настройки и чанки сохраняются. То, что может задеть ваш код, помечено ниже как Ломающее и разобрано в README, Переход на FetchIt 4.

Добавлено

  • Защита от спама для каждой формы, включена по умолчанию — и для отправок через FetchIt, и для форм, отправленных без JavaScript. fetchit.protection выключает её целиком.
    • Подписанный одноразовый токен в каждой форме (fetchit_token), сессия не нужна. Следующий токен, в заголовке X-FetchIt-Token, получает только запрос с верно подписанным токеном своей формы. Если токен страницы устарел (страница из кеша, долго открытая страница, новый ключ), скрипт сам отправляет форму ещё раз с новым токеном.
    • Минимальное время заполнения (fetchit.protection.min_time, 3 секунды), считается от первого вывода страницы, включая повторные отправки.
    • Скрытое поле-ловушка со случайным именем для каждой установки. Бот, который его заполнил, получает мнимый успех, а форма не обрабатывается.
    • Ограничение числа отправок на форму и адрес клиента (fetchit.protection.rate_limit, fetchit.protection.rate_window), в том числе за доверенными прокси и CDN (fetchit.protection.proxies, fetchit.protection.ip_header).
    • Использованные токены помечаются атомарно в core/cache/fetchit/tokens/, «Очистить кеш» этот каталог не трогает. Если пометку записать не удалось, форма отклоняется, а причина попадает в лог.
    • Необязательное доказательство работы (fetchit.protection.pow, в битах, по умолчанию выключено): браузер ищет n, при котором SHA-256 от token:n начинается с такого числа нулевых битов, и начинает, как только посетитель вошёл в форму. Если страница из кеша просит меньше, чем требует сервер, отказ несёт заголовок X-FetchIt-Pow, и скрипт решает задачу и отправляет ещё раз.
    • Необязательные капчи: Cloudflare Turnstile, Google reCAPTCHA v3 и Яндекс SmartCaptcha (fetchit.captcha, fetchit.captcha.site_key, fetchit.captcha.secret_key, fetchit.captcha.min_score). FetchIt подключает скрипт провайдера, получает его ответ перед каждой отправкой и проверяет его на сервере последним. Недоступный провайдер отклоняет форму своим сообщением fetchit_err_captcha_unavailable; капча, которой нечего отправить, останавливает отправку с fetchit_err_captcha_client.
    • Лог отказов и неполадок (fetchit.protection.log) и ключ подписи, который создаётся при установке (fetchit.protection.secret). Ошибки в настройках капчи и доказательства работы пишутся в лог.
  • Событие OnFetchItBeforeProcess: плагин получает $action, $fields, $properties и $FetchIt и отклоняет отправку через $modx->event->output(). Срабатывает и с выключенной защитой.
  • Поддержка MODX 3 в том же пакете, собранном на MODX 2.8: он ставится начисто и на MODX 2.8, и на MODX 3.
  • API FetchIt 3.x на обеих версиях: класс FetchIt\FetchIt, saveActionProperties() и getActionProperties(), а на MODX 3 — $modx->services->get('FetchIt').
  • FetchIt::service() — один общий экземпляр на MODX 2 и MODX 3; способы получить FetchIt из 1.x и 3.x возвращают его же.
  • FetchIt::pdoTools() — находит pdoTools 2 на MODX 2 и pdoTools 3 на MODX 3, для Fenom и чанков @FILE.
  • FetchIt::prepareForm() — проставляет тегам формы в чанке метод POST и ключ формы.
  • Типы TypeScript, assets/components/fetchit/js/fetchit.d.ts: FetchIt, конфиг, FetchIt.Message, экземпляры форм и события fetchit:* с их detail. Скрипт проверяется по ним.
  • FetchIt.createNotifier() — встроенные уведомления для сайта, который сам задаёт FetchIt.Message. duration: 0 оставляет уведомление до закрытия.
  • detail.error в fetchit:error, когда запрос не удался, и строка лексикона fetchit_err_request, которую посетитель тогда видит.
  • Записи в лог MODX, когда скрипт не удаётся добавить на страницу с формой: нет ` илиfetchit.frontend.jsуказывает не на файл.js`.
  • Обновление с включённой fetchit.frontend.default.notifier пишет в лог, что Notyf больше не подключается, и предупреждает, если fetchit.frontend.js указывает на скрипт сайта.

Изменено

  • Ломающее: служебные поля защиты ставятся сразу после тега формы и убираются из $_POST до того, как их прочитает FormIt, поэтому в письма они не попадают. Свой скрипт вместо встроенного должен отправлять fetchit_token и брать следующий токен из заголовка X-FetchIt-Token каждого ответа.
  • Ломающее: уведомления fetchit.frontend.default.notifier теперь собственные, а не Notyf, и window.Notyf больше не подключается. Стили для .notyf__toast и скрипты с new Notyf() придётся поправить. Новые уведомления доступны (живые области для скринридеров, кнопка закрытия с подписью, работа с фокусом), не исчезают под курсором и при фокусе и берут цвета из CSS-переменных — по умолчанию пастельные зелёный и красный из Tailwind CSS 4. При Content-Security-Policy берут nonce скрипта FetchIt.
  • Ломающее: fetchit:error срабатывает и при неудачном запросе, тогда detail.response равен null.
  • Ломающее: сниппет обработки получает в fields только отправленную форму: $_POST, а для отправок через FetchIt ещё и $_FILES. Раньше приходил $_REQUEST — со значениями GET и, в зависимости от request_order, с cookie.
  • При включённой защите сниппет по-прежнему запускает FormIt на каждый показ страницы, ради его preHooks, но отправкой считается только POST с токеном своей формы.
  • Скрипт собирается синтаксисом ES2019, поэтому работает во всех браузерах из browserslist проекта.
  • Хуки FetchIt.Message и события получают строку message и объект data, даже если сниппет обработки их не вернул. Исключение в хуке пишется в лог с его именем и больше не мешает форме получить ответ.
  • fetchit:success можно отменить: event.preventDefault() оставляет поля заполненными.
  • Повторная отправка, пока идёт запрос, игнорируется.
  • На MODX 3 плагин и action.php берут FetchIt из контейнера сервисов, а не через устаревший getService().
  • Строчный вызов FetchIt.create() проверяет, что класс из fetchit.frontend.js.classname загружен, поэтому страница без скрипта откатывается к обычной отправке, а не падает. FetchIt.create() предупреждает в консоли, если ни одна форма не подошла.
  • method и data-fetchit идут последними среди атрибутов тега формы, а ?v= в адресе скрипта сохраняет строку запроса и якорь.

Удалено

  • lib/notyf.min.js и lib/notyf.min.css больше не поставляются. При обновлении прежние копии остаются на месте.

Исправлено

  • Форма, отправленная без JavaScript, не показывала сообщение об успехе или ошибке, если чанк применял выходные фильтры к плейсхолдерам FormIt, как в примере чанка: чанк отрисовывался до запуска FormIt.
  • Тег формы со своим data-fetchit ломался, похожие теги вроде ` менялись, как иformmethodиdata-fetchit` у элементов внутри формы. Теги формы теперь разбираются по одному, вместе со значениями в кавычках.
  • Скрипт не добавлялся на сайтах без анонимных сессий, а также когда `` был написан заглавными или имел атрибуты.
  • FormIt не ставился вместе с FetchIt на MODX 3. Установщик теперь ещё и сообщает о каждой причине, по которой скачивание или установка FormIt может не удаться.
  • Два одинаковых вызова сниппета на странице привязывали форму дважды, и она отправлялась дважды.
  • Поля, отключённые в разметке, после отправки становились доступными.
  • Ошибка сети или ответ не от FetchIt (страница ошибки PHP, HTML после редиректа, JSON от файрвола) попадали только в консоль. Теперь посетитель видит fetchit_err_request.
  • Плейсхолдер ошибки FormIt, содержащий только  , помечал поле как неверное.
  • Имена полей с кавычками ломали селекторы ошибок.
  • Несуществующий набор свойств сниппета ронял action.php на PHP 8. Теперь сниппет работает без него, а в лог MODX попадает имя пропавшего набора.
  • Без настройки fetchit.frontend.js плагин подключал несуществующий js/default.js.
  • Уведомления об устаревании на PHP 8.1, когда настроек классов невалидности нет.

Безопасность

  • POST прямо на адрес страницы с формой FetchIt доходил до FormIt и его хуков, включая письма, без единой проверки. Теперь он обязан нести верный токен своей формы.
  • FormIt 5.2 и новее сохранял свойства каждой формы FetchIt, вместе с хуками, для собственного action.php, который обрабатывает форму без проверок FetchIt. Теперь FetchIt выключает этот AJAX-режим для своих форм: убирает сохранённые свойства, плейсхолдер ajaxToken и formit.js. Собственные формы FormIt на той же странице свой AJAX-режим сохраняют.

3.1.4 - 2026-09-09

Исправлено

  • Сообщения об успехе и о проверке не показывались при отправке через AJAX. Теперь они попадают в элементы формы [data-success] и [data-validation-error] (#15).
  • Ошибки полей FormIt из одних пробелов помечали форму как неуспешную (#14).
  • Предупреждение PHP 8 о неопределённом $_SESSION['fetchit_called'] (#13) и о неопределённом $_SESSION['FetchIt'].
  • GET-запрос к action.php не перенаправлялся.
  • successMessage из вызова сниппета не использовался в AJAX-ответе FormIt.

Изменено

  • Фронтенд собирается на Rollup 4.

3.1.3 - 2026-07-21

Исправлено

  • Фатальная ошибка Serialization of 'PDO' is not allowed на MODX 3.2.2 и PHP 8.3 (#17, #18). Свойства формы больше не хранят экземпляр FetchIt: свои сниппеты получают его через $modx->services->get('FetchIt').

3.1.2 - 2023-11-11

Добавлено

  • Ошибка reCAPTCHA v3 от FormIt возвращается как ошибка поля recaptcha (#6).

Исправлено

  • action.php не находил config.core.php, когда корень документов не совпадает с корнем MODX (#4).

3.1.1 - 2023-07-14

Исправлено

  • Фатальная ошибка на PHP 8 при добавлении скрипта на страницу.

3.1.0 - 2023-06-12

Добавлено

  • Настройка fetchit.frontend.default.notifier: ответы дополнительно показываются уведомлениями Notyf.

3.0.0 - 2023-06-06

Добавлено

  • Пакет для MODX 3 на основе FetchIt 1.0.1.

1.1.3 - 2026-08-12

Исправлено

  • Фатальная ошибка Serialization of 'PDO' is not allowed на PHP 8.3 (#17). Свойства формы больше не хранят экземпляр FetchIt: свои сниппеты получают его через $modx->getService('fetchit', 'FetchIt', MODX_CORE_PATH . 'components/fetchit/model/').
  • Сообщения об успехе и о проверке не показывались при отправке через AJAX (#11, #15). Теперь они попадают в элементы формы [data-success] и [data-validation-error]; своим чанкам нужны эти атрибуты вместо условий [[+fi.success:…]].
  • Ошибки полей FormIt из одних пробелов помечали форму как неуспешную (#10, #14).
  • Предупреждение PHP 8 о неопределённом $_SESSION['fetchit_called'] (#7, #9, #13) и о неопределённом $_SESSION['FetchIt'].
  • GET-запрос к action.php не перенаправлялся.
  • successMessage из вызова сниппета не использовался в AJAX-ответе FormIt (#5).

1.1.2 - 2023-11-11

Добавлено

  • Ошибка reCAPTCHA v3 от FormIt возвращается как ошибка поля recaptcha (#6).

1.1.1 - 2023-07-14

Исправлено

  • Фатальная ошибка на PHP 8 при добавлении скрипта на страницу.

1.1.0 - 2023-06-12

Добавлено

  • Настройка fetchit.frontend.default.notifier: ответы дополнительно показываются уведомлениями Notyf.

1.0.1 - 2023-03-25

Исправлено

  • Скрипт пропадал, когда сниппет вызывали из Fenom. Теперь плагин на OnWebPagePrerender добавляет его в ``.

1.0.0 - 2023-03-20

Исправлено

  • Неопределённая переменная $hash.

1.0.0-beta - 2023-02-23

Добавлено

  • Первый релиз: формы отправляются через Fetch API и обрабатываются FormIt или собственным сниппетом.

Последние обсуждения в сообществе MODX.pro