recaptcha

The recaptcha hook¶

The recaptcha hook adds Google reCAPTCHA v3 checks to a FormIt form. v3 runs in the background. There is no checkbox and no challenge widget.

Google returns a score from 0.0 to 1.0. FormIt accepts the submission only when verification succeeds and the score is at least formit.recaptcha_min_score (default 0.5).

This is the current FormIt behavior from 5.2.1 onward (Sterc/FormIt). Older FormIt releases used reCAPTCHA v1 APIs and settings that no longer apply.

Requirements¶

1. FormIt 5.2.1+ (package that ships reCAPTCHA v3).
2. A reCAPTCHA v3 site key and secret key from the Google reCAPTCHA admin. Create a v3 key for your domain. v2 checkbox keys will not work with this hook.
3. System settings formit.recaptcha_site_key and formit.recaptcha_secret_key filled in (area formit_recaptcha).
4. Frontend JS enabled: formit.frontend_js set to js/web/formit.js (the FormIt default on a normal install).

Without formit.frontend_js, FormIt does not load Google's script or request a token, so the hook fails on submit.

How the JavaScript loads¶

When the page renders (before a POST) and the recaptcha hook is in &hooks, FormIt:

1. Sets [[+formit.recaptcha_html]] to two hidden inputs: g-recaptcha-response and g-recaptcha-action.
2. Registers https://www.google.com/recaptcha/api.js?render={siteKey} if the site key is set.
3. Registers assets/components/formit/js/web/formit.js when formit.frontend_js is set, and passes recaptchaSiteKey / recaptchaDefaultAction into the FormIt JS config.

On submit, formit.js calls grecaptcha.execute(), writes the token into g-recaptcha-response, then continues with a normal POST or with AJAX if data-formit-ajax-token is present.

You do not add the Google script by hand. You do need the placeholder in the form markup and a working frontend JS setting.

Usage¶

[[!FormIt?
    &hooks=`recaptcha,email`
    &recaptchaAction=`contact`
]]

Inside the <form>:

[[+formit.recaptcha_html]]
[[!+fi.error.recaptcha]]

Place recaptcha before hooks that should run only after a valid human score (for example before email). Put redirect last when you use it.

Example with fields and email: Simple Contact Page.

System settings¶

Configure keys under System Settings in the formit_recaptcha area:

Also required for the token request:

After upgrading from FormIt versions that used reCAPTCHA v1, remove reliance on formit.recaptcha_public_key, formit.recaptcha_private_key, recaptchaTheme, recaptchaJs, and recaptcha_use_ssl. Those keys and properties are gone. Use the v3 settings above.

Available properties¶

Troubleshooting¶

Server-side verification posts to Google's siteverify endpoint with the secret, the token, and the client IP. PHP needs outbound HTTPS (cURL) to www.google.com.

See also¶

1. FormIt.Hooks.email
2. FormIt.Hooks.FormItAutoResponder
3. FormIt.Hooks.FormItSaveForm
4. FormIt.Hooks.math
5. FormIt.Hooks.redirect
6. FormIt.Hooks.spam
7. AJAX Form Submission
8. Simple Contact Page