README

适用于Craft CMS的Google reCAPTCHA插件可以渲染和验证reCAPTCHA小部件。它与API v2和v3兼容，包括复选框徽章和无障碍选项。

要求

此插件需要Craft CMS 4.0.0或更高版本以及PHP 8.0.2或更高版本。

要使用此插件，您需要获取API站点密钥和秘密密钥，您可以在此处配置。

安装

使用composer从项目目录或从控制面板的插件商店部分安装： composer require jub/craft-google-recaptcha
在Craft控制面板的设置→插件下安装插件，或通过命令行使用： ./craft plugin/install google-recaptcha

配置

控制面板

您可以通过转到设置→Google reCAPTCHA通过控制面板管理配置设置。

提供从您的reCAPTCHA账户获取的站点密钥和秘密密钥。
根据创建密钥时创建的reCAPTCHA类型选择相应的API版本。
对于v2 API，选择以下参数
- 大小：选择reCAPTCHA小部件的大小。
- 主题：选择reCAPTCHA小部件的颜色主题。
- 徽章：选择reCAPTCHA徽章的位置。
对于v3 API
- 默认动作：reCAPTCHA验证期间使用的默认动作名称。如果为空，则默认为homepage。
- 默认得分阈值：为了验证reCAPTHCHA挑战（有关解释得分帮助，请参阅此处），需要获取的介于0和1之间的最小得分。留空不进行检查。
- 动作：可以在此处为每个动作定义得分阈值。

配置文件

您可以在项目的config文件夹中创建一个google-recaptcha.php文件，并按以下方式提供设置

return [
    "version"   		=> 2, // Either 2 our 3
    "siteKey"   		=> '', // Site key
    "secretKey" 		=> '', // Secret key
    "size"      		=> 'normal', // (v2) normal, compact or invisible
    "theme"     		=> 'light', // (v2) light or dark
    "badge"     		=> 'bottomright', // (v2) bottomright, bottomleft or inline
    "actionName"        => 'homepage', // (v3) Default action name
    "scoreThreshold"	=> 0.5 // (v3) Value between 0 and 1 to determine the minimum score to validate
    "actions"			=> [ // (v3) List of actions with their associated score threshold value (see the template part below to know how to specify the action parameter in the render method)
    	[
    		'name' 				=> 'some_action_name',
    		'scoreThreshold' 	=> 0.5
    	]
    ]
    
];

⚠️该文件中提供的任何值都将覆盖控制面板中的设置。

使用Google reCAPTCHA

在模板中显示Google reCAPTCHA小部件

您可以将Google reCAPTCHA小部件集成到您的Twig模板中，如下所示

{{ craft.googleRecaptcha.render() }}

该render方法接受一个可选参数，您可以在其中提供要应用于小部件容器的任何HTML属性（v2为div，v3为隐藏输入）。
例如，要提供容器ID，可以这样做

{{ craft.googleRecaptcha.render({id: 'recaptcha-widget'}) }}

对于v3 API，还可以提供以下动作属性

{{ craft.googleRecaptcha.render({id: 'recaptcha-widget', action: 'some_action_name'}) }}

在这种情况下，可以在插件控制面板的“动作设置”部分定义该动作使用的得分阈值。

💡对于v2 API，您可以将第二个布尔参数提供给render方法以触发小部件的即时渲染（即{{ craft.googleRecaptcha.render({ id: 'recaptcha-widget' }, true) }}）。如果您使用Ajax或Sprig调用加载视图并且需要刷新小部件，这将非常有用。

设置脚本的额外属性

在第一个渲染参数中，可以使用 scriptOptions 特殊属性为生成的脚本标签添加额外的属性。

例如，为了支持内容安全策略（CSP），假设您正在使用 Sherlock 安全插件，您可以执行以下操作

{% set nonce = craft.sherlock.getNonce() %}
{{ craft.googleRecaptcha.render({scriptOptions: {'nonce': nonce}}) }}

验证用户提交

为了在服务器端验证用户提交，您可以使用内置方法

GoogleRecaptcha::$plugin->recaptcha->verify();

例如，在一个模块控制器中，您可以这样做

public function actionSubmitForm() {
	if(GoogleRecaptcha::$plugin->recaptcha->verify()) {
		// Do something useful here
	}
	else {
		Craft::$app->session->setError('Looks like you are a robot!');
	}

}

验证访客条目提交

为了在使用 Craft Guest Entries 插件时添加 reCAPTCHA 验证，您可以在项目模块中执行以下操作

Event::on(SaveController::class, SaveController::EVENT_BEFORE_SAVE_ENTRY, function (SaveEvent $e) {
    /** @var Entry $submission */
    $submission = $e->entry;
    $submission->setScenario(Element::SCENARIO_LIVE);
    $submission->validate();
    // Check reCAPTCHA
    $isValid = GoogleRecaptcha::$plugin->recaptcha->verify();
    if (!$isValid) {
        $submission->addError('recaptcha', 'Please, prove you’re not a robot.');
        $e->isValid = false;
    }
});

验证联系表单提交

为了在使用 Contact Form 时添加 reCAPTCHA 验证，您可以在项目模块中执行以下操作

Event::on(Submission::class, Submission::EVENT_AFTER_VALIDATE, function(Event $e) {
    /** @var Submission $submission */
    $submission = $e->sender;
    // Check reCAPTCHA
    $isValid = GoogleRecaptcha::$plugin->recaptcha->verify();
    if (!$isValid) {
        $submission->addError('recaptcha', 'Please, prove you’re not a robot.');
    }
});

可用事件

\juban\googlerecaptcha\events\BeforeRecaptchaVerifyEvent 事件在执行 reCAPTCHA 验证之前触发。您可以使用该事件来
- 绕过验证，通过将 skipVerification 事件属性设置为 true。在这种情况下，验证将被视为成功。
- 取消验证，通过将 isValid 事件属性设置为 false。在这种情况下，验证将被视为失败。

jub / craft-google-recaptcha

维护者

详情