README

将 reCAPTCHA 控制器添加到 Nette 框架表单。

文档

安装
配置
使用
请求者
AJAX
不可见 reCAPTCHA
测试

安装

为了方便安装，请使用 Composer

composer require uestla/recaptcha-control

同时，别忘了包含官方 JavaScript 库

<script src="https://www.google.com/recaptcha/api.js" async defer></script>

如果你使用 AJAX，那么你可能想使用库资产 - 更多信息。

配置

为了能够在你的表单中使用 reCAPTCHA 控制器，只需在你的 config.neon 中注册 DI 扩展即可

extensions:
	recaptcha: ReCaptchaControl\DI\Extension

recaptcha:
	# required
	siteKey: '<your_site_key>'
	secretKey: '<your_secret_key>'

	# optional
	methodName: 'addReCaptcha'
	requester: ReCaptchaControl\Http\Requester\CurlRequester

参数

使用

表单

要实际上将 reCAPTCHA 添加到你的表单，只需调用

$form->addReCaptcha(
	'captcha', // control name
	'reCAPTCHA for you', // label
	"Please prove you're not a robot." // error message
);

请注意，验证规则会自动添加，所以你根本不需要调用任何 addRule()。

模板

然后你可以在你的 Latte 模板中使用宏和 n:attr 方法来渲染该控件

<form ...>
	{* n:attr *}
	<div n:name="captcha"></div>

	{* or macro *}
	{input captcha}

	{* don't forget to render potential errors *}
	{$form['captcha']->getError()}
</form>

这就完成了！:-)

请求者

请求者是发送 HTTP 请求的层。当你的生产环境不符合默认要求时（cURL 扩展等）很有用。

你可以通过在配置中设置 requester 键来更改默认的请求者。该值可以是类名或另一个服务的名称（见下文详细信息）。

CurlRequester

这是默认的，因为配置中的 requester 值是可选的。

它使用 PHP cURL 扩展。如果你想要为请求设置任何 CURLOPT_* 值，你必须创建一个服务实例并将这些选项传递给构造函数

recaptcha:
	...
	requester: @curlRequester

services:
	curlRequester:
		class: ReCaptchaControl\Http\Requester\CurlRequester
		arguments:
			-
				CURLOPT_CAINFO: %appDir%/res/cacert.pem
				CURLOPT_USERAGENT: 'Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.104 Safari/537.36'

如示例所示，你可以使用所有 CURLOPT_* 常量作为字符串键（它们在内部被转换）。

SimpleRequester

使用流上下文调用 file_get_contents()。

recaptcha:
	...
	requester: ReCaptchaControl\Http\Requester\SimpleRequester

GuzzleRequester

如果你已经在你的应用程序中使用 Guzzle HTTP Client，这个请求者可能很有用

recaptcha:
	...
	requester: ReCaptchaControl\Http\Requester\GuzzleRequester

services:
	- Guzzle\Http\Client # will be autowired to the GuzzleRequester constructor

如果你正在使用多个客户端，最好将请求者定义为独立的服务

recaptcha:
	...
	requester: @guzzleRequester

services:
	guzzleRequester: ReCaptchaControl\Http\Requester\GuzzleRequester(@primaryGuzzleHttpClient)

	primaryGuzzleHttpClient: Guzzle\Http\Client
	secondaryGuzzleHttpClient: Guzzle\Http\Client

自定义请求者

你也可以实现自己的请求者。只需确保它实现了 ReCaptchaControl\Http\Requester\IRequester 接口。

它基本上需要一个单一的 public function post(string $url, array $values = []): string 方法，该方法接受 URL，使用给定的 $values 执行 HTTP POST 请求，并返回响应体的字符串。在失败的情况下，应抛出 ReCaptchaControl\Http\Requester\RequestException。

然后你可以像上面一样使用它
```
recaptcha:
	requester: MyRequesterClass
```
或者当你有依赖关系时
```
recaptcha:
	requester: @myRequester

services:
	myRequester:
		factory: MyRequesterClass( ... )
		...
```

AJAX

当包含 reCAPTCHA 控件的片段被更新时，需要重新渲染 reCAPTCHA 本身。

如果你使用 nette.ajax.js，你可能想使用 assets/recaptcha.ajax.js 脚本。

你可以通过 bower 安装它

bower install

重要提示：脚本 recaptcha.ajax.js 会加载官方的JavaScript库，因为需要显式地渲染 reCATPCHAs。所以请务必小心，不要自己加载。

不可见 reCAPTCHA

您还可以使用这个库来使用不可见reCAPTCHA。后端部分保持不变，因此只需要在前端进行适当的配置。要查看其工作情况，您可以访问 https://kesspess.cz/recaptcha/invisible，并在测试中查看代码。

测试 & CI

自动化测试

这个库使用 Nette Tester 进行自动化测试，并使用 PHPStan 进行静态分析。要自行运行它们，请执行以下操作：

# runs test suite & static analysis
composer ci

手动测试

您可能已经注意到了 tests/manual 目录。其内容实际上在 https://kesspess.cz/recaptcha 上。

要在本地机器上运行它，请执行以下操作：

将 config/local.neon.template 复制到 config/local.neon
在 config/local.neon 中正确填写 reCAPTCHA 密钥
运行 composer install
运行 bower install

之后，您应该能够通过本地web服务器运行它。

表单定义在 TestPresenter 中。

单独的示例模板位于 presenters/templates 目录中。

clear01 / recaptcha-control

维护者

详细信息