#A simple package to help integrate Cloudflare Turnstile.

This packages provides an API integrating Laravel with Cloudflare's Turnstile product.

#Installation

You can install the package via Composer:

composer require ryangjchandler/laravel-cloudflare-turnstile

You should then add the following configuration values to your config/services.php file:

return [

    // ...,

    'turnstile' => [
        'key' => env('TURNSTILE_SITE_KEY'),
        'secret' => env('TURNSTILE_SECRET_KEY'),
    ],

];

Create your Turnstile keys through Cloudflare and add them to your .env file.

TURNSTILE_SITE_KEY="1x00000000000000000000AA"
TURNSTILE_SECRET_KEY="2x0000000000000000000000000000000AA"

#Usage

In your layout file, include the Turnstile scripts using the <x-turnstile.scripts> component. This should be added to the <head> of your document.

<html>
    <head>
        <x-turnstile.scripts />
    </head>
    <body>
        {{ $slot }}
    </body>
</html>

Once that's done, you can use the <x-turnstile /> component inside of a <form> to output the appropriate markup with your site key configured.

<form action="/" method="POST">
    <x-turnstile />

    <button>
        Submit
    </button>
</form>

To validate the Turnstile response, use the Turnstile rule when validating your request.

use Illuminate\Validation\Rule;
use RyanChandler\LaravelCloudflareTurnstile\Rules\Turnstile;

public function submit(Request $request)
{
    $request->validate([
        'cf-turnstile-response' => ['required', new Turnstile],
    ]);
}

#Customizing the widget

You can customize the widget by passing attributes to the <x-turnstile /> component.

To learn more about these parameters, refer to the offical documentation.

<form action="/" method="POST">
    <x-turnstile
        data-action="login"
        data-cdata="sessionid-123456789"
        data-callback="callback"
        data-expired-callback="expiredCallback"
        data-error-callback="errorCallback"
        data-theme="dark"
        data-tabindex="1"
    />

    <button>
        Submit
    </button>
</form>

#Livewire support

This package can also integrate seamlessly with Livewire.

You can use wire:model to bind the Turnstile response to a Livewire property directly.

<x-turnstile wire:model="yourModel" />

#Multiple widgets with Livewire

If you're using Livewire and need to have multiple widgets on the same page, each widget requires a unique ID.

<x-turnstile id="my_widget" wire:model="captcha" />

The id property must match this RegEx: /^[a-zA-Z_][a-zA-Z0-9_-]*$/. IDs that do not match the RegEx will trigger an exception.

#Writing tests

If you wish to write tests for your application that uses Turnstile, you can use the Turnstile facade to fake responses.

use RyanChandler\LaravelCloudflareTurnstile\Facades\Turnstile;

Turnstile::fake(): // Force a successful response.
Turnstile::fake()->fail(); // Force a failed response.
Turnstile::fake()->expired(); // Force an expired token response.

Instead of hardcoding the submitted Turnstile token, you can use the Turnstile::dummy() method to generate a dummy token.

post('/my-form', [
    'cf-turnstile-response' => Turnstile::dummy(),
])

#Testing

composer test

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

#Credits

#License

The MIT License (MIT). Please see License File for more information.

Install on iPhone/iPad

Laravel Cloudflare Turnstile