# GateForm для WordPress

[GateForm](https://gateform.ru) — капча и защита форм от спама и ботов.
Плагин объединяет две возможности:

- **капча** для WordPress, Contact Form 7, WPForms, Gravity Forms, Ninja Forms,
  Elementor Pro Forms, Formidable Forms, Fluent Forms и WooCommerce;
- **виджет связи** GateForm: автоматически размещается в подвале сайта при указании `ID виджета связи`.

Секретный ключ остаётся на сервере, значения полей формы никуда не передаются.
Виджету связи нужен только публичный идентификатор `w_...`.

- Сайт: <https://gateform.ru>
- Документация: <https://gateform.ru/docs>
- Поддержка: <info@gateform.ru>

## Возможности

### Капча

- защита комментариев;
- защита входа в админку и на сайт (`wp-login.php`);
- защита регистрации;
- Contact Form 7: тег `[gateform]`, проверка через `wpcf7_validate`;
- WPForms, Gravity Forms, Ninja Forms, Elementor Pro Forms,
  Formidable Forms, Fluent Forms;
- WooCommerce: оформление заказа, вход и регистрация;
- свои CSS-селекторы форм;
- режим **fail-open**: при недоступности сервиса формы продолжают работать;
- без внешних библиотек и CDN — только `client.js` с `https://gateform.ru`;
- IP-адреса посетителей не сохраняются.

### Виджет связи

Укажите `ID виджета связи` (`w_...`) в настройках плагина — код виджета
`<script src="https://gateform.ru/widget.js" data-widget-id="..." defer></script>`
будет сразу автоматически размещаться в подвале всех публичных страниц сайта.
Также доступен шорткод `[gateform_widget]` (или `[gateform_widget id="w_..."]`).

## Требования

- WordPress **6.2+**
- PHP **8.1+**
- HTTPS на сайте (рекомендуется)
- Аккаунт GateForm и ключ проверки с указанным доменом сайта
- Contact Form 7, WooCommerce и другие плагины — опционально

## Установка

1. Скопируйте папку `gateform` в `/wp-content/plugins/` или загрузите ZIP через
   «Плагины → Добавить новый → Загрузить плагин».
2. Активируйте плагин в разделе «Плагины».
3. Откройте «Настройки → GateForm».
4. Заполните:
   - **Публичный ключ** (`site_key`) — вида `gf_site_...`;
   - **Секретный ключ** (`secret_key`) — вида `gf_sec_...`;
   - какие формы защищать;
   - при необходимости — **ID виджета связи** (`w_...`), чтобы код виджета сразу выводился в подвале сайта.
5. Сохраните настройки.

Для входа в админку отдельная настройка не нужна: `/wp-admin` использует
`wp-login.php`, поэтому включённый пункт «Вход в админку и на сайт» защищает
и админку, и обычный вход.

Домен сайта должен быть добавлен в список доменов ключа в личном кабинете
GateForm. Если домены не указаны, ключ разрешён на всех доменах.

## Contact Form 7

1. Включите «Contact Form 7» в настройках плагина.
2. Добавьте в форму тег `[gateform]`:

   ```text
   [text* your-name]
   [email* your-email]
   [textarea your-message]
   [gateform]
   [submit "Отправить"]
   ```

   Тег выводит скрытое поле `gf_token` и подпись «Защищено GateForm» со ссылкой
   на сайт и логотипом.

3. Если тег не добавлен, `client.js` подключится к `form.wpcf7-form`
   автоматически, добавит поле токена и подпись в конец формы.

Проверка выполняется фильтром `wpcf7_validate` до отправки письма. При отказе
форма показывает сообщение об ошибке и не отправляет письмо.

Подпись можно отключить фильтром:

```php
add_filter('gateform_cf7_branding', '__return_false');
```

## Как это работает

Плагин выводит в подвале страницы тег:

```html
<script src="https://gateform.ru/client.js"
        data-site-key="gf_site_..."
        data-form="#commentform, form.wpcf7-form"
        data-token-name="gf_token"
        data-consent-position="before-submit"
        defer></script>
```

`client.js`:

1. собирает поведенческие сигналы (движения указателя, нажатия клавиш, время заполнения);
2. запрашивает одноразовый токен;
3. добавляет в форму скрытое поле `gf_token`;
4. добавляет видимую галочку «Я не робот» со ссылками на согласие и политику.

Положение галочки выбирается в настройках плагина: в начале формы, перед кнопкой
отправки, после кнопки или в конце формы. Для точечного размещения можно
переопределить его атрибутом `data-consent-target="#selector"`.

При отправке формы плагин проверяет токен через `POST /api/v1/validate`
и только после успешной проверки пропускает заявку.

Токен одноразовый: повторная проверка вернёт `TOKEN_ALREADY_USED`.

## Режим fail-open

По умолчанию плагин работает **fail-closed**: если сервис проверки недоступен,
форма отклоняется. Это безопаснее.

Если важнее не терять заявки при сбое, включите
«Принимать формы без проверки (fail-open)». Тогда при сетевой ошибке, таймауте,
HTTP 5xx или 429 форма будет принята.

Неверный секретный ключ (`INVALID_CREDENTIALS`) никогда не приводит к fail-open:
это ошибка настройки.

## Хуки и фильтры

| Хук | Назначение |
| --- | --- |
| `pre_comment_on_post` | Проверка токена перед комментарием |
| `authenticate` | Проверка токена при входе |
| `registration_errors` | Проверка токена при регистрации |
| `wpcf7_validate` | Contact Form 7 |
| `wpforms_process` | WPForms |
| `gform_validation` | Gravity Forms |
| `ninja_forms_submit_data` | Ninja Forms |
| `elementor_pro/forms/validation` | Elementor Pro Forms |
| `frm_validate_entry` | Formidable Forms |
| `fluentform/validation_errors` | Fluent Forms |
| `woocommerce_checkout_process` | WooCommerce checkout |
| `woocommerce_login_errors` | WooCommerce login |
| `woocommerce_registration_errors` | WooCommerce registration |
| `wp_footer` | Подключение `client.js` к формам на сайте |
| `login_footer` | Подключение `client.js` к `wp-login.php` |

Для собственной формы можно добавить серверную проверку через фильтр:

```php
add_filter('gateform_validate_token', function (array $result, string $context, string $token): array {
    if ($context === 'my_form' && !$result['valid']) {
        $result['message'] = 'Подтвердите, что вы человек.';
    }

    return $result;
}, 10, 3);
```

CSS-селектор своей формы добавьте в настройках плагина, чтобы `client.js`
вставил в неё скрытое поле `gf_token`.

## Брендинг

Ссылка на [gateform.ru](https://gateform.ru) и логотип выводятся:

- в шапке страницы настроек;
- в теге `[gateform]` Contact Form 7;
- в форме CF7 без тега (подпись добавляется в конец формы).

Логотип загружается с домена GateForm (`/logo-mark.svg`). Если сайт использует
строгую CSP, разрешите `img-src https://gateform.ru`.

## Ограничения

- Плагин не защищает XML-RPC и REST API.
- При включённом кэшировании страниц скрипт всё равно подключается:
  токен запрашивается в момент отправки формы.
- Для AJAX-форм некоторых плагинов токен должен попадать в `$_POST`.
  Поддерживаемые интеграции читают его из стандартного POST.
- Виджеты не привязаны к домену и не требуют ключа проверки.

## Лицензия

MIT. См. [LICENSE](LICENSE).

Разработчик: **GateForm** — <https://gateform.ru>
