- How do I install and set up Laravel Turnstile in my Laravel 12 project?
- Run `composer require coderflex/laravel-turnstile`, then publish the config and views with `php artisan vendor:publish --tag=turnstile-config`. Add your Cloudflare Turnstile site and secret keys to `.env` under `TURNSTILE_SITE_KEY` and `TURNSTILE_SECRET_KEY`. Finally, include the Blade component `<x-turnstile-widget />` in your form.
- Does this package work with Laravel Livewire or Inertia.js forms?
- Yes, the package works with Livewire and Inertia.js as long as your form includes the `cf-turnstile-response` field. For Livewire, ensure the field is bound to a property, and for Inertia.js, include it in your form submission payload. The validation logic remains the same as standard Laravel forms.
- What Laravel versions does this package support?
- The package supports Laravel 11 and 12. If you're using Laravel 10 or below, you’ll need to upgrade or consider a custom integration, as the package dropped support for older versions to align with modern PHP and Laravel features.
- How do I validate Turnstile responses in a Laravel controller?
- Use the facade method `LaravelTurnstile::validate($request->input('cf-turnstile-response'))` to verify the response programmatically. Alternatively, add the validation rule to your form request: `'cf-turnstile-response' => [new TurnstileCheck()].` Both methods handle errors and return responses consistently.
- Can I customize the Turnstile widget’s appearance (theme, language, size) in my Laravel app?
- Yes, the Blade component `<x-turnstile-widget />` accepts props like `theme`, `language`, and `size` to customize the widget. For example, `<x-turnstile-widget theme='dark' language='es' />` will render the widget in dark mode and Spanish. Check the published views for all available options.
- How do I test Turnstile validation locally without hitting Cloudflare’s API?
- Cloudflare provides dummy keys for testing. Use them in your `.env` file to bypass API calls during development. The package will still validate responses locally, allowing you to test form submissions without rate limits or API errors.
- What happens if Cloudflare changes the Turnstile API in the future?
- The package uses a facade layer to abstract API calls, so future changes by Cloudflare are isolated. Monitor Cloudflare’s changelog and update the package if needed. The facade pattern ensures minimal disruption to your application’s validation logic.
- Is there a way to cache Turnstile validation responses for better performance?
- Yes, you can cache validation responses using Laravel’s cache system. For high-traffic forms, store the response in Redis or another cache driver after validation to reduce API calls. This is especially useful if you expect repeated submissions from the same user.
- Can I use this package with multi-step forms where Turnstile is only on the final step?
- Yes, persist the `cf-turnstile-response` in a session or hidden field across steps. When the form is submitted, validate the response as usual. This approach ensures the CAPTCHA is only solved once per submission flow.
- Are there any known conflicts with other Laravel packages like Laravel Fortify or Spatie Laravel-Permission?
- No, the package has minimal dependencies (only Laravel core and Guzzle) and is designed to integrate seamlessly with other Laravel packages. It doesn’t interfere with Fortify’s authentication or Spatie’s permission systems, as it focuses solely on Turnstile validation and widget rendering.