README

Google reCAPTCHA for Craft CMS 允许渲染和验证 reCAPTCHA 小部件。它与 API v2 和 v3 兼容，包括复选框徽章和透明版本。

要求

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

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

安装

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

配置

控制面板

您可以通过前往设置→Google reCAPTCHA 来通过控制面板管理配置设置。

提供从您的reCAPTCHA 账户获取的站点密钥和秘密密钥。
根据您创建密钥的 reCAPTCHA 类型相应地选择 API 版本。
对于 v2 API，选择以下参数
- 大小：选择 reCAPTCHA 小部件的大小。
- 主题：选择 reCAPTCHA 小部件的颜色主题。
- 徽章：选择 reCAPTCHA 徽章的位置。
对于 v3 API
- 默认动作：reCAPTCHA 验证期间要使用的默认动作名称。如果为空，则默认为 homepage。
- 默认分数阈值：为了使最终用户验证 reCAPTCHA 挑战，必须在 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》方法接受一个可选参数，您可以在其中提供任何要应用到小部件容器（v2版本为div，v3版本为隐藏输入框）的HTML属性。
例如，要提供容器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调用加载的视图，并且需要刷新小部件，这将非常有用。

验证用户提交

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

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访客条目插件时添加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;
    }
});

验证联系表单提交

为了在使用联系表单时添加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.');
    }
});

由Simplon.Prod创建。

简化版 / craft-google-recaptcha

维护者

详细信息