Spam protection
Each form has its own spam settings in Basin. To find them, open the form’s page in the Control Panel and click Change in Basin under Spam protection. If a form requires a CAPTCHA and the page doesn’t include one, Basin rejects every submission. The plugin makes sure the page includes whatever Basin requires.
What happens automatically
Section titled “What happens automatically”With Add spam protection automatically on (the default), on every front-end page that has a Basin form:
- Honeypot: a hidden field is added to the form, named whatever the form’s honeypot is in Basin (
_gotchaunless you’ve changed it). Bots that fill it in are filed as spam. - CAPTCHA: if the form requires reCAPTCHA, hCaptcha or Turnstile, the widget and its script are added, just before the submit button.
This works however the form got onto the page: craft.basin.form(), a Basin Form field, hard-coded markup, {% cache %} blocks, and forms added later by JavaScript (such as in a modal). Pages without a Basin form are left alone.
To leave one form alone, add data-basin-protect="false" to its <form> tag. To turn it off everywhere, turn off the setting and place things yourself.
Which CAPTCHA to use
Section titled “Which CAPTCHA to use”The CAPTCHA is chosen in Basin. If you’re choosing:
- reCAPTCHA v3 or Turnstile are invisible to most visitors.
- hCaptcha is a good choice for privacy-focused sites.
- Turn on one CAPTCHA per form, and keep the honeypot.
reCAPTCHA v2 or v3
Section titled “reCAPTCHA v2 or v3”Basin accepts either version of reCAPTCHA. v3 is the default: it’s invisible and checks visitors when they submit. v2 shows the “I’m not a robot” checkbox.
You can choose:
- for the whole site, in the plugin’s settings;
- for one form, on its page under Basin → Forms (needs Set up forms on this site);
- for one form on one page, with
data-basin-recaptcha="v2"on the<form>tag, orform.captcha({ version: 'v2' }).
v2 and v3 forms can share a page.
Turnstile
Section titled “Turnstile”Basin doesn’t provide Turnstile keys. To use Turnstile:
- Create a Turnstile widget in your Cloudflare dashboard, and add every domain the form is used on (production, staging and local).
- Enter its site key and secret key in the form’s spam settings in Basin.
If Turnstile is turned on without keys, every submission fails. The form’s page in the Control Panel warns you when this happens.
Placing it yourself
Section titled “Placing it yourself”To control exactly where the honeypot and CAPTCHA go, use the helpers:
{% set form = craft.basin.form('demo0contact') %}{% if form %} <form action="{{ form.action }}" method="post"> {{ form.honeypot() }} <input type="email" name="email" required> {{ form.captcha() }} <button type="submit">Send</button> </form>{% endif %}{{ form.spamProtection() }} outputs both. Each helper outputs nothing if the form doesn’t need it, and the automatic protection won’t add anything twice. They take an optional object of HTML attributes, e.g. form.captcha({ class: 'my-captcha' }).
If you turn Add spam protection automatically off, the helpers are the only way the CAPTCHA gets onto your pages.
Static caching
Section titled “Static caching”Pages cached by Blitz get the same spam protection as any other page, including when your server serves Blitz’s cached files directly. Nothing the plugin adds is specific to a visitor, so cached pages are safe to show to everyone. Other full-page caches, such as Cloudflare or Varnish, store the page after the plugin has added protection, so they work too.
A cached page keeps the spam settings it was cached with, so clear it after changing the form’s settings in Basin (below).
If your server serves Blitz’s files directly, PHP doesn’t run on those visits, so the error log only sees a missing form when the page is cached, not on every visit. A page that stays cached for more than 30 days can have its entry expire while the problem is still there. Clearing the page from Blitz brings the entry back when the page is next cached.
When you change spam settings in Basin
Section titled “When you change spam settings in Basin”The plugin caches each form’s settings for the Cache duration (5 minutes by default). After turning on a CAPTCHA in Basin, either wait, or clear Basin data under Utilities → Caches.
If you use static caching, such as Blitz, also clear the cached pages that have the form, because they include the old settings.
Content Security Policy
Section titled “Content Security Policy”The plugin adds a small inline script to pages with a CAPTCHA form. If your site uses a nonce-based Content Security Policy, the script uses the same nonce as your other scripts. Your policy also needs to allow the CAPTCHA provider’s script and frames:
- reCAPTCHA:
www.google.com,www.gstatic.com - hCaptcha:
js.hcaptcha.com,*.hcaptcha.com - Turnstile:
challenges.cloudflare.com
Headless sites
Section titled “Headless sites”GraphQL returns each form’s spam requirements, so your front end can add them. See GraphQL.