Skip to content

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.

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 (_gotcha unless 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.

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.

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, or form.captcha({ version: 'v2' }).

v2 and v3 forms can share a page.

Basin doesn’t provide Turnstile keys. To use Turnstile:

  1. Create a Turnstile widget in your Cloudflare dashboard, and add every domain the form is used on (production, staging and local).
  2. 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.

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.

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.

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.

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

GraphQL returns each form’s spam requirements, so your front end can add them. See GraphQL.