README

Multi-provider captcha integration for Filament forms, supporting hCaptcha, reCAPTCHA v2, reCAPTCHA v3, and Cloudflare Turnstile.

Features

• 🔒 Multiple captcha providers (hCaptcha, reCAPTCHA v2, reCAPTCHA v3, Turnstile)
• 🎨 Seamless integration with Filament forms
• ⚙️ Driver-based architecture for easy extension
• 🧪 Comprehensive test coverage
• 📦 Compatible with Filament v3, v4 and v5
• 🔧 Development mode support

Requirements

• PHP ^8.2
• Laravel 11, 12 or 13
• Filament 3, 4 or 5

Installation

composer require ddr/filament-captcha

Publish the configuration file (optional):

php artisan vendor:publish --tag="captcha-config"

Configuration

Add the following environment variables to your .env file based on your chosen provider:

hCaptcha

CAPTCHA_DRIVER=hcaptcha
HCAPTCHA_SITEKEY=your-site-key
HCAPTCHA_SECRET=your-secret-key

Get your keys at hCaptcha Dashboard.

Google reCAPTCHA v2

CAPTCHA_DRIVER=recaptcha_v2
RECAPTCHA_V2_SITEKEY=your-site-key
RECAPTCHA_V2_SECRET=your-secret-key

Get your keys at Google reCAPTCHA Admin Console.

Google reCAPTCHA v3

CAPTCHA_DRIVER=recaptcha_v3
RECAPTCHA_V3_SITEKEY=your-site-key
RECAPTCHA_V3_SECRET=your-secret-key
RECAPTCHA_V3_SCORE=0.5

Get your keys at Google reCAPTCHA Admin Console.

The RECAPTCHA_V3_SCORE determines the minimum score required to pass validation (0.0 - 1.0, default: 0.5).

Cloudflare Turnstile

CAPTCHA_DRIVER=turnstile
TURNSTILE_SITEKEY=your-site-key
TURNSTILE_SECRET=your-secret-key

Get your keys at Cloudflare Turnstile Dashboard.

Usage

In Filament Forms

use Ddr\FilamentCaptcha\Forms\Components\Captcha;

public function form(Form $form): Form
{
    return $form
        ->schema([
            // ... other fields
            Captcha::make('captcha'),
        ]);
}

Specifying a Driver

You can override the default driver:

Captcha::make('captcha')->driver('recaptcha_v2')

Custom Login Page

Create a custom login page extending Filament's base login:

<?php

namespace App\Filament\Pages\Auth;

use Ddr\FilamentCaptcha\Forms\Components\Captcha;
use Filament\Auth\Pages\Login as BaseLogin;
use Filament\Schemas\Schema;

class Login extends BaseLogin
{
    public function form(Schema $schema): Schema
    {
        return $schema
            ->components([
                $this->getEmailFormComponent(),
                $this->getPasswordFormComponent(),
                $this->getRememberFormComponent(),
                Captcha::make('captcha')->hiddenLabel(),
            ]);
    }
}

Then register it in your AdminPanelProvider:

->login(\App\Filament\Pages\Auth\Login::class)

Validation Rule

You can use the captcha validation rule independently:

use Ddr\FilamentCaptcha\Rules\Captcha;

$request->validate([
    'captcha' => ['required', new Captcha('hcaptcha')],
]);

Development Mode

The captcha field adapts its behavior based on which credentials are configured:

• No site key configured: the field is completely hidden and validation is skipped, allowing forms to work without any captcha setup.
• Site key configured, no secret key: the widget is displayed but server-side verification is skipped. Useful for testing the UI locally.
• Both keys configured: full captcha flow with server-side verification (production).

Customization

Publishing Assets

You can publish and customize the package's configuration, views, and translations:

# Publish configuration file
php artisan vendor:publish --tag="captcha-config"

# Publish views
php artisan vendor:publish --tag="filament-captcha-views"

# Publish translations
php artisan vendor:publish --tag="filament-captcha-translations"

Customizing Views

After publishing views, they will be available in resources/views/vendor/filament-captcha/. You can customize:

• Driver-specific widgets: resources/views/vendor/filament-captcha/drivers/*.blade.php
• Main component: resources/views/vendor/filament-captcha/forms/components/captcha.blade.php

Laravel will automatically use your published views instead of the package defaults.

Customizing Configuration

After publishing the config file, you can customize driver settings, verify URLs, and other options in config/captcha.php.

Provider Comparison

Testing

composer test          # Run tests
composer lint          # Check code style
composer lint:fix      # Fix code style
composer analyse       # Run static analysis
composer check         # Run all checks

License

The MIT License (MIT). Please see License File for more information.