Getting Started

Minimal Setup

Installation:

composer require ddr/filament-captcha

Publish the config file (if needed):

php artisan vendor:publish --provider="Ddr\FilamentCaptcha\FilamentCaptchaServiceProvider"

Configure Providers: Edit config/filament-captcha.php to set your preferred provider (e.g., hcaptcha, recaptcha_v2, recaptcha_v3, or turnstile). Example for hCaptcha:

'providers' => [
    'hcaptcha' => [
        'enabled' => true,
        'site_key' => env('HCAPTCHA_SITE_KEY'),
        'secret_key' => env('HCAPTCHA_SECRET_KEY'),
    ],
],

First Use Case: Add the captcha field to a Filament form:

use Ddr\FilamentCaptcha\Fields\FilamentCaptcha;

protected static ?string $captchaProvider = 'hcaptcha'; // Set default provider

public function form(Form $form): Form
{
    return $form
        ->schema([
            FilamentCaptcha::make('captcha')
                ->label('Verify you are human')
                ->required(),
            // ... other fields
        ]);
}

Implementation Patterns

Common Workflows

Provider-Specific Configuration: Use the config/filament-captcha.php file to enable/disable providers and set keys. Example for reCAPTCHA v3:

'recaptcha_v3' => [
    'enabled' => true,
    'site_key' => env('RECAPTCHA_SITE_KEY'),
    'secret_key' => env('RECAPTCHA_SECRET_KEY'),
    'score_threshold' => 0.5, // Custom threshold for reCAPTCHA v3
],

Dynamic Provider Selection: Override the default provider per form or field:

FilamentCaptcha::make('captcha')
    ->provider('turnstile') // Override default
    ->label('Cloudflare Turnstile')
    ->required();

Validation Logic: The package handles validation automatically. Customize error messages in the config:

'messages' => [
    'hcaptcha.required' => 'Please complete the hCaptcha.',
    'recaptcha_v3.threshold' => 'You did not pass the reCAPTCHA v3 verification.',
],

Development Mode: Enable in config to bypass captcha checks during development:
```
'development_mode' => env('APP_ENV') === 'local',
```

Integration with Filament Resources: Add captcha to create/update forms:

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

Customizing the UI: Use Filament’s built-in styling or override the view:

FilamentCaptcha::make('captcha')
    ->extraAttributes(['class' => 'custom-captcha-class'])
    ->extraAttributes(['data-custom-attr' => 'value']);

Gotchas and Tips

Pitfalls

Environment Variables: Ensure all required keys (HCAPTCHA_SITE_KEY, RECAPTCHA_SECRET_KEY, etc.) are set in .env. Missing keys will throw exceptions during runtime.
Provider-Specific Quirks:
- reCAPTCHA v3: Requires a score_threshold in config. Default is 0.5. Adjust based on your needs.
- Turnstile: Ensure your domain is whitelisted in the Cloudflare dashboard.
- hCaptcha: If using a custom theme, ensure the site_key matches the theme configuration.
Caching Issues: If captcha verification fails intermittently, clear your cache:
```
php artisan cache:clear
php artisan view:clear
```
Development Mode: Forgetting to disable development_mode in production can expose your site to spam. Always set:
```
'development_mode' => false,
```
in config/filament-captcha.php for production.
Form Submission: Ensure the captcha field is included in the form submission. The package automatically validates it, but missing it can cause silent failures.

Debugging

Logs: Enable debug mode in the config to log captcha verification attempts:
```
'debug' => true,
```
Check storage/logs/laravel.log for errors.
Verification Failures: If a captcha fails validation, check the provider’s dashboard (e.g., Google reCAPTCHA Admin Console) for blocked IPs or invalid keys.

Testing: Use the development_mode to bypass captchas during testing:

'development_mode' => true,

Or mock the provider in PHPUnit tests:

$this->mock(FilamentCaptchaService::class)->shouldReceive('verify')->andReturn(true);

Tips

Provider Switching: Use the --provider option to switch providers dynamically:
```
FilamentCaptcha::make('captcha')->provider('recaptcha_v2');
```

Custom Drivers: Extend the package by creating a custom driver. Example:

namespace App\Providers;

use Ddr\FilamentCaptcha\Contracts\CaptchaProvider;
use Illuminate\Support\Facades\Http;

class CustomCaptchaProvider implements CaptchaProvider
{
    public function verify(string $response, array $config): bool
    {
        $result = Http::post('https://api.custom-captcha.com/verify', [
            'response' => $response,
            'secret' => $config['secret_key'],
        ]);

        return $result->successful();
    }

    public function renderView(): string
    {
        return view('custom-captcha::widget')->render();
    }
}

'providers' => [
    'custom' => [
        'enabled' => true,
        'class' => \App\Providers\CustomCaptchaProvider::class,
        'site_key' => env('CUSTOM_CAPTCHA_SITE_KEY'),
    ],
],

Performance: For high-traffic forms, consider lazy-loading the captcha script:
```
FilamentCaptcha::make('captcha')
    ->extraAttributes(['data-lazy-load' => 'true']);
```
Then use JavaScript to load the script dynamically.
Localization: Customize captcha labels and messages for different locales by publishing the language files:
```
php artisan vendor:publish --provider="Ddr\FilamentCaptcha\FilamentCaptchaServiceProvider" --tag="filament-captcha-lang"
```
Then override the translations in resources/lang/{locale}/filament-captcha.php.

Security: Restrict captcha keys to specific environments using Laravel’s env() helpers:

'recaptcha_v2' => [
    'enabled' => env('APP_ENV') !== 'local',
    'site_key' => env('RECAPTCHA_SITE_KEY'),
    'secret_key' => env('RECAPTCHA_SECRET_KEY'),
],

Filament Captcha Laravel Package