Webman Turnstile 是一个专为 Webman 框架设计的 Composer 插件，用于简化 Cloudflare Turnstile 的后端验证流程。通过简单的配置和静态方法调用，您可以轻松地在 Webman 项目中集成 Turnstile 验证功能。
- 🚀 简单易用的静态方法调用
- ⚙️ 自动生成插件配置文件
- 🔒 安全的后端验证
- 📦 完全兼容 Webman 框架
- 🛠️ 支持自定义配置
- 🌐 自动获取客户端 IP 地址
使用 Composer 安装：
composer require zjkal/webman-turnstile安装完成后，插件会自动加载内置配置。若需要自定义，请在主项目创建 config/plugin/zjkal/turnstile/app.php 覆盖默认配置。
可选：在主项目创建并编辑 config/plugin/zjkal/turnstile/app.php 以覆盖默认配置：
<?php
return [
'enable' => true, // 设置为 false 可关闭 Turnstile 验证, 用于调试和开发
'secret_key' => 'your-turnstile-secret-key',
'timeout' => 30, // 验证超时时间（秒）
'verify_url' => 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
'verify_hostname' => false,
'allowed_hostnames' => [],
];enable: 是否启用 Turnstile 验证secret_key: Cloudflare Turnstile 的密钥timeout: HTTP 请求超时时间verify_url: Turnstile 验证接口地址verify_hostname: 是否验证返回的主机名allowed_hostnames: 当启用主机名验证时允许的主机名列表
💡 提示: 所有验证方法的 IP 参数都是可选的。如果不传入 IP 参数，系统会自动通过 Webman 的
request()助手函数获取客户端真实 IP 地址，让使用更加简便。
use plugin\\zjkal\\turnstile\\Turnstile;
$token = $request->post('cf-turnstile-response');
if (Turnstile::check($token)) {
// 验证通过
echo "验证成功！";
} else {
// 验证失败
echo "验证失败！";
}use plugin\\zjkal\\turnstile\\Turnstile;
// 验证 Turnstile token（IP 地址会自动获取）
$token = $request->post('cf-turnstile-response');
$result = Turnstile::verify($token);
if ($result['success']) {
// 验证成功
echo "验证通过！";
} else {
// 验证失败
echo "验证失败：" . implode(', ', $result['error-codes']);
}在您的 HTML 页面中添加 Turnstile 组件：
<!DOCTYPE html>
<html>
<head>
<title>Turnstile 验证</title>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
<form method="POST" action="/verify">
<!-- 其他表单字段 -->
<!-- Turnstile 组件 -->
<div class="cf-turnstile" data-sitekey="your-site-key"></div>
<button type="submit">提交</button>
</form>
</body>
</html>验证 Turnstile token 并返回详细结果。
参数：
$token(string): Turnstile 响应 token$remoteIp(string, 可选): 客户端 IP 地址，不传则自动从 request() 获取
use plugin\\zjkal\\turnstile\\Turnstile;
use plugin\\zjkal\\turnstile\\Exception\\TurnstileException;
try {
$result = Turnstile::verify($token);
// 处理验证结果...
} catch (TurnstileException $e) {
// 获取异常信息
$message = $e->getMessage();
$errorCodes = $e->getErrorCodes();
// 检查特定错误类型
if ($e->hasErrorCode('missing-secret-key')) {
// 处理密钥未配置的情况
error_log('Turnstile 密钥未配置');
} elseif ($e->hasErrorCode('network-error')) {
// 处理网络错误
error_log('Turnstile 网络请求失败');
}
// 返回错误响应给用户
return json(['error' => '验证服务暂时不可用，请稍后重试']);
}getMessage(): 获取异常消息getErrorCodes(): 获取错误代码数组getFirstErrorCode(): 获取第一个错误代码hasErrorCode($code): 检查是否包含特定错误代码
常见的 Turnstile 错误代码：
missing-input-secret: 缺少密钥参数invalid-input-secret: 无效的密钥missing-input-response: 缺少响应参数invalid-input-response: 无效的响应参数bad-request: 请求格式错误timeout-or-duplicate: 超时或重复提交internal-error: 内部错误
- ✅ Webman 1.x
- ✅ Webman 2.x
- 📋 PHP >= 7.4
MIT License
欢迎提交 Issue 和 Pull Request！
- 初始版本发布
- 支持基本的 Turnstile 验证功能
- 自动配置文件生成