PHP 中的 hCaptcha:用 CapSkip SDK 和 Guzzle 识别

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

要在 PHP 中识别 hCaptcha,请安装 capskip/capskip,并用 sitekey 和页面地址调用 hcaptcha()。 CapSkip hCaptcha 识别工具 会返回一个 token,以及获得它时所用的 User-Agent。PHP 这边的难点在时钟:按 CapSkip 文档,一次识别需要 10 到 30 秒,SDK 在你不传 timeout 时最多等 300 秒,而 PHP 在 30 秒后会结束一个 Web 请求。本指南把超时设在这个限制之内,然后用 Guzzle 提交表单。

你需要什么

  • 一台运行 CapSkip 4.0.0 或更高版本的 Windows 机器,这是第一个支持 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 版本。我运行了 Windows 版 PHP 8.0.30、8.1.33、8.2.29、8.3.28、8.4.15 和 8.5.0,每个都分别搭配 Guzzle 7.16.1 和 Guzzle 8.3.0。
  • 一个由 hCaptcha 小组件保护、且你被允许自动化操作的表单,以及该小组件的 sitekey。
  • 访问 CapSkip 的途径。Local 模式只在它所运行的那台 PC 上响应(127.0.0.1)。Server 模式还会在你的网络地址或公网 IP 上响应。模式在 连接设置 中选择。
# In a PowerShell prompt, in the folder that will hold hcaptcha_form.php
composer require capskip/capskip guzzlehttp/guzzle

测试方式:针对我写的 in.php 和 res.php 模拟服务器,依据的是 API 文档中 hCaptcha 部分的内容,旁边还有一个假的注册页面。没有任何请求发往真实的 CapSkip 应用或 hCaptcha 站点,所以下面每个识别耗时都是模拟服务器的设置,页面的各项检查(每个 token 只能用一次、User-Agent 必须一致、两分钟有效期)则是我按文档规则写出来的。PHP 这一侧是真实的:SDK、Guzzle 和 Windows 上的 PHP,分别在命令行和内置 Web 服务器下运行,不是 Apache 或 IIS。hCaptcha 的 开发者文档 讲解了真实的验证过程。

第 1 步:用你自己的超时调用 hcaptcha()

把这四个 PHP 代码块按所示顺序放进名为 hcaptcha_form.php 的同一个文件。sitekey 可能是 h-captcha 容器上的 data-sitekey 属性、hcaptcha.render() 的 sitekey 选项,或者小组件 iframe 地址中的 sitekey= 参数。把它粘贴到 SITEKEY,并设置 PAGE_URL。

方法是 hcaptcha(string $sitekey, string $url, array $options = [])。options 数组接受键 "timeout"、"invisible"(1 或 true)、"data"(Enterprise 站点的 rqdata 值)、"userAgent" 和 "proxy"。在发送任何东西之前,SDK 会拒绝空的 sitekey、不是绝对 http 或 https 的页面地址、不是 0、1、true 或 false 的 invisible 值,以及 CapSkip 不接受的任何选项,其中包括 2Captcha 的 domain 选项。每次拒绝都是一个 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() 调用是阻塞的。它提交任务,然后轮询到 token 就绪或超时结束。Web 请求有 30 秒的 max_execution_time,而命令行没有限制:即使 php.ini 里写着 30,这里读到的命令行限制也是 0,而 PHP 内置 Web 服务器读到的是 30。我在 Windows 上使用了 5 秒的限制,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 秒的那次休眠返回的时候
在休眠外面包一个带 catch 和 finally 的 try 块两者都没有运行。register_shutdown_function 注册的函数运行了,error_get_last 里保存着那条消息
3 秒后调用 set_time_limit(5),然后休眠 4 秒没有错误。脚本总共运行了 7.0 秒
限制为 3 秒时,2 秒后调用 set_time_limit(0),然后休眠 5 秒没有错误。脚本总共运行了 7.0 秒

接下来有三条规则。PHP 从不打断休眠或 cURL 调用,而 SDK 在等待期间做的就只有这些。它只在控制权返回时才检查限制,所以一次等待可能超出限制整整一个等待长度。致命错误会跳过 catch 和 finally,所以你的任何处理代码都救不了这个任务。而且 set_time_limit 是重新开始计数,而不是累加。我只在 Windows 上运行过,而 set_time_limit 的 PHP 手册 说明其他系统不会把休眠或等待套接字的时间计算在内。

其余的由 SDK 的轮询决定,这是读它的源码并对照模拟服务器检验得出的。第一次轮询立刻发出,然后休眠 0.25 秒、0.5、1、2 和 4,之后每次轮询之间是 5 秒。超时是开始一次轮询的截止时间,而不是答案的截止时间。超时为 20 时,最后一次轮询在 17.8 秒发出,TimeoutException 在 22.9 秒出现,所以在 19 秒就绪的 token 根本没有被读取。超时为 0 时会回退到 SDK 的 defaultTimeout,即 120 秒,solve 函数避免了这一点。

因此 BUDGET 是你唯一能掌控的数字:一次注册为等待 token 最多愿意等多久,由所有尝试共同分享。第 4 步给 PHP 的是 BUDGET 加 30 秒,所以你的截止时间先触发,表现为你可以捕获的 TimeoutException,而不是你无法捕获的致命错误。请让 BUDGET 小于 PHP 前面任何 Web 服务器的超时,set_time_limit 对那些超时没有影响。CapSkip 也可能为了等一个空闲的 hCaptcha 线程而把任务挂起,在我读过的应用源码中最多 250 秒,所以如果你让很多识别排队,请随 PHP 的限制一起调大 BUDGET。

第 3 步:用 cookie jar 和正确的 User-Agent 提交表单

加载页面和提交表单必须看起来像同一个访客。除非你给 Guzzle 客户端一个 cookie jar,否则它不保存 cookie,所以 post_form 会构建一个带有新 CookieJar 的客户端,加载页面,并带着页面设置的 cookie 提交。

token 还属于某个浏览器身份。文档说,回复会指明 CapSkip 识别时使用的 User-Agent,表单必须在它之下提交。否则 Guzzle 会报出它自己的身份:省略这个头时,模拟服务器在页面加载中看到的是 GuzzleHttp/8(Guzzle 7 下是 GuzzleHttp/7),并拒绝了这次提交。在站点客户端上设置默认 User-Agent 就能覆盖这两个请求,所以这个客户端要在识别之后创建。"userAgent" 键改变不了这一点,因为文档说,CapSkip 只有在它与自己的浏览器一致时才会采用它。

提交时把页面地址作为 Referer 发送。Guzzle 不会添加它,而一些框架(Django 就是其中之一)会拒绝既没有 Referer 也没有 Origin 的 HTTPS 表单提交。带有这条规则的模拟站点在这个头出现之前一直返回 403。hidden_fields 函数会复制表单的隐藏输入,其中之一是 CSRF token。它的 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,Web 页面还会加上 504 或 502 状态码。它把 CapSkipError 和 RuntimeException 并列捕获,因为 SDK 的异常都继承 CapSkipError,而它不是 RuntimeException。

有些主机会禁用 set_time_limit,到那时致命错误就回来了。限制为 30 秒、BUDGET 保持 90 时,它在大约 33 秒时出现,位于 SDK 在大约 28 秒那次轮询之后的休眠里。BUDGET 为 29 同样失败,而 25 则在约 28 秒以 TimeoutException 结束。如果没有这个调用,请让 BUDGET 至少比限制小 10 秒。

只有 ERROR_CAPTCHA_UNSOLVABLE 值得新建任务。文档单独点出了 ERROR_RECAPTCHA_INVALID_SITEKEY 和 ERROR_PROXY_CONNECT_REFUSED,因为重新提交的任务会以同样的方式失败,所以它们会结束脚本。SDK 把 CapSkip 的回复文本放进 ApiException 消息,而应用源码把 JSON 错误构造成状态为 0、错误码放在 request 里的对象,所以代码用 str_contains 在消息中搜索。站点拒绝一次提交时,循环会请求新的 token,因为 token 只能用一次。低于 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 运行,Web 服务器那几行还在 8.4.15 上搭配 Guzzle 7 运行。其余的在全部六个版本上搭配两个 Guzzle 版本都运行过。

模拟设置脚本的表现
识别需要 12 秒,命令行轮询出现在 0、0.3、0.8、1.8、3.8、7.8 和 12.8 秒,然后表单在约 13 秒后被接受,状态 200
识别需要 38 秒,内置 Web 服务器,30 秒限制约 43 秒后返回状态 200,最后一次轮询在 42.9 秒
同上,但删除了 set_time_limit 调用约 33 秒后 PHP 出现致命错误。页面正文是 PHP 的错误文本,最后一次轮询在大约 28 秒发出
与第二行相同,但删除了该调用,并把 BUDGET 设为 25状态 504 和文本 out of time: timeout 24 exceeded,约 28 秒后
一个永远不会完成的任务,BUDGET 25,命令行TimeoutException、退出码 2 和消息 timeout 24 exceeded,约 28 秒后,最后一次轮询在 22.9 秒
前两次识别被拒绝第三个任务通过,error_log 里有两行记录
每次识别都被拒绝三行 attempt 输出,然后在三个任务之后出现 RuntimeException,没有向站点发出请求
第一次提交返回了 403请求了第二个 token,该次提交被接受
空 sitekey,或不是绝对地址的页面地址立刻出现 ValidationException。模拟服务器没有看到任务,站点也从未被联系过
轮询时返回 ERROR_PROXY_CONNECT_REFUSED脚本在第一个任务之后就停了,没有重试任何东西
CapSkip 端口上没有任何进程在监听约 2 秒后出现 NetworkException

在 PHP 中识别 hCaptcha 时的常见错误

400 和 403 的判定是我的模拟服务器的规则。账号类错误来自阅读 CapSkip 应用源码,我没有运行过它们。

你所看到的原因修复
Fatal error: Maximum execution time of 30 seconds exceededPHP 的限制在 SDK 的等待之中耗尽了。set_time_limit 调用缺失,或者主机禁用了该函数把这个调用保留在 sign_up 里。如果主机禁用了它,就让 BUDGET 至少比限制小 10 秒
out of time: timeout 89 exceeded(HTTP 504,退出码 2)TimeoutException:限制时间内没有 token 到达。CapSkip 还没有完成,或者任务仍在等待空闲线程在 CapSkip 的 Monitor 中查看该任务。只有当 PHP 前面的每一个超时都允许时,才调大 BUDGET
ValidationExceptionSDK 在任何请求离开 PHP 之前就停止了这次调用:空的 sitekey、相对的或非 http 的页面地址、不在 0、1、true 和 false 之内的 invisible 值,或者像 domain 这样的未知选项。消息会指出是哪一种修正消息中指出的那个参数
消息中含 ERROR_CAPTCHA_UNSOLVABLE 的 ApiException小组件没有通过提交一个新任务,sign_up 最多会这样做三次
带 ERROR_RECAPTCHA_INVALID_SITEKEY 的 ApiException按文档所说,hCaptcha 不接受这个页面的这个 sitekey重新复制 data-sitekey,并确认 PAGE_URL 是显示该小组件的页面
带有 ERROR_PROXY_CONNECT_REFUSED 的 ApiExceptionCapSkip 无法连接 proxy 选项中指定的代理检查代理的地址和类型,或者去掉 proxy 选项
带 ERROR_WRONG_USER_KEY 或 ERROR_KEY_DOES_NOT_EXIST 的 ApiExceptionCapSkip 正在检查密钥,而 "apiKey" 键缺失或有误把 CapSkip 期望的密钥作为构造函数数组的 "apiKey" 键传入
带 ERROR_NO_SLOT_AVAILABLE、ERROR_ZERO_BALANCE 或 ERROR_IP_NOT_ALLOWED 的 ApiExceptionCapSkip 密钥检查产生的账号类错误:密钥超出了请求速率限制,没有剩余额度可用于此方法,或者绑定到了使用另一个 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,而 SDK 的 Http.php 在每次向 CapSkip 发出请求之后仍然调用它。识别能正常进行,但在 display_errors 开启时,这条通知会出现在输出开头,所以 Web 页面再也拿不到它的 504 或 502 状态码在 error_reporting 中关闭 E_DEPRECATED,或者关闭 display_errors,直到 SDK 不再调用 curl_close
cURL error 60: SSL certificate problemWindows 版 PHP 发行时 curl.cainfo 是未设置的(这里的六个构建上都是空的),所以 Guzzle 访问 https 站点会失败。SDK 自己发往 CapSkip 的请求走的是 http,不受影响下载一个 cacert.pem 文件,例如从 curl.se,并在 php.ini 中把 curl.cainfo 设为它的路径
站点返回 400,没有会话 cookie提交时没有带上页面设置的 cookie通过同一个客户端、同一个 CookieJar 加载页面并提交
用新 token 仍然从站点得到 403提交带的是 Guzzle 自己的 User-Agent,或者 token 已被用过,或者已有约两分钟发送同一个结果里的 "userAgent" 项,每个 token 只用一次,识别后立刻发送
需要 Referer 的站点返回 403Guzzle 不发送它保留 post_form 里的 Referer 那一行

从 PHP 脚本访问 CapSkip 服务器

要让 CapSkip 离开运行 PHP 的 PC,就要更改构造函数数组里的主机和端口。Server 模式让其他设备能通过你的网络或公网 IP 访问 CapSkip,设置指南建议使用静态公网 IP。Server 模式启动时端口是对所有地址开放的。要把访问限制在你预期的机器上,请为其他地址添加一条 Windows Firewall 阻止规则。识别工具仍然留在你的硬件上,也没有任何计量。

常见问题

同一个 hcaptcha() 调用能处理隐形和 Enterprise 小组件吗?

可以。SDK 和 API 文档把两者都视为同一个方法再加一个额外字段:隐形小组件把 invisible 设为 1,Enterprise 站点把 rqdata 值放在 data 里,并且每个任务都重新请求。两者都放在 task_options 里。在模拟服务器上,它们都到达了 in.php,重试时发送的是新的 data 值。我没能在真实的 Enterprise 站点上测试。

PHP 中的 hCaptcha 应该在 Web 请求里运行,还是在命令行里运行?

命令行更简单。PHP 在那里没有限制,所以 BUDGET 是唯一的时钟,而且 Windows 任务计划程序可以按定时启动这个文件。如果有访客在等待,就让页面启动任务,由命令行 worker 来等待。

在 PHP 中识别 hCaptcha 需要代理吗?

测试时不需要。文档说,CapSkip 不会为 hCaptcha 强制使用代理,但来自同一个 IP 的持续识别请求,正是它的速率限制所要捕捉的。用量大时,请在 CapSkip 的设置中给它一个代理列表,或者传入 proxy 选项,即形如 login:password@IP:PORT 的字符串。它以 proxy 和 proxytype 的形式到达了模拟服务器。请用 Guzzle 的 proxy 选项从同一个地址提交表单。我没有测试过真实的代理。

在 PHP 中识别 hCaptcha,意味着一次带有你设定超时的 hcaptcha() 调用、任务顶部的一次 set_time_limit 调用,以及一个低于其他所有超时的 BUDGET。只重试 CapSkip 没能识别的任务,并在随 token 一起返回的 User-Agent 下提交。因为 CapSkip 是一个 无限量验证码识别工具 且采用统一授权定价,被拒绝的 token 只会让循环多跑一遍。至于其他验证码类型, PHP 验证码识别页面 列出了相应的 SDK 调用。 hCaptcha 演示 展示了小组件被通过的过程。