README

Adds the reCAPTCHA control to Nette Framework forms.

Documentation

Installation
Configuration
Usage
Requester
AJAX
Invisible reCAPTCHA
Testing

Installation

For easy installation use Composer:

composer require uestla/recaptcha-control

Also don't forget to include the official JavaScript library:

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

Are you using AJAX? Then you may want to use library asset instead - see more.

Configuration

To be able to use the reCAPTCHA control in your forms just register the DI extension in your config.neon:

extensions:
	recaptcha: ReCaptchaControl\DI\Extension

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

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

Parameters:

Parameter	Type	Default value	Required	Meaning
`siteKey`	string \| `Nette\DI\Statement`	~	YES	The site key you obtain in your Google Account
`secretKey`	string \| `Nette\DI\Statement`	~	YES	The secret key you obtain in your Google Account
`methodName`	string	"addReCaptcha"	NO	Extension method name you'll be calling upon your forms to add the control, e.g. `$form->addReCaptcha(...)`
`requester`	string	"CurlRequester"	NO	Name of the class or service which sends requests to the Google validation API. The default `CurlRequester` needs PHP cURL extension to run properly. Read more about requesters here.

Usage

Form

To actually add reCAPTCHA to your form just call

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

Please note that the validation rule is added automatically so you don't need to call any addRule() at all.

Template

You can then render the control in your Latte template using both macro and n:attr approach:

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

	{* or macro *}
	{input captcha}

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

And there she goes! :-)

Requester

Requester is a layer for sending HTTP requests. It comes handy when your production environment does not meet the default requirements (cURL extension etc.).

You can change the default requester by setting the requester key in configuration. The value can be either a class name or a name of another service (see details below).

CurlRequester

This is the default one since requester value is optional in configuration.

It uses PHP cURL extension. If you want to set any CURLOPT_* value for the requests you have to create the service aside and pass these options to the constructor:
```
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'
```
As you can see in the example it is possible to use all CURLOPT_* constants as string keys (they are converted internally).

SimpleRequester

Calls file_get_contents() with stream context.

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

GuzzleRequester

If you're already using the Guzzle HTTP Client in your application, this requester may come handy:

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

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

If you're using multiple clients it is better to define the requester as a service aside:

recaptcha:
	...
	requester: @guzzleRequester

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

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

Custom requester

You can also implement your own requester. Just make sure it implements the ReCaptchaControl\Http\Requester\IRequester interface.

It basically requires a single public function post(string $url, array $values = []): string method which takes URL, performs a HTTP POST request with given $values and returns body of the response as a string. In case of a failure, ReCaptchaControl\Http\Requester\RequestException should be thrown.

You can then use it the same way as above:
```
recaptcha:
	requester: MyRequesterClass
```
or when you have some dependencies:
```
recaptcha:
	requester: @myRequester

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

AJAX

When a snippet containing reCAPTCHA control gets updated, the reCAPTCHA itself needs to be re-rendered.

If you're using the nette.ajax.js, you may want to use the assets/recaptcha.ajax.js script.

You can install it via bower:

bower install

IMPORTANT: The recaptcha.ajax.js script loads the official JavaScript library because it needs to render the reCATPCHAs explicitely. So please be careful not to loaded by yourself as well.

Invisible reCAPTCHA

You can also use this library for Invisible reCAPTCHA. The backend part stays the same so it only needs proper configuration in the frontend. To see it in action you can visit https://kesspess.cz/recaptcha/invisible and the code in tests.

Tests & CI

Automated tests

This library uses Nette Tester for automated testing and PHPStan for static analysis. For running them yourself simply run

# runs test suite & static analysis
composer ci

Manual testing

You may have noticed the tests/manual directory. Its content is actualy live at https://kesspess.cz/recaptcha.

To get it to work on your local machine, do following:

copy config/local.neon.template to config/local.neon
fill reCAPTCHA keys properly in config/local.neon
run composer install
run bower install

After that you should be able to run it via your local web server.

The form definitions are in TestPresenter.

Individual example templates are located in presenters/templates directory.

uestla / recaptcha-control

Maintainers

Details