README

通过使用 Google 的 reCAPTCHA 服务，将“垃圾邮件防护”字段添加到 SilverStripe 用户表单中。

要求

SilverStripe ^4 | ^5
SilverStripe Spam Protection ^2 | ^3
PHP CURL

安装

composer require undefinedoffset/silverstripe-nocaptcha

通过 composer 或手动安装模块后，您必须将垃圾邮件防护设置为 NocaptchaProtector，这需要在您网站的配置文件中设置，通常是在 mysite/_config/config.yml。

SilverStripe\SpamProtection\Extension\FormSpamProtectionExtension:
    default_spam_protector: UndefinedOffset\NoCaptcha\Forms\NocaptchaProtector

最后，通过在表单对象上调用 enableSpamProtection() 将“垃圾邮件防护”字段添加到您的表单中。

$form->enableSpamProtection();

配置

该字段有多种配置选项，您必须设置 site_key 和 secret_key，您可以从 reCAPTCHA 页面获取这些密钥。这些配置选项必须添加到您网站的 yaml 配置中，通常是在 app/_config/config.yml。

UndefinedOffset\NoCaptcha\Forms\NocaptchaField:
    site_key: "YOUR_SITE_KEY" #Your site key (required)
    secret_key: "YOUR_SECRET_KEY" #Your secret key (required)
    recaptcha_version: 2 # 2 or 3
    minimum_score: 0.2 # minimum spam score to achieve. Any less is blocked
    verify_ssl: true #Allows you to disable php-curl's SSL peer verification by setting this to false (optional, defaults to true)
    default_theme: "light" #Default theme color (optional, light or dark, defaults to light)
    default_type: "image" #Default captcha type (optional, image or audio, defaults to image)
    default_size: "normal" #Default size (optional, normal, compact or invisible, defaults to normal)
    default_badge: "bottomright" #Default badge position (bottomright, bottomleft or inline, defaults to bottomright)
    default_handle_submit: true #Default setting for whether nocaptcha should handle form submission. See "Handling form submission" below.
    proxy_server: "" #Your proxy server address (optional)
    proxy_port: "" #Your proxy server address port (optional)
    proxy_auth: "" #Your proxy server authentication information (optional)

# The following options can also be specified through Environment variables with Injector config
SilverStripe\Core\Injector\Injector:
  UndefinedOffset\NoCaptcha\Forms\NocaptchaField:
    properties:
      SiteKey: '`SS_NOCAPTCHA_SITE_KEY`'
      SecretKey: '`SS_NOCAPTCHA_SECRET_KEY`'
      ProxyServer: '`SS_OUTBOUND_PROXY`'
      ProxyPort: '`SS_OUTBOUND_PROXY_PORT`'
      ProxyAuth: '`SS_OUTBOUND_PROXY_AUTH`'

添加字段标签

如果您想向 Captcha 字段添加字段标签或帮助文本，可以像这样操作

$form->enableSpamProtection()
    ->fields()->fieldByName('Captcha')
    ->setTitle("Spam protection")
    ->setDescription("Please tick the box to prove you're a human and help us stop spam.");

注释模块

当您使用 silverstripe/comments 模块时，您必须将以下内容添加到您的 _config.php 中（按照他们的文档说明），以便在评论表单上使用 nocaptcha/spamprotection。

CommentingController::add_extension('CommentSpamProtection');

检索验证响应

如果您希望在表单动作中手动检索网站验证响应，请使用 getVerifyResponse() 方法。

function doSubmit($data, $form) {
    $captchaResponse = $form->Fields()->fieldByName('Captcha')->getVerifyResponse();

    // $captchaResponse = array (size=5) [
    //  'success' => boolean true
    //  'challenge_ts' => string '2020-09-08T20:48:34Z' (length=20)
    //  'hostname' => string 'localhost' (length=9)
    //  'score' => float 0.9
    //  'action' => string 'submit' (length=6)
    // ];
}

ReCAPTCHA v3

ReCAPTCHA v3 与 v2 不同，用户不会看到“您是人类吗？”复选框，而是当用户提交表单时，用户操作返回一个垃圾邮件分数 0.0 到 1.0。默认情况下，此模块将阻止任何垃圾邮件分数 <= 0.4 的提交，但可以通过 Config API 在站点范围内或针对每个表单进行定制。

UndefinedOffset\NoCaptcha\Forms\NocaptchaField:
  minimum_score: 0.2

或针对每个表单

$captchaField = $form->Fields()->fieldByName('Captcha')-
$captchaField->setMinimumScore(0.2);

有关版本 3 的更多信息，包括如何实现自定义操作，请参阅 https://developers.google.com/recaptcha/docs/v3

处理表单提交

默认情况下，此模块包含的 JavaScript 将向您的表单添加一个提交事件处理程序。

如果您需要以特殊方式处理表单提交（例如，支持前端验证），您可以自行处理表单提交事件。

这可以通过 Config API 在全局范围内进行配置

UndefinedOffset\NoCaptcha\Forms\NocaptchaField:
    default_handle_submit: false

或针对每个表单

$captchaField = $form->Fields()->fieldByName('Captcha');
$captchaField->setHandleSubmitEvents(false);

使用此配置，此模块不会向您的表单添加任何事件处理程序。相反，将提供一个名为 nocaptcha_handleCaptcha 的函数，您可以在准备好提交表单时从您的代码中调用它。它具有以下签名

function nocaptcha_handleCaptcha(form, callback)

form 必须是表单元素，而 callback 应该是最终提交表单的函数，尽管它是可选的。

在 simplest case 中，您可以使用它像这样

document.addEventListener("DOMContentLoaded", function(event) {
    // where formID is the element ID for your form
    const form = document.getElementById(formID);
    const submitListener = function(event) {
        event.preventDefault();
        let valid = true;
        /* Your validation logic here */
        if (valid) {
            nocaptcha_handleCaptcha(form, form.submit.bind(form));
        }
    };
    form.addEventListener('submit', submitListener);
});

报告问题

在报告问题时，请确保指定您正在使用的 SilverStripe 版本，例如 3.1.3、3.2beta、master 等。同时，请确保包含您收到的任何 JavaScript 或 PHP 错误，对于 PHP 错误，请确保包含完整的堆栈跟踪。此外，请说明您是如何产生该问题的。您可能还被要求提供一些类以帮助重现问题。专注于问题本身，记住您看到的是问题，而不是模块的维护者，因此可能需要很多问题才能找到解决方案或答案。

undefinedoffset / silverstripe-nocaptcha

维护者

详细信息