Filament Turnstile Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require l3aro/filament-turnstile
   

2. Publish config (required for keys):

   php artisan vendor:publish --tag="filament-turnstile-config"
   

3. Add Turnstile keys to .env:

   TURNSTILE_SITE_KEY=your_site_key
   TURNSTILE_SECRET_KEY=your_secret_key
   

4. Use in a form (e.g., Login page):

   use l3aro\FilamentTurnstile\Forms\Turnstile;
   
   Turnstile::make('captcha')
       ->theme(TurnstileTheme::Auto)
       ->size(TurnstileSize::Normal)
   

First Use Case

Protect a Filament login form from bots:

// In your custom Login page class
protected function getForms(): array {
    return [
        'form' => $this->form()
            ->schema([
                // ... other fields
                Turnstile::make('captcha'),
            ]),
    ];
}

Implementation Patterns

Core Workflow

1. Form Integration:

   • Add Turnstile field to any Filament form (e.g., Login, Registration, or custom forms).
   • Configure via fluent methods (theme(), size(), language()).

2. Validation:

   • The package auto-validates Turnstile responses. No manual validation needed unless customizing.

3. Reset Logic:

   • Dispatch reset-captcha event after failed submissions (e.g., in onValidationError):

     protected function onValidationError(ValidationException $exception) {
         $this->dispatch(FilamentTurnstileFacade::getResetEventName());
     }
     

Advanced Patterns

• Dynamic Theming:

  Turnstile::make('captcha')
      ->theme($this->isDarkMode() ? TurnstileTheme::Dark : TurnstileTheme::Light)
  

• Multi-Language Support:

  Turnstile::make('captcha')
      ->language(app()->getLocale())
  

• Conditional Rendering:

  Turnstile::make('captcha')
      ->visible(fn () => $this->isHighRiskForm())
  

Integration Tips

• Panel-Level Override: Extend the default Login page in your PanelProvider:

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

• Testing: Use Cloudflare’s dummy keys for CI/CD:

  TURNSTILE_SITE_KEY=0x4AAAAAAAAAAAAAAAAAAAAAGGeSlV
  TURNSTILE_SECRET_KEY=0x4AAAAAAAAAAAAAAAAAAAAAGGeSlV
  

Gotchas and Tips

Pitfalls

1. Key Mismatch:

   • Ensure TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY match your Cloudflare dashboard.
   • Debug: Check browser console for 403 Forbidden errors (invalid secret key).

2. Event Naming Collisions:

   • Avoid using reset-captcha as a custom JavaScript event name elsewhere in your app.
   • Fix: Rename via config:

     'reset_event' => 'custom-reset-event',
     

3. Blade Template Issues:

   • If using custom views, ensure BackedEnum values are cast to strings (fixed in v1.0.7).

4. Livewire Reset Timing:

   • Delayed resets may occur if onValidationError runs after the form re-renders.
   • Workaround: Dispatch the event in updated():

     public function updated($property) {
         if ($this->wasSuccessful && $this->hasErrors()) {
             $this->dispatch(FilamentTurnstileFacade::getResetEventName());
         }
     }
     

Debugging Tips

• Cloudflare Debug Mode: Enable in .env to see detailed logs:

  TURNSTILE_DEBUG=true
  

• Network Tab: Inspect the /cdn-cgi/turnstile/v0/captcha endpoint for failed submissions.

Extension Points

1. Custom Validation: Override the default validation rule:

   Turnstile::make('captcha')
       ->rules(['custom.turnstile' => 'required|valid_turnstile'])
   

   Register the rule in a service provider:

   Validator::extend('valid_turnstile', function ($attribute, $value, $parameters) {
       return TurnstileValidator::validate($value);
   });
   

2. Theme/Size Enums: Extend existing enums for custom options:

   class CustomTurnstileSize extends TurnstileSize {
       public const Compact = 'compact';
   }
   

3. Event Listeners: Listen for Turnstile events globally:

   Event::listen(FilamentTurnstileFacade::getResetEventName(), function () {
       Log::info('Turnstile reset triggered');
   });