README

Configurable Google reCAPTCHA for Filament forms — supports both v2 (checkbox) and v3 (invisible / score-based), switchable with a single config key.

• A drop-in Recaptcha::make('recaptcha') form field.
• Server-side token verification via Google's siteverify API.
• Auto-disables (renders nothing, skips validation) when not configured — so local dev and CI are unaffected.
• Configurable fail-open / fail-closed behaviour on a Google outage.

Requirements

• PHP 8.3+
• Laravel 13+
• Filament 5+

Installation

composer require ejoi8/filament-recaptcha

Publish the config (optional):

php artisan vendor:publish --tag=recaptcha-config

Configuration

Add your keys to .env:

RECAPTCHA_ENABLED=true
RECAPTCHA_VERSION=v2          # v2 | v3
RECAPTCHA_SITE_KEY=your-site-key
RECAPTCHA_SECRET_KEY=your-secret-key

# v3 only:
RECAPTCHA_V3_THRESHOLD=0.5
RECAPTCHA_V3_ACTION=submit

# On a Google outage: false = block submissions, true = allow them
RECAPTCHA_FAIL_OPEN=false

When RECAPTCHA_ENABLED=false or either key is blank, the field becomes a no-op (renders nothing, attaches no validation, makes no API calls) — so you don't need keys in development or CI.

Usage

Add the field to any Filament form schema:

use Ejoi8\FilamentRecaptcha\Forms\Recaptcha;

Recaptcha::make('recaptcha'),

That's it. The field renders the widget, captures the token client-side, and verifies it server-side on submit. The token is dehydrated(false), so it is never persisted.

Switching v2 ↔ v3

Set RECAPTCHA_VERSION=v3 and use v3 site/secret keys. The field switches between the v2 checkbox and the invisible v3 grecaptcha.execute flow automatically at render time. For v3, tune the score with RECAPTCHA_V3_THRESHOLD and set the expected RECAPTCHA_V3_ACTION.

License

MIT — see LICENSE.md.