Download the PHP package karser/karser-recaptcha3-bundle without Composer

KarserRecaptcha3Bundle

reCAPTCHA v3 returns a score for each request without user friction. The score is based on interactions with your site (1.0 is very likely a good interaction, 0.0 is very likely a bot) and enables you to take an appropriate action for your site. Register reCAPTCHA v3 keys here.

Installation

With composer, require:

composer require karser/karser-recaptcha3-bundle

You can quickly configure this bundle by using symfony/flex:

• answer no for google/recaptcha
• answer yes for karser/karser-recaptcha3-bundle

Configuration without symfony/flex:

1. Register the bundle

Symfony 4/5/6/7 Version :
Register bundle into config/bundles.php:

Symfony 3 Version:
Register bundle into app/AppKernel.php:

2. Add configuration files

Add your site key and secret to your .env file:

Usage

How to integrate re-captcha in Symfony form:

Notes:

• The action_name parameter is reCAPTCHA v3 action which identifies the submission of this particular form in the Google reCAPTCHA dashboard, and confirming it is as expected in the backend is a recommended extra security step.
• The script_nonce_csp parameter is optional. You must use the same nonce as in your Content-Security Policy header.
• The locale parameter is optional. It defaults to English and controls the language on the reCaptcha widget.

How to use reCAPTCHA globally (meaning even in China):

Use 'www.recaptcha.net' host in your code when 'www.google.com' is not accessible.

How can I set the captcha language for different locales?

You can control the language in the small widget displayed by setting the locale in the options above.

To change the error messages, you should install the Symfony Translation component.

Then replace the validation text with the translation keys for the message and messageMissingValue options: ` Add English, Spanish, or any other translation:

How to get the ReCaptcha score:

Inject the Recaptcha3Validator and call getLastResponse()->getScore() after the form was submitted:

How to integrate re-captcha in API method:

The idea is to require the frontend to submit the captcha token, so it will be validated on server side.

First you need to add the captcha field to your transport entity:

And to add the validation constraint:

On frontend part you need to submit the captcha token along with email. You can obtain the captcha token either on page load or on form submit.

How to show errors from the captcha's response

Just add the {{ errorCodes }} variable to the message template:

How to deal with functional and e2e testing:

Recaptcha won't allow you to test your app efficiently unless you disable it for the environment you are testing against.

How to set the threshold from PHP dynamically rather from the .yaml config or .env?

You should inject @karser_recaptcha3.google.recaptcha in your service and call setScoreThreshold method.

How to resolve IP propertly when behind Cloudflare:

From the Cloudflare docs: To provide the client (visitor) IP address for every request to the origin, Cloudflare adds the CF-Connecting-IP header.

So you can implement custom IP resolver which attempts to read the CF-Connecting-IP header or fallbacks with the internal IP resolver:

Here is the service declaration. It decorates the internal resolver:

Symfony HttpClient integration

If you have a dependency on symfony/http-client in your application then it will be automatically wired to use via RequestMethod/SymfonyHttpClient.

Troubleshooting checklist

Make sure you setup recaptcha key/secret of version 3.

Also, make sure you added the domain you use in the recaptcha settings. Usually dev domain differs from the production one, so better to double check.

Make sure you are seeing this in the html of your rendered form

Make sure you don't have javascript errors in the browser console

Testing