Filament Turnstile Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require l3aro/filament-turnstile
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="L3aro\FilamentTurnstile\FilamentTurnstileServiceProvider" --tag="config"
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \L3aro\FilamentTurnstile\FilamentTurnstilePlugin::make(),
           ]);
   }
   

3. Configure Cloudflare Turnstile Add your site key and secret to .env:

   FILAMENT_TURNSTILE_SITE_KEY=your_site_key
   FILAMENT_TURNSTILE_SECRET_KEY=your_secret_key
   

4. First Use Case Add Turnstile to a form in Filament:

   use L3aro\FilamentTurnstile\Components\Turnstile;
   
   Turnstile::make('turnstile')
       ->required()
       ->rules(['required', 'turnstile'])
       ->columnSpanFull(),
   

Implementation Patterns

Common Workflows

1. Form Integration Use Turnstile component in Filament forms (e.g., create/edit pages):

   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               // ... other fields
               Turnstile::make('turnstile')
                   ->label('Verify You Are Human')
                   ->required(),
           ]);
   }
   

2. Custom Validation Extend validation rules in your model:

   use Illuminate\Validation\Rules\Turnstile;
   
   public static function rules(): array
   {
       return [
           'turnstile' => ['required', Turnstile::make()],
       ];
   }
   

3. Dynamic Configuration Override plugin settings per panel:

   FilamentTurnstilePlugin::make()
       ->siteKey(env('FILAMENT_TURNSTILE_SITE_KEY_ALTERNATE'))
       ->theme('dark'),
   

4. API Integration Verify Turnstile responses in API routes:

   use L3aro\FilamentTurnstile\Facades\Turnstile;
   
   public function store(Request $request)
   {
       $validated = $request->validate([
           'turnstile' => ['required', Turnstile::make()],
       ]);
       // ...
   }
   

5. Multi-Language Support Localize Turnstile labels:

   Turnstile::make('turnstile')
       ->label(__('filament-turnstile::messages.verify'))
       ->hint(__('filament-turnstile::messages.hint')),
   

Gotchas and Tips

Pitfalls

1. Missing .env Configuration

   • Symptom: Turnstile widget fails to load or validation errors occur.
   • Fix: Ensure FILAMENT_TURNSTILE_SITE_KEY and FILAMENT_TURNSTILE_SECRET_KEY are set in .env.

2. CORS Issues

   • Symptom: Turnstile verification fails silently.
   • Fix: Ensure your Cloudflare Turnstile settings allow requests from your Filament domain.

3. Caching Stale Responses

   • Symptom: Validation fails intermittently.
   • Fix: Clear Filament cache (php artisan filament:cache:clear) or use Turnstile::make()->ignoreCache() for testing.

4. Theme Mismatch

   • Symptom: Turnstile widget appears out of place (e.g., light theme on dark panel).
   • Fix: Explicitly set the theme:

     Turnstile::make()->theme('dark'),
     

5. Rate Limiting

   • Symptom: Validation returns error-captcha-exhausted.
   • Fix: Check Cloudflare Turnstile dashboard for rate limits or adjust your FILAMENT_TURNSTILE_SECRET_KEY permissions.

Debugging Tips

1. Enable Debug Mode Add to .env:

   FILAMENT_TURNSTILE_DEBUG=true
   

   Logs verification responses to storage/logs/filament-turnstile.log.

2. Test Locally Use Cloudflare’s Turnstile test mode with:

   FILAMENT_TURNSTILE_TEST_MODE=true
   

3. Inspect Network Requests Check the POST /cdn-cgi/turnstile/v0/siteverify request in browser dev tools for errors.

Extension Points

1. Custom Verification Logic Override the default verification by binding your own validator:

   Turnstile::make()->validator(function ($response) {
       // Custom logic here
       return $response['success'];
   });
   

2. Event Listeners Listen for Turnstile events (e.g., TurnstileVerified):

   use L3aro\FilamentTurnstile\Events\TurnstileVerified;
   
   TurnstileVerified::listen(function ($model, $response) {
       // Log or process the response
   });
   

3. Blade Integration Use the @turnstile directive in custom Blade views:

   @turnstile('turnstile', [
       'theme' => 'light',
       'size' => 'normal',
   ])
   

4. Testing Mock Turnstile responses in tests:

   Turnstile::shouldReceive('verify')
       ->once()
       ->andReturn(['success' => true, 'error-codes' => []]);