- How do I install and configure derekcodes/turnstile-laravel in a Laravel app?
- Install it with Composer using composer require derekcodes/turnstile-laravel. Laravel's package auto-discovery registers the service provider, so you normally just add your Turnstile site key and secret key to your environment file and config. Publish the config file if you need to customise keys, endpoint, or timeout values, then add the widget to the forms you want to protect. Before rolling out, verify the flow on staging using Cloudflare's published test keys.
- Which Laravel and PHP versions does this Turnstile package support?
- Support is defined by the package's composer.json, so check the require constraints on Packagist and in the repository before committing. The last release was in March 2025, so confirm the constraints against your application's PHP and Laravel matrix and your CI pipeline. If you are on a newer Laravel major, run a non-production spike rather than assuming compatibility.
- How do I add the Cloudflare Turnstile widget to a Blade form?
- The package provides simple Blade helpers so you can drop the Turnstile widget into a form without hand-writing Cloudflare's script tag and container element. Place the helper output inside the form that will post the token back to your server. If you write the markup manually instead, include Cloudflare's script and allow it in your Content Security Policy.
- Does it include a Laravel validation rule for verifying Turnstile tokens server-side?
- Yes, the main integration point is a validation rule you attach to FormRequests or inline validate calls in controllers. The rule takes the submitted token and verifies it against Cloudflare's siteverify endpoint, so missing or invalid tokens fail validation like any other field. That keeps bot protection inside Laravel's standard validation and error-message flow instead of ad hoc controller code.
- Can I fake or mock Turnstile in my Laravel tests?
- A good fake or mock helper lets you skip the outbound HTTP call in tests, so check the repository's test suite and documentation to confirm one exists and how it is used. If none is provided, point the package at a local stub endpoint via config or bind a fake HTTP client in the container. Either way, keep at least one integration test covering the real verification path.
- Does the package verify hostname, action, and cdata, or just the success flag?
- This is a key diligence item, because Cloudflare's siteverify response includes hostname, action, cdata, and error codes beyond the success boolean. Read the source or docs to confirm which fields the rule actually checks, and add your own assertions if it only inspects success. For sensitive flows such as login, checkout, or password reset, pinning the action and hostname prevents token reuse from another form on your site.
- How are timeouts, retries, and Cloudflare outages handled?
- Validation makes a synchronous outbound HTTP call to Cloudflare, so set a short timeout and decide deliberately whether failures should fail open or fail closed. Incomplete verification semantics and accidental fail-open behaviour are the main risks flagged in technical review, so read the source for how non-200 responses and malformed JSON are treated. If you need per-form policy or retry logic, wrap the call behind an internal adapter.
- Does it work with Laravel Octane and config caching?
- Because it is a thin adapter over Laravel's HTTP client and config repository, it should work under Octane and with php artisan config:cache, provided keys are read from config rather than env() directly at runtime. Test both in staging, since env() calls outside config files break once configuration is cached. Long-running workers also mean you should confirm no verification state is cached across requests.
- Is this package production-ready given its modest adoption?
- It is a small, security-sensitive wrapper with roughly 57 stars, zero dependents, and a last release in March 2025, so single-maintainer and abandonment risk is real. The upside is that replacement cost is low: siteverify is easy to reimplement with Laravel's HTTP client behind an internal CaptchaVerifier interface. Pilot it behind a feature flag on one low-risk form and keep a rollback path to your existing provider.
- How should I manage Turnstile keys and CSP requirements?
- Keep the site key and secret key in your environment file only, reference them through config, and never commit the secret or expose it to the browser. Cloudflare's widget script and iframe need explicit Content Security Policy allowances, and your egress rules must permit outbound calls to the siteverify endpoint. Use Cloudflare's test keys in local development so production credentials are not used outside production.