hCaptcha на PHP: решение через CapSkip SDK и Guzzle

hcaptcha in php - hCaptcha in PHP: Solve It With the CapSkip SDK and Guzzle

Чтобы решить hCaptcha на PHP, установите capskip/capskip и вызовите hcaptcha() с sitekey и адресом страницы. Вызов уходит в решатель hCaptcha в CapSkip и возвращает токен вместе с User-Agent, с которым он получен. Для PHP важнее всего время: по документации CapSkip решение занимает от 10 до 30 секунд, SDK ждёт до 300, если вы не передадите тайм-аут, а PHP завершает веб-запрос через 30. В этом руководстве тайм-аут вписан в этот предел, а затем форма отправляется через Guzzle.

Что понадобится

  • Машина с Windows и CapSkip 4.0.0 или новее: это первая версия, которая работает с hCaptcha.
  • Composer и PHP 8.0.2 или новее с включёнными расширениями curl и json. SDK требует 8.0, а на 8.0.30 проверка платформы в Composer для SDK вместе с Guzzle показывает 8.0.2. Метод hcaptcha появился в SDK версии 1.6.0. Я запускал PHP 8.0.30, 8.1.33, 8.2.29, 8.3.28, 8.4.15 и 8.5.0 для Windows, каждый с Guzzle 7.16.1 и с Guzzle 8.3.0.
  • Форма с виджетом hCaptcha, которую вам разрешено автоматизировать, и sitekey этого виджета.
  • Способ связаться с CapSkip. Режим Local отвечает только на ПК, где он запущен (127.0.0.1). Режим Server отвечает ещё и в вашей сети или на публичном IP. Режим выбирается в разделе Настройки подключения приложения CapSkip.
# In a PowerShell prompt, in the folder that will hold hcaptcha_form.php
composer require capskip/capskip guzzlehttp/guzzle

Как проверялось: на имитации in.php и res.php, которую я написал по разделу hCaptcha на странице CapSkip с названием Документация API, рядом с ней поддельная страница регистрации. Ни один запрос не ушёл в настоящее приложение CapSkip или на сайт hCaptcha, поэтому каждое время решения ниже задано настройкой имитации, а проверки страницы (одно использование на токен, совпадающий User-Agent, срок жизни две минуты) воспроизводят правила документации так, как я их закодировал. Часть на PHP настоящая: SDK, Guzzle и PHP на Windows, в командной строке и во встроенном веб-сервере, а не в Apache или IIS. Материалы из документации для разработчиков hCaptcha охватывают настоящую проверку.

Шаг 1: вызов hcaptcha() с собственным тайм-аутом

Поместите четыре блока PHP в один файл hcaptcha_form.php в показанном порядке. Sitekey находится в атрибуте data-sitekey контейнера h-captcha, в параметре sitekey у hcaptcha.render() или в параметре sitekey= в адресе iframe виджета. Вставьте его в SITEKEY и задайте PAGE_URL.

Метод выглядит так: hcaptcha(string $sitekey, string $url, array $options = []). Массив options принимает ключи "timeout", "invisible" (1 или true), "data" (значение rqdata сайта Enterprise), "userAgent" и "proxy". Перед отправкой чего-либо SDK отклоняет пустой sitekey, адрес страницы не в абсолютном виде с http или https, значение invisible, отличное от 0, 1, true или false, и любой параметр, которого CapSkip не принимает, включая параметр domain из 2Captcha. Каждый такой отказ оформляется как ValidationException.

Возвращаемый массив содержит запись "token" для h-captcha-response и g-recaptcha-response, запись "code" с той же строкой, запись "userAgent" и запись "captchaId". Запись "respKey" содержит второе значение hCaptcha, пустое, если его нет, и большинство сайтов его не читает. Ключи invisible и data задаются в функции task_options, и она выполняется для каждого задания, потому что значение rqdata одноразовое. При включённой API Key Validation добавьте ключ "apiKey" в массив конструктора.

<?php
// hcaptcha_form.php: run it with php hcaptcha_form.php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use CapSkip\CapSkip;
use CapSkip\Exceptions\ApiException;
use CapSkip\Exceptions\CapSkipError;
use CapSkip\Exceptions\TimeoutException;
use GuzzleHttp\Client;
use GuzzleHttp\Cookie\CookieJar;

const PAGE_URL = 'https://example.com/signup';  // the page that shows the widget
const SITEKEY = 'YOUR_SITEKEY';  // the data-sitekey of its h-captcha div
const BUDGET = 90;  // seconds one sign-up may spend waiting for tokens

// Local mode. In Server mode, use your server's address instead. With API Key
// Validation on, add 'apiKey' => 'YOUR_KEY' to this array.
$solver = new CapSkip(['host' => '127.0.0.1', 'port' => 8080]);

// Extra task options, asked for on every task, so a fresh value fits here.
//   invisible widget:  return ['invisible' => 1];
//   Enterprise rqdata: return ['data' => fetch_rqdata()];  (your own function)
function task_options(): array
{
    return [];
}

function solve(CapSkip $solver, float $deadline): array
{
    $left = (int) floor($deadline - microtime(true));
    if ($left < 10) {
        // Not enough time for a solve. A timeout of 0 would mean the SDK default.
        throw new TimeoutException('the budget is used up');
    }
    // Waits for the token. The result holds token (for h-captcha-response and
    // g-recaptcha-response), code (the same string), userAgent (the browser
    // identity of the token), respKey (empty when there is none) and captchaId.
    return $solver->hcaptcha(SITEKEY, PAGE_URL, ['timeout' => $left] + task_options());
}

Шаг 2: ожидание в пределах лимита времени PHP

Вызов hcaptcha() блокирует выполнение. Он отправляет задание, затем опрашивает результат, пока токен не будет готов или не закончится тайм-аут. Веб-запросу даётся 30 секунд max_execution_time, а командной строке не даётся ничего: её лимит здесь читался как 0, даже когда в php.ini стояло 30, тогда как встроенный веб-сервер PHP читал 30. Я использовал лимит в 5 секунд на Windows, и PHP 8.0.30, 8.4.15 и 8.5.0 вели себя одинаково.

Что я запускал при лимите в 5 секундЧто произошло
Одна пауза в 10 секундФатальная ошибка пришла через 10.0 секунды, когда пауза завершилась
Паузы шагами по 0.25 секундыФатальная ошибка пришла через 5.2 секунды
Вызов hcaptcha() для задания, которое так и не завершилосьФатальная ошибка пришла через 7.8 секунды, когда завершилась пауза SDK с 3.8 до 7.8 секунды
Блок try с catch и finally вокруг паузыНи один не выполнился. Функция из register_shutdown_function выполнилась, и error_get_last содержал сообщение
set_time_limit(5) через 3 секунды, затем пауза в 4 секундыОшибки нет. Скрипт работал 7.0 секунды в сумме
set_time_limit(0) через 2 секунды при лимите в 3 секунды, затем пауза в 5 секундОшибки нет. Скрипт работал 7.0 секунды в сумме

Отсюда три правила. PHP никогда не прерывает паузу или вызов cURL, а только это SDK и делает, пока ждёт. Он проверяет лимит, когда управление возвращается, поэтому ожидание может превысить лимит на всю свою длину. Фатальная ошибка пропускает catch и finally, поэтому никакой ваш обработчик не спасёт задание. И set_time_limit перезапускает счётчик, а не добавляет к нему. Я запускал только на Windows, а в руководстве по PHP для set_time_limit сказано, что в других системах время сна и ожидания на сокете не учитывается.

Остальное определяет опрос в SDK, как видно из его исходного кода и проверено на имитации. Первый опрос уходит сразу, затем SDK ждёт 0.25 секунды, 0.5, 1, 2 и 4, а после этого по 5 между опросами. Тайм-аут задаёт крайний срок для начала опроса, а не для ответа. При тайм-ауте 20 последний опрос ушёл через 17.8 секунды, а TimeoutException пришёл через 22.9, поэтому токен, ставший готовым через 19 секунд, так и не был прочитан. Тайм-аут 0 откатывается к defaultTimeout SDK в 120 секунд, чего функция solve избегает.

BUDGET остаётся единственным числом, которым распоряжаетесь вы: сколько регистрация может ждать токены, общее для всех попыток. Шаг 4 даёт PHP время BUDGET плюс 30 секунд, поэтому ваш срок срабатывает первым, как TimeoutException, который можно перехватить, а не как фатальная ошибка, которую перехватить нельзя. Держите BUDGET меньше любого тайм-аута веб-сервера перед PHP, которого set_time_limit не касается. CapSkip может также удерживать задание в ожидании свободного потока hCaptcha, в исходном коде приложения, который я читал, до 250 секунд, поэтому увеличивайте BUDGET вместе с лимитом PHP, если ставите в очередь много решений.

Шаг 3: отправка формы с хранилищем cookie и правильным User-Agent

Загрузка страницы и отправка формы должны выглядеть как один посетитель. Клиент Guzzle не хранит cookie, пока вы не дадите ему хранилище, поэтому post_form создаёт клиент с новым CookieJar, загружает страницу и отправляет форму с cookie, которые установила страница.

Токен также привязан к идентичности браузера. В документации сказано, что в ответе назван User-Agent, с которым решал CapSkip, и форму нужно отправлять именно с ним. Иначе Guzzle представится сам: имитация видела GuzzleHttp/8 (GuzzleHttp/7 при Guzzle 7) при загрузке страницы, когда заголовок был пропущен, и отклоняла отправку. User-Agent по умолчанию у клиента сайта покрывает оба запроса, поэтому этот клиент создаётся после решения. Ключ "userAgent" этого не меняет, потому что в документации сказано, что CapSkip использует его, только если он совпадает с его собственным браузером.

Отправка указывает адрес страницы как Referer. Guzzle не добавляет его, а некоторые фреймворки, включая Django, отклоняют отправку формы по HTTPS без Referer и Origin. Имитация сайта с таким правилом отвечала 403, пока заголовка не было. Функция hidden_fields копирует скрытые поля формы, например токен CSRF. Префикс loadHTML заставляет libxml читать UTF-8: без него на странице без тега meta charset буква с диакритическим знаком в скрытом значении приходила искажённой, и имитация отклоняла отправку. Виджет заполняет и h-captcha-response, и g-recaptcha-response, поэтому код отправляет оба.

function hidden_fields(string $html): array
{
    $doc = new DOMDocument();
    libxml_use_internal_errors(true);
    // The prefix makes libxml read the page as UTF-8 even without a meta tag.
    $doc->loadHTML('<?xml encoding="UTF-8">' . $html);
    $fields = [];
    foreach ((new DOMXPath($doc))->query('//form//input[@type="hidden"][@name]') as $input) {
        $fields[$input->getAttribute('name')] = $input->getAttribute('value');
    }
    return $fields;
}

function post_form(array $solved, string $email): int
{
    // The SDK adds userAgent only when CapSkip's reply names one. Never fall
    // back to Guzzle's own: the token belongs to the browser that earned it.
    $userAgent = $solved['userAgent'] ?? throw new RuntimeException('CapSkip named no User-Agent');
    // One client for the page load and the post: its jar keeps the session
    // cookie, and its default header is the User-Agent the token was earned with.
    $site = new Client([
        'cookies' => new CookieJar(),
        'headers' => ['User-Agent' => $userAgent],
        'http_errors' => false,
        'timeout' => 20,
    ]);
    $page = $site->get(PAGE_URL);
    if ($page->getStatusCode() !== 200) {
        throw new RuntimeException('GET ' . PAGE_URL . ' answered ' . $page->getStatusCode());
    }
    $fields = hidden_fields((string) $page->getBody());  // the csrf field, for one
    $fields['email'] = $email;  // your form's own fields go here
    $fields['h-captcha-response'] = $solved['token'];
    $fields['g-recaptcha-response'] = $solved['token'];  // the widget fills both
    // Post to the form's action address; here that is the page itself.
    return $site->post(PAGE_URL, [
        'form_params' => $fields,
        'headers' => ['Referer' => PAGE_URL],
    ])->getStatusCode();
}

Шаг 4: регистрация с повторами и запуск

Функция sign_up сначала занимается временем. Если у PHP есть лимит и существует set_time_limit, она перезапускает счётчик на BUDGET плюс 30 секунд: запас на последнюю паузу SDK и отправку формы. В командной строке, где лимит равен 0, она ничего не меняет. Следующая попытка начинается, только если остаётся 10 секунд бюджета. Последний блок выбирает выход: 2 при нехватке времени, 1 при любой другой неудаче, а для веб-страницы ещё статус 504 или 502. Он перехватывает CapSkipError и RuntimeException рядом друг с другом, потому что все исключения SDK наследуют CapSkipError, который не является RuntimeException.

Некоторые хосты отключают set_time_limit, и тогда фатальная ошибка возвращается. При лимите в 30 секунд и BUDGET, оставленном равным 90, она пришла примерно через 33 секунды, во время паузы SDK после его опроса примерно на 28-й секунде. BUDGET, равный 29, провалился так же, а 25 завершился TimeoutException примерно через 28 секунд. Без этого вызова держите BUDGET минимум на 10 секунд меньше лимита.

Новое задание получает только ERROR_CAPTCHA_UNSOLVABLE. В документации ERROR_RECAPTCHA_INVALID_SITEKEY и ERROR_PROXY_CONNECT_REFUSED названы отдельно, потому что повторно отправленное задание закончилось бы так же, поэтому они завершают скрипт. SDK помещает текст ответа CapSkip в сообщение ApiException, а исходный код приложения строит ошибку JSON как объект со status 0 и кодом в request, поэтому наш код ищет его в сообщении через str_contains. Когда сайт отклоняет отправку, цикл просит новый токен, ведь токен работает один раз. Статус ниже 400 лишь значит, что сайт не отклонил запрос, поэтому проверяйте и текст, который бывает только при успехе.

function sign_up(CapSkip $solver, string $email): int
{
    $deadline = microtime(true) + BUDGET;
    // A limit of 0 means none, as on the command line. Otherwise restart PHP's
    // clock with room to spare, so the SDK's TimeoutException fires first, not
    // PHP's fatal error. Some hosts disable set_time_limit; then keep BUDGET
    // at least 10 seconds under the limit instead.
    if ((int) ini_get('max_execution_time') !== 0 && function_exists('set_time_limit')) {
        set_time_limit(BUDGET + 30);
    }
    for ($attempt = 1; $attempt <= 3; $attempt++) {
        try {
            $solved = solve($solver, $deadline);
        } catch (ApiException $e) {
            if (!str_contains($e->getMessage(), 'ERROR_CAPTCHA_UNSOLVABLE')) {
                throw $e;  // a refused sitekey or an unreachable proxy would fail again
            }
            error_log("attempt $attempt: ERROR_CAPTCHA_UNSOLVABLE, new task");
            continue;
        }
        $status = post_form($solved, $email);
        if ($status < 400) {
            return $status;
        }
        error_log("attempt $attempt: the site answered $status, new token");
    }
    throw new RuntimeException('no accepted form after 3 attempts');
}
try {
    $status = sign_up($solver, '[email protected]');
    echo "the site answered $status\n";
} catch (TimeoutException $e) {
    if (!headers_sent()) {
        http_response_code(504);  // no effect on the command line
    }
    echo 'out of time: ', $e->getMessage(), "\n";
    exit(2);
} catch (CapSkipError | RuntimeException $e) {
    if (!headers_sent()) {
        http_response_code(502);
    }
    echo get_class($e), ': ', $e->getMessage(), "\n";
    exit(1);
}
# From the same PowerShell prompt, in the folder that holds the file
php hcaptcha_form.php

Вот как файл вёл себя на имитации. Первые пять строк запускались на PHP 8.0.30, 8.4.15 и 8.5.0 с Guzzle 8, а строки с веб-сервером также на 8.4.15 с Guzzle 7. Остальные запускались на всех шести версиях с обеими версиями Guzzle.

Настройка имитацииЧто сделал скрипт
Решение занимает 12 секунд, командная строкаОпросы на 0, 0.3, 0.8, 1.8, 3.8, 7.8 и 12.8 секунды, затем форма принята со статусом 200 примерно через 13 секунд
Решение занимает 38 секунд, встроенный веб-сервер, лимит 30 секундСтатус 200 примерно через 43 секунды, последний опрос на 42.9
То же, но с удалённым вызовом set_time_limitФатальная ошибка PHP примерно через 33 секунды. Тело страницы содержало текст ошибки PHP, а последний опрос ушёл примерно на 28-й секунде
То же, что во второй строке, но с удалённым вызовом и BUDGET, равным 25Статус 504 и текст out of time: timeout 24 exceeded примерно через 28 секунд
Задание, которое никогда не завершается, BUDGET 25, командная строкаTimeoutException, код выхода 2 и сообщение timeout 24 exceeded примерно через 28 секунд, последний опрос на 22.9
Первые два решения отклоненыТретье задание прошло, после двух строк в error_log
Каждое решение отклоненоТри строки с попытками, затем RuntimeException после трёх заданий, без запроса к сайту
Первая отправка получила ответ 403Запрошен второй токен, и эта отправка принята
Пустой sitekey или адрес страницы не в абсолютном видеValidationException сразу. Имитация не получила ни одного задания, к сайту не обращались
ERROR_PROXY_CONNECT_REFUSED при опросеСкрипт остановился после первого задания и ничего не повторял
На порту CapSkip никто не слушаетNetworkException примерно через 2 секунды

Частые ошибки при решении hCaptcha на PHP

Ответы 400 и 403 следуют правилам моей имитации. Ошибки аккаунта взяты из чтения исходного кода приложения CapSkip, и я их не запускал.

Что вы видитеПричинаИсправить
Fatal error: Maximum execution time of 30 seconds exceededЛимит PHP закончился во время ожидания в SDK. Вызова set_time_limit нет, либо хост отключил эту функциюОставьте вызов в sign_up. Если хост его отключил, задайте BUDGET минимум на 10 секунд меньше лимита
out of time: timeout 89 exceeded (HTTP 504, код выхода 2)TimeoutException: токен не пришёл за тайм-аут. CapSkip не закончил, либо задание всё ещё ждало свободного потокаНайдите задание на вкладке Monitor в CapSkip. Увеличивайте BUDGET, только если это позволяет каждый тайм-аут перед PHP
ValidationExceptionSDK остановил вызов до того, как какой-либо запрос покинул PHP: пустой sitekey, относительный адрес страницы или адрес не по http, значение invisible вне 0, 1, true и false либо неизвестный параметр вроде domain. В сообщении сказано, какой именноИсправьте аргумент, который назван в сообщении
ApiException, в сообщении которого есть ERROR_CAPTCHA_UNSOLVABLEВиджет не был пройденОтправьте новое задание, что sign_up делает до трёх раз
ApiException с ERROR_RECAPTCHA_INVALID_SITEKEYhCaptcha не принял этот sitekey для этой страницы, по документацииСкопируйте data-sitekey заново и убедитесь, что PAGE_URL указывает на страницу, на которой показан виджет
ApiException с ERROR_PROXY_CONNECT_REFUSEDCapSkip не может подключиться к прокси, указанному в параметре proxyПроверьте адрес и тип прокси или уберите параметр proxy
ApiException с ERROR_WRONG_USER_KEY или ERROR_KEY_DOES_NOT_EXISTCapSkip проверяет ключи, а ключ "apiKey" отсутствует или неверенПередайте ключ, который ожидает CapSkip, как ключ "apiKey" массива конструктора
ApiException с ERROR_NO_SLOT_AVAILABLE, ERROR_ZERO_BALANCE или ERROR_IP_NOT_ALLOWEDОшибки аккаунта из проверок ключей в CapSkip: у ключа превышен лимит частоты запросов, для этого метода не осталось кредитов, либо он привязан к устройству с другим IP-адресомПроверьте настройки ключа в CapSkip. При превышении лимита частоты запросов подождите несколько секунд и запустите скрипт снова
NetworkException: Failed to connect to 127.0.0.1 port 8080По хосту и порту из массива конструктора ни один сервер не отвечаетЗапустите CapSkip, затем сравните его настройки подключения с массивом. Скрипту на другой машине нужен режим Server
Deprecated: Function curl_close() is deprecatedPHP 8.5 помечает curl_close как устаревшую, а файл Http.php в SDK по-прежнему вызывает её после каждого запроса к CapSkip. Решение работает, но при включённом display_errors уведомление открывает вывод, поэтому веб-страница больше не может получить статус 504 или 502Отключите E_DEPRECATED в error_reporting или отключите display_errors, пока SDK не откажется от curl_close
cURL error 60: SSL certificate problemPHP для Windows поставляется с незаданным curl.cainfo (он был пустым на всех шести сборках здесь), поэтому Guzzle даёт сбой на сайте по https. Собственные запросы SDK идут к CapSkip по http и это не затрагиваетСкачайте файл cacert.pem, например с curl.se, и укажите путь к нему в curl.cainfo в php.ini
400 от сайта, нет cookie сеансаОтправка ушла без cookie, которую установила страницаЗагружайте страницу и отправляйте форму через один клиент с одним CookieJar
403 от сайта при свежем токенеОтправка несла собственный User-Agent Guzzle, либо токен уже использовался или ему было около двух минутОтправляйте запись "userAgent" из того же результата, один раз на токен, сразу после решения
403 от сайта, которому нужен RefererGuzzle его не отправляетОставьте строку с Referer в post_form

Обращение к серверу CapSkip из вашего скрипта PHP

Чтобы вынести CapSkip с ПК, на котором работает PHP, нужно изменить хост и порт в массиве конструктора. Режим Server позволяет другим устройствам обращаться к CapSkip в вашей сети или по публичному IP, а руководство по настройке рекомендует статический. Режим Server запускается с портом, открытым для всех адресов. Чтобы оставить доступ только нужным машинам, добавьте блокирующее правило Windows Firewall для остальных. Решатель остаётся на вашем оборудовании, и никакого счётчика нет.

FAQ

Подходит ли тот же вызов hcaptcha() для невидимых виджетов и виджетов Enterprise?

Да. SDK и документация API считают оба случая одним и тем же методом с дополнительным полем: invisible, равное 1, для невидимого виджета и значение rqdata в data для сайта Enterprise, запрашиваемое заново для каждого задания. Добавьте любое из них в task_options. На имитации оба дошли до in.php, а повтор отправил новое значение data. Настоящий сайт Enterprise я проверить не мог.

Где запускать hCaptcha на PHP: в веб-запросе или в командной строке?

Командная строка проще. Там у PHP нет лимита, поэтому единственными часами остаётся BUDGET, а Планировщик заданий Windows может запускать файл по таймеру. Если посетитель ждёт, пусть страница запускает задание, а ждёт его воркер в командной строке.

Нужен ли прокси для решения hCaptcha на PHP?

Для теста не нужен. В документации сказано, что CapSkip не навязывает прокси для hCaptcha, но постоянный поток решений с одного IP как раз и должны ловить её лимиты частоты запросов. При большом объёме дайте CapSkip список прокси в его настройках или передайте параметр proxy, строку вида login:password@IP:PORT. На имитации он пришёл как proxy и proxytype. Отправляйте форму с того же адреса через параметр proxy в Guzzle. Настоящий прокси я не проверял.

Решение hCaptcha на PHP сводится к одному вызову hcaptcha() с заданным вами тайм-аутом, вызову set_time_limit в начале задания и значению BUDGET меньше любого другого тайм-аута. Повторяйте только то, что CapSkip не смог решить, а форму отправляйте с тем User-Agent, который пришёл вместе с токеном. Поскольку CapSkip предоставляет безлимитный сервис распознавания капчи по фиксированной лицензии, отклонённый токен стоит лишь ещё одного прохода по циклу. На странице сервиса распознавания капчи для PHP описаны вызовы SDK для других типов CAPTCHA, а в демо hCaptcha видно, как виджет проходит проверку.