Download the PHP package laragear/turnstile without Composer
On this page you can find all versions of the php package laragear/turnstile. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package turnstile
Turnstile
Use Cloudflare's no-CAPTCHA with HTTP/3 in your Laravel application.
Become a sponsor
Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word on social media!.
Requirements
- PHP 8.3 or later
- Laravel 12 or later
Installation
You can install the package via Composer:
Setup
This library comes already with the official demonstration keys to start developing your application with Cloudflare Turnstile immediately.
Once in production, you will require real keys, both of them obtainable through your Cloudflare Dashboard, and set as environment variables:
Frontend integration
This library comes with two Blade Components to easy your development pain: <x-turnstile::script /> and <x-turnstile::widget />.
Script
You can use the <x-turnstile::script /> Blade Component to implement the Cloudflare Turnstile script in your <head> tag of your HTML view.
The script will render a <script> tag using async and defer by default:
If you don't want to use async or defer, you can set any of these to false.
You may also set explicit to true to make widgets be rendered only explicitly by your frontend JavaScript.
Finally, you can also set a custom callback name to be executed once the script is completely loaded in your frontend, especially if you're using explicit rendering, with the onload attribute.
Site Key on JavaScript frontend
If you put the script on the <head> part of your HTML view, you may set the meta attribute to render a <meta> tag alongside the script. This tag will contain your Turnstile site-key so your JavaScript frontend can use it to render the widget.
It will render the following HTML:
You will be able to retrieve the site key through Javascript by querying the meta tag with the turnstile-sitekey name.
Alternatively, you may set a custom name for the tag by setting a value to the meta attribute.
Preconnect
You can also add a resource hint to Cloudflare servers by setting the preconnect attribute in the component.
Widget
[!IMPORTANT]
Remember that the Widget Mode is controlled via your Cloudflare Dashboard, not here. In development, this is controlled with testing keys.
You can use the <x-turnstile::widget /> Blade Component to add the Turnstile Widget in your forms. Depending on the Widget Mode, the Widget may render as usual or be invisible at Turnstile discretion.
You can pass HTML attributes and data attributes to change the widget behavior. For example, you can use the data-action to differentiate multiple widgets in your application, or data-error-callback to execute a JavaScript function in your frontend if the challenge fails.
[!TIP]
Classes are automatically appended, so you shouldn't worry about overwriting the
cf-turnstileclass used by the Widget to render.
Backend integration
When issuing a form, you have three alternatives to ensure the Turnstile challenge is valid and successful, from the easiest to the more flexible:
- Use the
TurnstileRequestrequest on the controller action. - Use the
turnstilemiddleware on the route. - Use the
turnstilerule on the Request validation. - Manually retrieve the Challenge.
[!WARNING]
All methods will fail on server-side errors:
- The Cloudflare Turnstile servers are unreachable.
- The request to Cloudflare Turnstile servers is malformed.
- The token is duplicated or had a timeout.
Connection problems will always throw an exception.
Validating with Request
The easiest and least intrusive way to check the Turnstile Challenge is to use the Laragear\Turnstile\Http\Requests\TurnstileRequest instance in your controller. This is great if you only have a few controllers where you want to stop bots.
You can have access to the Cloudflare Turnstile Challenge object through the challenge() method, plus additional helpers for the Challenge instance itself. For example, you may use it to double-check if the action is equal to something you expect.
[!IMPORTANT]
The Request will check for the
cf-turnstile-responsekey validate manually.
Extending the Form Request
If you need to create a form request and also validate the Turnstile Challenge, you may safely extend the TurnstileRequest instead of the base FormRequest. The class runs the validation before your form request authorization and rules to avoid running side effects.
This means your controller can safely retrieve the validated data using $request->validated(), as the token won't be considered part of the Request itself.
Custom key and rules
You may also edit the key and the rules where to find and check the Response Token in the request. For the case of rules, ensure you're using the turnstile rule.
Precognitive request
The TurnstileRequest won't check for the Challenge Token on Precognitive Requests, which is useful to not disrupt live-validation.
If you require custom validation on precognitive requests, you may override the skipChallengeWhenPrecognitive() method.
Extending the Form Request
If you need to create a form request and also validate the Turnstile Challenge, you may safely extend the TurnstileRequest instead. The class runs the validation before your form request authorization and rules.
This means your controller can safely retrieve the validated data using $request->validated().
Validating with Middleware
The turnstile middleware is a great way to check if a form submission contains a successful challenge. Simply add the middleware to the route (or group of routes) that receive the form submission, like a POST, PUT or PATCH.
[!NOTE]
Is not suggested to use the middleware on
GETmethods or similar. Some browsers (or extensions) may cache or inspect ahead document links.
If you want to configure the middleware behaviour, you should use the TurnstileMiddleware class and the static helper methods.
Custom challenge key
The middleware will check for the cf-turnstile-response key set in the form or JSON, by default. If you have edited your frontend to use another key, use the input() method of the middleware class with the key name.
Middleware bypass when authenticated
You can configure the authentication guards to bypass the challenge requirement if the user is authenticated through the auth() method.
By default, it will check the default authentication guard of your application. You may set specific guards by just naming them.
To complement this, you should add the widget to your forms only if the user is a guest for the given guards.
Middleware accepts failed challenges
You can allow the route to continue even if the challenge failed, using the acceptFailed() method.
Middleware checks action
If you have multiple Cloudflare Turnstile widgets in your application, and you have separated them through actions names, you can add a check to match the action name in the backend. If the action doesn't match, a validation exception will be thrown.
Validating on Precognitive
By default, the middleware will skip running on Precognitive requests. If you want to run it, set the TurnstileMiddleware::onPrecognitive() option, especially if your validation has side effects.
Validating with Rule
You can use the turnstile rule to check if the Turnstile challenge is present and is successful in the data to validate. The easiest way is to unpack the default rule contained in the rules() method of the Turnstile facade.
For more granular control, you can use the key method of the Turnstile facade to use the default keythat the Cloudflare Turnstile script injects into the form, and put your own additional validation rules if necessary.
Rule bypass when authenticated
If you want to bypass the rule check if the user is authenticated, set the auth parameter on the rule.
You may also add a list of guards to check by adding them after = and separating them by ,.
Rule accepts failed challenges
The rule supports not checking if the challenge is successful by setting the accept-failed parameter. This can be useful to retrieve the response later and programmatically continue based on the response result through the sucess() and failed() methods of the Turnstile facade.
Validating Manually
[!IMPORTANT]
The challenge is automatically retrieved by the use the
challenge()method instead.
To validate the Challenge manually, you require the Turnstile Response Token that is sent by the frontend, and optionally the IP of the Request.
Once identified, you should use the getChallenge() method of Turnstile facade to retrieve the Challenge from Cloudflare Turnstile servers.
You will receive a Laragear\Turnstile\Challenge instance with some useful helpers to check the challenge status.
Alternatively, if you're already using the default configuration, you can just use getChallengeFromRequest() which will automatically resolve the Request from the Container and find the token using the default key name.
Once the challenge is retrieved, is saved into the Application Container. This makes easier to retrieve the challenge elsewhere in your application. If you don't want to save the Challenge, set the save parameter to false.
Idempotency Keys
Because Cloudflare Turnstile Siteverify API will return an error when retrieving the same Challenge more than once, an idempotency key can be used in case of duplicate submissions.
How idempotency is handled will be up to your application. While most of the time is not needed at all, on some frontends the token may be resent anyway. To avoid errors, you can add a UUID string to both getChallenge() and getChallengeFromRequest() methods of the Turnstile facade.
Getting the correct client IP
If you're under a Cloudflare Proxy, can get the correct client IP through the CF-Connecting-IP header. This is set as a constant in the Turnstile class, so you can use it when retrieving the challenge:
Retrieving the Challenge on failure
If there is a server or backend error, the challenge retrieval will fail. If you still want to proceed, you may capture the exception and retrieve the Challenge with a try-catch block.
Retrieving an already received Challenge
The challenge() method of the Turnstile facade can be used to retrieve an already saved Turnstile Challenge inside the Application Container.
If you're not sure if the Challenge was received and saved, you can use both hasChallenge() and missingChallenge() beforehand.
Alternatively, you can use both success() and failed() methods to check if the challenge is successful or has failed, respectively. Of course, these must be invoked after the challenge have been retrieved.
Finally, you can always inject the Laragear\Tunrstile\Challenge anywhere in your application. For example, in your route controller action.
Interstitial challenge
You can force a first-time visitor to complete a Turnstile challenge with the turnstile.interstitial middleware. Once completed, the user will be redirected to its intended route.
Before using it, you should register the default routes to handle to show interstitial challenge and capture it. You can do this with the Laragear\Turnstile\Http\Controllers\InterstitialController::register() method.
You may change the default path the routes will use using the first parameter, and middleware using the second:
[!IMPORTANT]
The interstitial middleware will throw a JSON response if the request requires JSON. This is because JSON response cannot be redirected. Instead, use the
redirect_urlkey of the response to redirect the user to the interstitial controller.
Skip when authenticated
If you want to skip the challenge if a user is authenticated, you may add the auth keyword as parameter.
Alternatively, you can set which guards to check to skip the middleware by setting the guards as auth=guard&guard...
[!IMPORTANT]
When setting the middleware to be skipped for authenticated users, interstitial routes should also be hidden for authenticated users.
Global interstitial
If you want to register the middleware globally, you should do it in the web middleware group. This can be done in your bootstrap/app.php file or App\Providers\AppServiceProviders.
Livewire Trait
If you're using Liveware, you may use the Laragear\Turnstile\Livewire\InteractsWithTurnstile trait in your Livewire pages or components, alongside the widget in your frontend.
The trait overrides the validate() method the Component class, and validates the Turnstile Challenge only when all the validation rules pass.
If you're using a custom challenge key in your form, you may override the turnstileToken() method to retrieve the value of the token form elsewhere.
[!IMPORTANT]
The Challenge validation does not run when calling
validateOnly(). In that case, you should validate manually
Livewire manual validation
To detach the automatic validation of the Challenge, you can use the validatesTurnstileAutomatically() method and return false. This way, calling validate() in your component won't consume the challenge token.
After that, you may call validateTurnstile() manually in your component.
Handling the Turnstile Challenge
You have access to some useful methods to handle if the challenge should be deemed successful or not, and how to handle successes and failures:
skipTurnstileValidation(): Returns if the challenge verification should run or be skipped.handleTurnstileChallengeStatus(): Returns if the challenge is successful or not.handleSuccessfulTurnstileChallenge(): Handle a successful Turnstile challenge.handleFailedTurnstileChallenge(): Handle a failed Turnstile challenge.
For example, for non-admins, you may check if the challenge is successful if it matches the component action:
Filament Widget Field
If you're using Filament, you may use the Laragear\Turnstile\Filament\Forms\TurnstileWidget field in your forms. It will automatically inject the Turnstile Script in the page and render the Turnstile Widget. The Turnstile Challenge will be validated only on complete form submission.
The Widget includes some convenient methods based on the Cloudflare Turnstile Widget configuration:
| Method | Description |
|---|---|
normal() |
Sets the size of the widget to normal. |
flexible() |
Sets the size of the widget to flexible. |
compact() |
Sets the size of the widget to compact. |
system() |
Sets the theme of the widget to system/browser default. |
light() |
Sets the theme of the widget to light. |
dark() |
Sets the theme of the widget to dark. |
appearanceAlways() |
Sets the appearance of the widget to always appear. |
appearanceExecute() |
Sets the appearance of the widget to appear on manual execution. |
appearanceInteractionOnly() |
Sets the appearance of the widget to appear only when required. |
executionRender() |
Sets the execution of the widget challenge as it renders. |
executionExecute() |
Sets the execution of the widget challenge on manual execution. |
languageAuto() |
Sets the language of the widget to browser locale. |
language(string $lang) |
Sets the language of the widget to given locale. |
languageApp() |
Sets the language of the widget to application locale. |
tabindex(int $tabindex) |
Sets the tab order of the widget to one set. |
callback(string $functionName) |
Adds an additional function names to execute on successful challenges. |
actionName(string $functionName) |
Sets the action name for the challenge. |
implicit(bool $condition = true) |
Makes the widget be rendered automatically by the script. |
[!IMPORTANT]
The Filament Turnstile Widget is rendered implicitly by default, meaning its rendering is handled internally by AlpineJS. This makes all the options to be passed as a JavaScript object. You can use explicit rendering, but you may have problems if Livewire or Filament are configured to run in SPA mode or use islands.
Script injection
You don't need to manually inject the script in your app frontend, the Filament Widget Field does it automatically for you. Alternatively, disable the injection using withoutScript().
You may also pass the stack where the script should pushed if it's not scripts, and additional attributes to pass to the widget, using withScript().
[!NOTE]
If you use
implicit()rendering on the widget, the widget will automatically remove theexplicitflag from the script, which will make all widgets render as soon as possible.
Advanced configuration
Laragear Turnstile is intended to work out-of-the-box, but you can publish the configuration file for fine-tuning the Challenge verification.
You will get a config file with this array:
Environment
This sets which environment the library should run as. When null, it will mirror your current application environment.
- On
production, you will require your Site Key and Secret Key from Cloudflare Turnstile. - On
testing, challenges will be faked regardless, no keys needed. - On the rest of environments, testing keys will be automatically injected.
If you set false as the environment value, both rule won't retrieve challenges.
[!WARNING]
When using manual validation with the environment set as
false, you will receive a successful fake Challenge.
Form Key
This sets the default key to check for in the Request for the Turnstile response. By default, is cf-turnstile-response, but if you're using a custom frontend, you may change it here.
HTTP Client options
This array sets the options for the outgoing request to Cloudflare Turnstile servers. This is handled by Guzzle, which in turn will pass it to the underlying transport. Depending on your system, it will probably be cURL.
By default, it instructs Guzzle to use HTTP/3 (QUIC), with a graceful fallback to HTTP/2 if you're not using cURL or your cURL version does not support it.
Credentials
Here is the full array of Turnstile Site Key (public) and Secret Key (private) to use. These can be obtained through your Cloudflare Dashboard. Do not change the array unless you know what you're doing. If you want to set your keys, use the environment variables instead:
Interstitial
This controls the interstitial middleware behavior:
key: Where in the session is stored the challenge reminder.view: View to use to show the user as the interstitial challenge.route: The name of the route the middleware should point to.duration: Default duration to reminder the challenge. Thetruevalue will remind the challenge forever. An integer will remind the challenge for that amount of minutes.
Testing
On testing, or when the environment is testing, the library will automatically fake successful Challenges without contacting Cloudflare Turnstile servers.
You may create your own fake challenges easily using the fake() method of the Tunrstile facade. It accepts any of the Turnstile Challenge attributes, which is great to test multiple responses from Turnstile in your application.
Testing keys
This library incorporates the official testing Turnstile Site Keys and Secret Keys as the Laragear\Turnstile\Enums\SiteKey and Laragear\Turnstile\Enums\SecretKey, respectively.
The easiest way to change the testing keys on development is to change the environment variables on your .env files, as Laravel will automatically restart to pick up the changes. You can use the enum names, as these will be matched automatically to the corresponding testing key.
For the case of the widget, you may require to refresh your browser so the widget gets re-rendered with the selected key.
[!NOTE]
This doesn't work on production environments. Ensure you have your correct keys in production!
Inside your application, you can programmatically swap keys use the useTestingSiteKey() and useTestingSecretKey() methods of the Turnstile facade, along with the corresponding enums for the behaviour you require to check.
For the case of the widget, you can change the site key using the site-key attribute with the enum case name as value, in either kebab-case, snake_case, camelCase or StudlyCaps (these are normalized for you).
Laravel Octane compatibility
- There are no singletons using a stale application instance.
- There are no singletons using a stale config instance.
- There are no singletons using a stale request instance.
- There are no static properties written during a request.
There should be no problems using this package with Laravel Octane as intended.
Security
If you discover any security-related issues, please report it using the online form.
License
This specific package version is licensed under the terms of the MIT License, at the time of publishing.
Laravel is a Trademark of Taylor Otwell. Copyright © 2011–2026 Laravel LLC.
Cloudflare and Cloudflare Turnstile are trademarks of Cloudflare, Inc. Copyright © 2009–2026.
All versions of turnstile with dependencies
ext-json Version *
illuminate/support Version 12.*|13.*
illuminate/http Version 12.*|13.*
illuminate/routing Version 12.*|13.*
illuminate/container Version 12.*|13.*
illuminate/events Version 12.*|13.*
illuminate/session Version 12.*|13.*