包简介

Cloudflare Turnstile verification plugin for Webman framework

README 文档

README

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>

API 参考

Turnstile::verify($token, $remoteIp = null)

验证 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' => '验证服务暂时不可用，请稍后重试']);
}

TurnstileException 方法

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！

更新日志

v1.0.0

初始版本发布
支持基本的 Turnstile 验证功能
自动配置文件生成

zjkal/webman-turnstile 适用场景与选型建议

zjkal/webman-turnstile 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 6 次下载、GitHub Stars 达 2，最近一次更新时间为 2025 年 12 月 04 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「plugin」「captcha」「cloudflare」「verification」「webman」「turnstile」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 zjkal/webman-turnstile 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 zjkal/webman-turnstile 我们能提供哪些服务？

定制开发 / 二次开发

基于 zjkal/webman-turnstile 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 zjkal/webman-turnstile 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

maiconpinto/cakephp-adminlte-theme 171

CakePHP 4.x AdminLTE Theme.

rsm/rsm-googlerecaptcha-modul 3

Diese Contao 4 Erweiterung stellt Google reCAPTCHA V2 in Form eines neuen Formularfeldes im Formulargenerator bereit. This extension provides Google reCAPTCHA V2 in the form of a new form field in the form generator of Contao Open Source CMS.

wucdbm/two-captcha 0

Two Captcha

rolandverner/symfony-cloudflare 3

Symfony bundle for Cloudflare integration: trusted proxies, real client IP detection, forwarded headers.

cornford/guzzle-cloudflare-middleware 3

Cloudflare Middleware For Guzzle

yhbyun/laravel-securimage 3

Laravel 5 Securimage helper

zjkal/webman-turnstile

包简介

关键字：