PHP 中的 hCaptcha:用 CapSkip SDK 和 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 exceeded | PHP 的限制在 SDK 的等待之中耗尽了。set_time_limit 调用缺失,或者主机禁用了该函数 | 把这个调用保留在 sign_up 里。如果主机禁用了它,就让 BUDGET 至少比限制小 10 秒 |
| out of time: timeout 89 exceeded(HTTP 504,退出码 2) | TimeoutException:限制时间内没有 token 到达。CapSkip 还没有完成,或者任务仍在等待空闲线程 | 在 CapSkip 的 Monitor 中查看该任务。只有当 PHP 前面的每一个超时都允许时,才调大 BUDGET |
| ValidationException | SDK 在任何请求离开 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 的 ApiException | CapSkip 无法连接 proxy 选项中指定的代理 | 检查代理的地址和类型,或者去掉 proxy 选项 |
| 带 ERROR_WRONG_USER_KEY 或 ERROR_KEY_DOES_NOT_EXIST 的 ApiException | CapSkip 正在检查密钥,而 "apiKey" 键缺失或有误 | 把 CapSkip 期望的密钥作为构造函数数组的 "apiKey" 键传入 |
| 带 ERROR_NO_SLOT_AVAILABLE、ERROR_ZERO_BALANCE 或 ERROR_IP_NOT_ALLOWED 的 ApiException | CapSkip 密钥检查产生的账号类错误:密钥超出了请求速率限制,没有剩余额度可用于此方法,或者绑定到了使用另一个 IP 地址的设备 | 检查 CapSkip 中该密钥的设置。对于速率限制,请等几秒再运行脚本 |
| NetworkException: Failed to connect to 127.0.0.1 port 8080 | 构造函数数组中的主机和端口上没有服务器应答 | 启动 CapSkip,然后把它的连接设置与数组对照。另一台机器上的脚本需要 Server 模式 |
| Deprecated: Function curl_close() is deprecated | PHP 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 problem | Windows 版 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 的站点返回 403 | Guzzle 不发送它 | 保留 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 演示 展示了小组件被通过的过程。
