yaleksandr89 / human-gate

v1.0.0 2026-11-09 19:12 UTC

Requires

• php: ^8.4
• ext-gd: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95.27
• phpstan/phpstan: ^2.2.16
• phpstan/phpstan-deprecation-rules: ^2.0.5
• phpunit/phpunit: ^13.3.5

MIT

• security
• captcha
• Challenge
• anti-bot
• spam-protection

Published on Packagist.org on 2026-11-09 19:33 UTC

README

Выберите язык

Русский	English	Español	中文	Français	Deutsch
Выбран	English	Español	中文	Français	Deutsch

Composer-пакет для создания капчи и проверки ответов в PHP-приложениях. Подходит для форм регистрации, обратной связи и отправки комментариев, где нужно сократить количество автоматических отправок.

Капча создаётся и проверяется на сервере без обращения к внешним сервисам. Пакет можно использовать с любым PHP-фреймворком или без него.

Для чего нужен пакет

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

Возможности

• Три вида капчи:
  • Текстовая капча (TextImage): ввод символов с изображения.
  • Выбор карточек (CategorySelection): поиск карточек нужной категории.
  • Последовательность значков (IconSequence): повторение порядка значков с изображения.
• Настройка срока действия капчи, числа неверных попыток и количества одновременно активных капч.
• Обновление капчи и защита от повторного использования правильного ответа.
• Готовое хранилище на основе стандартных сессий PHP.
• Реализация на PHP без сторонних Composer-зависимостей и внешних сервисов проверки. Внешний вид капчи задаётся самим приложением, поэтому пакет не навязывает оформление или средства разработки интерфейса.

Требования

• PHP ^8.4.
• Расширение ext-gd с поддержкой FreeType.
• Composer.

Установка

composer require yaleksandr89/human-gate

Быстрый старт

Ниже три примера создания капчи. В них используется PHP сессия: каждый пример сам открывает её через session_start() и сохраняет в ней данные проверки. Другой способ хранения можно подключить через ChallengeStore, как показано в руководстве по интеграции.

Скриншоты сделаны на alexanderyurchenko.ru и показывают один из вариантов оформления. Сам пакет отвечает за создание капчи и проверку ответов, фронт реализуется на стороне приложения самостоятельно.

Текстовая капча (TextImage)

Пользователь вводит шесть символов с изображения. Регистр букв по умолчанию не учитывается.

Показать PHP-пример создания текстовой капчи

<?php

declare(strict_types=1);

use Yaleksandr\HumanGate\Challenge\Policy;
use Yaleksandr\HumanGate\Challenge\Purpose;
use Yaleksandr\HumanGate\ChallengeService;
use Yaleksandr\HumanGate\Clock\SystemClock;
use Yaleksandr\HumanGate\Session\ActiveNativeSessionScope;
use Yaleksandr\HumanGate\Session\NativeSessionChallengeStore;
use Yaleksandr\HumanGate\TextImage\GdTextImageRenderer;
use Yaleksandr\HumanGate\TextImage\TextImageStrategy;

require 'vendor/autoload.php';

if (!session_start()) {
    throw new RuntimeException('Не удалось открыть сессию PHP.');
}

$service = new ChallengeService(
    new NativeSessionChallengeStore(ActiveNativeSessionScope::capture()),
    new Policy(),
    new SystemClock(),
    new TextImageStrategy(new GdTextImageRenderer()),
);

$result = $service->issue(new Purpose('contact.send'));
if ($result->challenge === null) {
    throw new RuntimeException('Не удалось создать капчу.');
}

$id = $result->challenge->id->value();
$presentation = $result->challenge->presentation;

Пример оформления текстовой капчи на сайте

Другие варианты: тёмная тема и мобильный экран

Тёмная тема на компьютере:

Светлая тема на телефоне:

Тёмная тема на телефоне:

Можно менять регистр, масштаб изображения, размытие, шум и поворот символов. Длина ответа всегда составляет шесть символов. Параметры текстовой капчи описаны отдельно.

Выбор карточек по категории (CategorySelection)

Пользователь выбирает все карточки нужной категории. Категории и названия карточек задаёт приложение, порядок выбора значения не имеет.

Показать PHP-пример создания капчи с выбором карточек

<?php

declare(strict_types=1);

use Yaleksandr\HumanGate\CategorySelection\CategorySelectionCategory;
use Yaleksandr\HumanGate\CategorySelection\CategorySelectionStrategy;
use Yaleksandr\HumanGate\Challenge\ChallengeKind;
use Yaleksandr\HumanGate\Challenge\Policy;
use Yaleksandr\HumanGate\Challenge\Purpose;
use Yaleksandr\HumanGate\ChallengeService;
use Yaleksandr\HumanGate\Clock\SystemClock;
use Yaleksandr\HumanGate\Session\ActiveNativeSessionScope;
use Yaleksandr\HumanGate\Session\NativeSessionChallengeStore;

require 'vendor/autoload.php';

if (!session_start()) {
    throw new RuntimeException('Не удалось открыть сессию PHP.');
}

$service = new ChallengeService(
    new NativeSessionChallengeStore(ActiveNativeSessionScope::capture()),
    new Policy(),
    new SystemClock(),
    new CategorySelectionStrategy([
        new CategorySelectionCategory('Фрукты', ['Яблоко', 'Груша', 'Слива', 'Персик']),
        new CategorySelectionCategory('Инструменты', ['Молоток', 'Пила', 'Отвёртка', 'Клещи']),
    ]),
);

$result = $service->issue(new Purpose('contact.send'), ChallengeKind::CategorySelection);
if ($result->challenge === null) {
    throw new RuntimeException('Не удалось создать капчу.');
}

$id = $result->challenge->id->value();
$presentation = $result->challenge->presentation;

Пример оформления капчи с выбором карточек на сайте

Другие варианты: тёмная тема и мобильный экран

Тёмная тема на компьютере:

Светлая тема на телефоне:

Тёмная тема на телефоне:

Настраиваются количество карточек и число правильных вариантов; список категорий задаёт приложение. Подробности настройки выбора карточек.

Последовательность значков (IconSequence)

Пользователь выбирает значки в том порядке, в котором они показаны на изображении. Здесь порядок выбора важен.

Показать PHP-пример создания капчи с последовательностью значков

<?php

declare(strict_types=1);

use Yaleksandr\HumanGate\Challenge\ChallengeKind;
use Yaleksandr\HumanGate\Challenge\Policy;
use Yaleksandr\HumanGate\Challenge\Purpose;
use Yaleksandr\HumanGate\ChallengeService;
use Yaleksandr\HumanGate\Clock\SystemClock;
use Yaleksandr\HumanGate\IconSequence\IconSequenceStrategy;
use Yaleksandr\HumanGate\Session\ActiveNativeSessionScope;
use Yaleksandr\HumanGate\Session\NativeSessionChallengeStore;

require 'vendor/autoload.php';

if (!session_start()) {
    throw new RuntimeException('Не удалось открыть сессию PHP.');
}

$service = new ChallengeService(
    new NativeSessionChallengeStore(ActiveNativeSessionScope::capture()),
    new Policy(),
    new SystemClock(),
    new IconSequenceStrategy(),
);

$result = $service->issue(new Purpose('contact.send'), ChallengeKind::IconSequence);
if ($result->challenge === null) {
    throw new RuntimeException('Не удалось создать капчу.');
}

$id = $result->challenge->id->value();
$presentation = $result->challenge->presentation;

Пример оформления капчи с последовательностью значков на сайте

Другие варианты: тёмная тема и мобильный экран

Тёмная тема на компьютере:

Светлая тема на телефоне:

Тёмная тема на телефоне:

Можно менять длину последовательности, число вариантов, размер значков, размытие, шум и поворот. Настройки последовательности значков.

Все виды капчи используют общие настройки срока действия и числа попыток. По умолчанию капча действует 180 секунд; время можно изменить через Policy::ttlSeconds.

Примеры выше показывают создание капчи. Полученные идентификатор и данные изображения или карточек приложение использует для показа проверки в своей форме. Отправка ответа, вызов ChallengeService::verify() и обновление капчи показаны в руководстве по интеграции.

Жизненный цикл капчи

По умолчанию капча действует три минуты. Отдельно установлен лимит неверных ответов: после третьей ошибки проверка завершается, даже если время ещё не истекло. Правильный ответ принимается только один раз. Подробнее о сроке действия, попытках и обновлении капчи.

Проверка на сервере

Human Gate хранит данные проверки на сервере и не передаёт браузеру правильный ответ. Каждая капча связана с конкретной формой или операцией через ключ Purpose: например, капчу для отправки сообщения нельзя использовать для регистрации. Подробнее о проверке и хранении данных.

Обратная связь

• Воспроизводимые ошибки — GitHub Issues.

Если пакет оказался полезен, поставьте звезду на GitHub — так его будет проще найти другим разработчикам. 🤘