- How do I install coderflex/laravel-turnstile in a Laravel application?
- Install it with composer require coderflex/laravel-turnstile, then publish the config file using php artisan vendor:publish --tag="turnstile-config". Add TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY to your .env file, keeping the secret key server-side only. The package auto-discovers its service provider, so no manual registration is required. It ships no migrations, so there is no schema footprint.
- Which Laravel and PHP versions does laravel-turnstile support?
- Version 2.1.1 dropped support for Laravel 10 and PHP 8.1, so current releases target Laravel 11+ on PHP 8.2+. Applications still on Laravel 10 or PHP 8.1 must pin the legacy 1.x line, which will not receive compatibility work for future Laravel majors. Confirm the supported constraint in composer.json before upgrading Laravel. This version gate is the biggest adoption constraint for older codebases.
- How do I validate a Turnstile token in a Laravel form request?
- Use the bundled validation rule inside your FormRequest: 'cf-turnstile-response' => ['required', new TurnstileCheck()]. For flows that do not use FormRequest, call LaravelTurnstile::validate($request->get('cf-turnstile-response')) imperatively from the controller. Both paths hit Cloudflare's siteverify endpoint server-side. The call is synchronous, so it sits directly in your request path.
- How do I render the Cloudflare Turnstile widget in a Blade view?
- Drop the package's Blade component into your form, typically as <x-turnstile-widget>, which renders Cloudflare's script and iframe and injects the cf-turnstile-response field automatically. Views are publishable if you need to customise markup or attributes. The component reads your site key from config or env. No JavaScript build step is required in your app.
- What Content-Security-Policy rules does the Turnstile widget need?
- Because the widget loads a Cloudflare-hosted script and an iframe, your CSP must allowlist the Turnstile origins in script-src and frame-src for each environment, or the widget silently fails to render and submissions block. Teams commonly start with a report-only policy to catch the exact origins before enforcing. This CSP work, not the package code, is usually the largest part of rollout effort.
- How can I test Turnstile forms without hitting the live Cloudflare endpoint?
- Cloudflare publishes documented dummy site and secret keys that always pass or always fail, which gives you a staging and CI path without live traffic. Whether you can intercept the siteverify call with Http::fake() depends on whether the package routes through Laravel's HTTP client, so verify that in the source before relying on it. Confirm your test suite never calls the real endpoint, since that adds flakiness and outbound dependency. The package's own tests are a useful reference.
- What happens if Cloudflare's siteverify endpoint is slow or down during a form submission?
- Every protected submission makes a synchronous HTTPS request to Cloudflare, so their latency, timeout, and outage behaviour become yours. The package returns a success boolean and leaves fail-open versus fail-closed policy to you, which is the right design but means the decision must be made explicitly. Check the default timeout and whether it and any retry policy are injectable before shipping to production. For critical forms, consider a short timeout plus a documented fallback path.
- Is coderflex/laravel-turnstile actively maintained, and which Packagist name should I require?
- The README instructs composer require coderflex/laravel-turnstile while the Packagist badge and repository resolve to coderflexx/laravel-turnstile, so verify the canonical name at install time and pin it in composer.json. The project is effectively single-maintainer with laravel-shift bot PRs for major-version bumps, and adoption is thin (roughly 121 stars and no dependents). For a small adapter this is acceptable if you accept a fork-and-own contingency for a security control.
- Does the package forward the client IP or expose Cloudflare error codes for observability?
- The package is a thin adapter, and its visible surface collapses verification to a success boolean, so it is unclear from the docs whether remoteip or idempotency_key are forwarded to siteverify or whether Cloudflare's error-codes array is surfaced. Both matter: remoteip improves accuracy and idempotency_key affects duplicate submission handling, while error codes are needed for debugging and alerting. Read the source or ask the maintainer before depending on them. If they are missing, wrapping the validate() call or forking the adapter is straightforward given the small code surface.
- Can I customise or translate the Turnstile validation error message?
- Yes. The published config file contains the error copy used by the validation rule, so you can change the wording or return a translation key for localised applications. Publish the config with the turnstile-config tag, edit the message, and optionally add matching entries to your lang files. This keeps user-facing failure text consistent with the rest of your Laravel validation messages.