README

此包是 Yii 2 的一个简单扩展，帮助处理 Google reCAPTCHA v3

• 安装
• 使用
  • 基本
  • AJAX 验证
  • Twig 集成
• 本地化
• 隐藏 Google reCaptcha 徽章

安装

您需要运行以下命令以将依赖项添加到您的项目中

composer require manchenkov/yii2-recaptcha3

或者您可以将此行添加到 composer.json 的 require 部分

"manchenkov/yii2-recaptcha3": "^1.0.3"

使用

基本设置

首先，您需要将以下设置添加到您的应用程序的 params 部分（通常为 params.php 文件）。

return [
    // your other params
    'reCAPTCHA.siteKey' => 'GOOGLE_RECAPTCHA_SITE_KEY',
    'reCAPTCHA.secretKey' => 'GOOGLE_RECAPTCHA_SECRET_KEY',
];

然后，您应该将以下规则添加到验证模型中

public $captcha;

public function rules()
{
    return [
        // other validation rules
        ['captcha', ReCaptchaValidator::class, 'score' => 0.8, 'action' => 'login'],
    ];
}

• score：接受分数的最小值（默认：0.5）
• action：页面动作名称（默认：homepage）
• message：要显示的错误消息（请参阅下面的 本地化 部分）

最后一步是添加 ActiveForm 输入，只需使用以下示例即可

$form->field($model, 'captcha')->widget(ReCaptchaWidget::class);

// or

$form->field($model, 'captcha')->widget(ReCaptchaWidget::class, ['action' => 'login']);
// action name must be the same as validation rules

AJAX 验证

默认行为可能会与 AJAX 验证产生一些问题，因为 Google 建议在提交表单之前请求验证码令牌，请参阅文档

Note: reCAPTCHA tokens expire after two minutes. If you're protecting an action with reCAPTCHA, make sure to call execute when the user takes the action rather than on page load.

在这种情况下，Yii 控制器将收到空值并给出验证错误。

为了解决这个问题，ReCaptchaWidget 支持额外的属性 - preloading。

您应该在视图文件中使用以下示例

<?php $form = ActiveForm::begin(
    [
        'id' => 'example-form',
        'enableAjaxValidation' => true,
        'validateOnBlur' => false,
        'validateOnChange' => false,
    ]
); ?>

...

<?= $form->field($model, 'captcha')->widget(ReCaptchaWidget::class, ['action' => 'login', 'preloading' => true]); ?>

重要

您不能在没有禁用 validateOnBlur 和 validateOnChange 的情况下使用 enableAjaxValidation，因为默认的 yiiActiveForm.js 插件会自动提交表单以进行验证，而不触发任何事件，因此 reCaptcha 令牌不会刷新。

与 Twig 一起使用

如果您使用 Twig 作为模板引擎，可以创建如下辅助函数

/**
/ $model: SomeForm model instance
/ $attribute: model property name
/ $action: captcha page action name
/ $showBadge: visibility of captcha badge on the page
**/
'reCaptcha' => function (Model $model, string $attribute, string $action = 'homepage', bool $showBadge = true) {
    return ReCaptchaWidget::widget([
        'model' => $model,
        'action' => $action,
        'attribute' => $attribute,
        'showBadge' => $showBadge
    ]);
};

然后在 .twig 模板中不使用 ActiveForm 使用它

{{ reCaptcha(model, 'captcha', 'login') | raw }}

本地化

如果在验证过程中发生错误或通过 HTTP 客户端发送请求时出错，默认错误消息将是“Google reCAPTCHA 验证失败”。输入小部件使用默认的 i18n 本地化 将其打印到页面上，因此您可以添加以下消息的翻译

// category - 'app'
Yii::t("app", "Google reCAPTCHA verification failed")

// For example: 'messages/en/app.php' (i18n php message sources)
"Google reCAPTCHA verification failed" => "Google reCAPTCHA verification failed",

// For example: 'messages/ru/app.php'
"Google reCAPTCHA verification failed" => "Не удалось проверить Google reCAPTCHA", 

隐藏 Google 隐私徽章

默认情况下，Google reCAPTCHA v3 在页面右下角打印一个徽章，但您可以使用以下示例隐藏它

$form->field($model, 'captcha')->widget(ReCaptchaWidget::class, [
    'action' => 'login',
    'showBadge' => false',
]);

在这种情况下，输入提示将包含 Google 建议的默认消息，但您可以通过使用 field(...)->widget(...)->hint('自定义 Google 验证码消息') 来更改它

无论如何，您必须在表单中包含一些提及文本，请参阅此处的详细信息。