Protect your Statamic forms using a Captcha service.
This addon allows you to protect your Statamic forms using any of the following services:
- Google reCAPTCHA v2 (v3 not supported)
- hCaptcha
- Cloudflare Turnstile
- ALTCHA
- FCaptcha
After the initial setup, all you need to do is add the {{ captcha }} tag inside your forms, easy peasy!
Install the addon via composer:
composer require aryehraber/statamic-captcha
Publish the config file:
php please vendor:publish --tag=captcha-config
Alternately, you can manually setup the config file by creating captcha.php inside your project's config directory:
<?php
return [
'service' => env('CAPTCHA_SERVICE', 'Recaptcha'), // options: Recaptcha / Hcaptcha / Turnstile / Altcha / Fcaptcha
'sitekey' => env('CAPTCHA_SITEKEY', ''),
'secret' => env('CAPTCHA_SECRET', ''),
'server_url' => env('CAPTCHA_SERVER_URL', ''), // required for Fcaptcha
'verify_ip' => env('CAPTCHA_VERIFY_IP', false), // Fcaptcha only, see below
'forms' => [],
'user_login' => false,
'user_registration' => false,
'disclaimer' => '',
'invisible' => false,
'hide_badge' => false,
'enable_api_routes' => false,
'custom_should_verify' => null,
];Once the config file is in place, make sure to add your sitekey & secret from Recaptcha's Console, hCaptcha's Console, Cloudflare's Dashboard, Altcha's Docs or your FCaptcha server, and add the handles of the Statamic Forms you'd like to protect:
<?php
return [
'service' => env('CAPTCHA_SERVICE', 'Recaptcha'), // options: Recaptcha / Hcaptcha / Turnstile / Altcha / Fcaptcha
'sitekey' => 'YOUR_SITEKEY_HERE', // Or add to .env
'secret' => 'YOUR_SECRET_HERE', // Or add to .env
'forms' => ['contact', 'newsletter'],
// ...
];When using FCaptcha, also point the addon to your self-hosted FCaptcha server:
CAPTCHA_SERVICE=Fcaptcha
CAPTCHA_SITEKEY=your-site-key
CAPTCHA_SECRET=your-verify-secret
CAPTCHA_SERVER_URL=https://captcha.example.comFCaptcha binds each token to the IP address it saw when the widget was solved, and rejects a token whose remoteip disagrees. Because that only holds when your site reports the exact same address — which needs Laravel's trusted proxies configured, and can still differ for a dual-stack visitor who reaches one host over IPv6 and the other over IPv4 — the addon does not assert an IP by default. Set CAPTCHA_VERIFY_IP=true to turn the check on once you've confirmed both ends agree.
If you would like Captcha to verify ALL forms without having to specify each one in the forms config array, you may use the all option instead.
Note: this should replace the array and be set as a string.
<?php
return [
'forms' => 'all',
// ...
];<head>
<title>My Awesome Site</title>
{{ captcha:head }}
</head>
<body>
{{ form:contact }}
<!-- Add your fields like normal -->
{{ captcha }}
{{ if error:captcha }}
<p>{{ error:captcha }}</p>
{{ /if }}
{{ /form:contact }}
</body>This will automatically render the Captcha element on the page. After the form is submitted, the addon will temporarily halt the form from saving while the Captcha service verifies that the request checks out. If all is good, the form will save as normal, otherwise an error will be added to the {{ errors }} object.
Simply set invisible to true inside Captcha's config (Turnstile handles invisibility from Cloudflares's Dashboard, so no Captcha config changes are needed). To hide the sticky Recaptcha badge, make sure to also set hide_badge to true.
Note: using Invisible Captcha will require you to display links to the Captcha service's Terms underneath the form, to make this easier use {{ captcha:disclaimer }}. This message can be customised using the disclaimer option inside Captcha's config, however sensible defaults have been added that will automatically switch depending on the Captcha service you're using.
Captcha can also verify User Registration & User Login form requests, simply set user_registration / user_login to true inside Captcha's config and use the {{ captcha }} tag as normal inside Statamic's {{ user:register_form }} / {{ user:login_form }} tags.
Some of the Captcha services offer additional features, such as light/dark mode and sizing options, via data attributes. These can simply be added to the Captcha tag and will be passed through to the client-side widget.
{{ captcha data-theme="dark" data-size="compact" }}
You can now conditionally render Captcha only when it is enabled for the given form. This is especially useful when using dynamic or shared form templates.
Use the captcha:is_enabled tag as a boolean:
{{ if {captcha:is_enabled form="contact"} }}
{{ captcha }}
{{ /if }}
This checks your Captcha configuration and only outputs the Captcha fields when appropriate, it will always return true if your forms config is set to all.
This package is localized to English and German. If you need translations in another language, you can create them yourself:
- Create the translations file in
resources/lang/vendor/statamic-captcha/{language}/messages.php. - You can use the English translation file as a blueprint.
- You are welcome to share your translations here by submitting a PR.
If you want to change existing messages, you can publish and override them:
php please vendor:publish --tag="captcha-translations"
You can provide additional custom logic to determine if verification should be attempted using a custom invokable class. This is useful to adjust Captcha's shouldVerify check to include app-specific behaviour, for example: only enforcing Captcha for guest users and bypassing it for logged-in users.
To get started, create an invokable class within your app, and add it as the custom_should_verify property in your config:
<?php
return [
// ...
'custom_should_verify' => \App\Support\MyCustomShouldVerify::class,
];This invokable class must implement the \AryehRaber\Captcha\Contracts\CustomShouldVerify interface, which enforces that an event param gets passed into the invoke method and subsequently returns an optional boolean. To stop Captcha's shouldVerify method from getting called, the invoke method must return false, otherwise returning true (or null) will continue Captcha's verification logic.
Note: this custom class is resolved via Laravel's container, meaning dependency injection is available via the constructor.
<?php
namespace App\Support;
use AryehRaber\Captcha\Contracts\CustomShouldVerify;
class MyCustomShouldVerify implements CustomShouldVerify
{
public function __invoke($event): ?bool
{
// bypass verification for authenticated users
if (auth()->check()) {
return false;
}
// bypass verification on dev environment
if (app()->environment('dev')) {
return false;
}
// bypass verification based on event form submission
if ($event instanceof \Statamic\Events\FormSubmitted) {
// return $event->submission;
}
// bypass verification based on login event
if ($event instanceof \Illuminate\Auth\Events\Login) {
// return $event->user;
}
// bypass verification based on user registration event
if ($event instanceof \Statamic\Events\UserRegistering) {
// return $event->user;
}
// bypass verification based on entry saving event
if ($event instanceof \Statamic\Events\EntrySaving) {
// return $event->entry;
}
}
}