- Does this package work with Filament v3.x or v4 beta?
- This package is explicitly designed for Filament v3.x (tested up to v3.0). While it may work with Filament v4 beta, compatibility isn’t guaranteed. Pin `filament/filament` to `^3.0` in your `composer.json` to avoid version conflicts. Always check the package’s changelog for updates on v4 support.
- How do I add Turnstile to a Filament login or registration form?
- Use the `Turnstile::make()` method in your form’s schema. For example, in a custom login page, add it to the form fields like this: `$this->form([Turnstile::make('turnstile')])`. The package automatically handles validation and error display, so no extra JavaScript is needed.
- Can I use Turnstile with custom Filament resources (e.g., feedback forms)?
- Yes, the package integrates with Filament’s resource forms out of the box. Simply add `Turnstile::make()` to your resource’s `form` method. For example: `public static function form(Form $form): Form { return $form->schema([Turnstile::make('captcha')]); }`. It works alongside other form fields like text inputs or rich editors.
- What happens if Cloudflare Turnstile’s API is down or rate-limited?
- The package relies on Cloudflare’s API for validation, so downtime or rate limits may break CAPTCHA verification. Use Cloudflare’s testing keys during development and implement a fallback (e.g., manual review or a simple error message) for critical forms. You can also mock responses in tests using Laravel’s `Http::fake()`.
- How do I customize the Turnstile theme, size, or language?
- The package supports all Cloudflare Turnstile configurations, including themes, sizes, and languages. Pass these as options to `Turnstile::make()`. For example: `Turnstile::make('turnstile')->theme('light')->size('compact')->language('es')`. These settings are passed directly to Cloudflare’s script.
- Will this package slow down my Filament admin panel due to the Turnstile script?
- The Turnstile script is loaded asynchronously by default, minimizing impact on page load times. However, if performance is critical, consider lazy-loading the script or deferring it until the form is interacted with. Test in production to ensure it meets your performance benchmarks.
- Do I need to handle Turnstile errors manually, or does the package manage them?
- The package automatically handles validation errors and resets the CAPTCHA when needed, thanks to Filament’s event system. If validation fails, the error message appears inline with other form errors. You can customize the reset event name in the config file to avoid conflicts with other events in your app.
- Can I use this package without Cloudflare Turnstile already set up?
- Yes, the package requires a Cloudflare account and Turnstile keys, but you don’t need to use Turnstile elsewhere in your stack. Simply obtain your keys from Cloudflare’s dashboard, add them to your `.env` file, and publish the config. The package handles the rest, including script loading and validation.
- Are there alternatives to this package if I don’t want to use Cloudflare Turnstile?
- If you prefer other CAPTCHA providers like reCAPTCHA or hCaptcha, you’d need a different package. This one is specifically built for Cloudflare Turnstile and leverages Filament’s architecture. For reCAPTCHA, consider packages like `spatie/laravel-recaptcha` or `intervention/image` for custom solutions, but they won’t integrate as seamlessly with Filament forms.
- How do I test Turnstile integration in my Filament application?
- Use Cloudflare’s testing keys during development to avoid hitting rate limits. For automated testing, mock Cloudflare’s API responses with Laravel’s `Http::fake()` to simulate successful or failed validations. Test form submissions in both happy and error scenarios to ensure the CAPTCHA behaves as expected in your workflows.