README

Cloudflare Turnstile

轻松将 Turnstile 集成到您的表单中进行验证。

Turnstile 是 Cloudflare 的 免费、以 隐私为先 的智能 CAPTCHA 替代品。它根据会话期间收集的遥测数据和客户端行为自动从一系列非侵入性浏览器挑战中选出。

该插件默认支持 Sprig 请求。

如果您想了解更多关于 Turnstile 的信息，请阅读公告 博客文章 或 官方文档。

要求

此插件需要 Craft CMS 5.0.0 或更高版本。

安装

您可以从插件商店或使用 Composer 安装此插件。

从插件商店

转到项目控制面板中的插件商店，搜索“Turnstile”，然后点击“安装”。

使用 Composer

打开您的终端并运行以下命令

# go to the project directory
cd /path/to/my-project.test

# tell Composer to load the plugin
composer require billmn/craft-turnstile

# tell Craft to install the plugin
./craft plugin/install turnstile

Turnstile 的密钥

在插件设置页面中插入 站点和密钥，支持 .env 变量。

配置文件（可选）

您可以在项目的配置文件夹中创建一个 turnstile.php 文件来覆盖控制面板中指定的设置。

<?php

return [
    'siteKey' => '',
    'secretKey' => '',
    'validateUserRegistrations' => false,
];

使用 Turnstile

在您的模板中，在 form 标签内添加以下代码以渲染小部件

{{ craft.turnstile.widget() }}

widget 方法接受可选参数，其中您可以提供 HTML 属性来配置 Turnstile。

支持的配置列表可在 Turnstile 文档 中找到。

以下是一个示例，提供元素 ID 属性并设置小部件的主题和大小

{{ craft.turnstile.widget({
    id: 'contact-form',
    'data-size': 'compact',
    'data-theme': 'dark',
}) }}

{# or if you prefer #}

{{ craft.turnstile.widget({
    id: 'contact-form',
    data: {
        size: 'compact',
        theme: 'dark',
    }
}) }}

如果您没有指定 ID，将创建一个随机 ID。

验证表单提交

要验证 Turnstile 响应，您可以使用以下方法之一

Turnstile::getInstance()->validator->verify(); // returns `true` if passes
Turnstile::getInstance()->validator->passes();
Turnstile::getInstance()->validator->fails();

以下是如何使用 Contact Form 将消息标记为垃圾邮件的示例。在您的项目模块中添加以下代码

use billmn\turnstile\Turnstile;
use craft\contactform\events\SendEvent;
use craft\contactform\Mailer;
use yii\base\Event;

Event::on(
    Mailer::class,
    Mailer::EVENT_BEFORE_SEND,
    function(SendEvent $e) {
        $e->isSpam = Turnstile::getInstance()->validator->fails();
    }
);

如果您使用 response-field-name 配置，可以通过指定字段名来验证提交

{{ craft.turnstile.widget({
    'data-response-field-name': 'custom-field',
}) }}

Turnstile::getInstance()->validator->fails('custom-field');

验证公共用户注册

如果您使用 Craft 内置控制器操作 save-user（通过使用 {{ actionInput('users/save-user') }}），也可以验证 Turnstile。此行为默认关闭，但可以在插件设置页面中启用，或者在可选的配置文件中将 validateUserRegistrations 设置为 true。

小部件配置

您可以使用 config 数组自定义小部件的行为。

例如

{{ craft.turnstile.widget({
    config: {
        scriptAttr: {
            nonce: 'nonce'
        }
    }
}) }}

方法

例如

{{ craft.turnstile.widget({
    config: {
        registerJs: false,
    }
}) }}

<script src="{{ craft.turnstile.scriptUrl }}"></script>

<script>
    {{ craft.turnstile.initScript|raw }}
</script>