- How do I install and configure romanzipp/laravel-turnstile in a Laravel app?
- Run composer require romanzipp/laravel-turnstile, then publish the package config file. Add TURNSTILE_SITEKEY and TURNSTILE_SECRET to your .env file. After that, add the validation rule to the relevant FormRequest and drop the Blade component into the matching form. The service provider is auto-discovered, so no manual registration is required.
- Which Laravel and PHP versions does laravel-turnstile support?
- The package targets a conventional Laravel application on PHP 8.1 or newer with the framework HTTP client available. Exact constraints live in the package composer.json, so check the illuminate/* and php requirements against your app version before committing. Because it is a small single-maintainer package, pin it against your current Laravel major and confirm whether an open pull request exists for the next major before you upgrade the framework.
- How do I add Turnstile validation to a Laravel FormRequest?
- Add the package's Turnstile validation rule to the rules array in your FormRequest alongside your existing field rules. It composes cleanly with existing rule sets, so you do not need to restructure how you validate the rest of the form. A failed check surfaces as a normal validation error, which means standard Laravel error handling and redirects work unchanged. Realistic effort is roughly half a day for the first form including test coverage, then minutes for each additional form.
- How do I render the Cloudflare Turnstile widget in a Blade form?
- Include the package's Blade component inside your form markup, next to the submit button. The component loads the Cloudflare-hosted script directly, so there is no Node build step and no change to your asset pipeline. Because rendering is delegated to Cloudflare's script, you should check the component's options if you need an explicit render mode or a custom action/cdata value rather than implicit rendering.
- How can I test Turnstile protected forms in CI without hitting Cloudflare?
- Cloudflare publishes dummy sitekeys for always-pass, always-block, and forced-interactive behavior. Point your test environment at those keys so you can exercise every branch in CI and staging without touching production credentials. This lets you assert both the success path and the rejection path deterministically in feature tests.
- Does laravel-turnstile fail open or closed when Cloudflare is unreachable?
- This is the single most important behavior to verify before putting the rule on an authentication or registration form. Failing closed means a Cloudflare outage locks users out; failing open means an outage silently removes your bot protection. Read the source of the validation rule and write an explicit test that simulates a connection exception so the semantics are known rather than assumed.
- Is the HTTP timeout on the Turnstile siteverify request configurable?
- The package delegates the siteverify call to Laravel's HTTP client, so the effective timeout depends on what the rule configures or what you set globally. A default Guzzle timeout sitting on a login form is a real outage vector, so confirm the value and make it explicit rather than inherited. If it is not configurable in the package, wrapping or forking the small rule is a trivial fix.
- Does laravel-turnstile work with Inertia or Livewire forms?
- The widget itself renders fine inside a Blade root view, including Inertia page components that use Blade. The extra work is pulling the token out of the widget callback and into the request payload your frontend submits. That is a small manual step rather than something the package handles for you, so budget a little time for the first non-plain-Blade form.
- How do I customize or localize the Turnstile validation error message?
- Validation failures surface through Laravel's normal validation pipeline, so you can override the message in your FormRequest messages method or in a lang file. The practical concern is comprehension: Turnstile tokens are single use and expire after roughly 300 seconds, so a user who leaves a tab open will fail verification. Make sure the message tells them to retry the check rather than showing a generic invalid response.
- Is laravel-turnstile maintained enough to use in production?
- It has low adoption, a single maintainer, and no downstream ecosystem acting as a canary, so there is no security disclosure process or release cadence guarantee. The code is MIT licensed and only a few hundred lines, which makes forking or vendoring it a trivial, low-risk mitigation. Treat the real decision as adopting Cloudflare Turnstile as your bot-mitigation vendor; the library choice is a reversible one-line swap that should not block a vendor decision that is independently sound.