README

Laravel Turnstile, is a package to help you implement cloudflare turnstile easily, and with no time.

Installation

You can install the package via composer:

composer require coderflex/laravel-turnstile

You can publish the config file with:

php artisan vendor:publish --tag="turnstile-config"

This is the contents of the published config file:

return [
    /*
    |--------------------------------------------------------------------------
    | Turnstile Keys
    |--------------------------------------------------------------------------
    |
    | This value is the site, and the secret key of your application, after creating an application
    | with Cloudflare turnstile, copy the site key, and use it here, or in the .env
    | file.
    | Note that the secret key should not be publicly accessible.
    |
    | @see: https://developers.cloudflare.com/turnstile/get-started/#get-a-sitekey-and-secret-key
    |
    */
    'turnstile_site_key' => env('TURNSTILE_SITE_KEY', null),

    'turnstile_secret_key' => env('TURNSTILE_SECRET_KEY', null),

    /*
    |--------------------------------------------------------------------------
    | Error Messages
    |--------------------------------------------------------------------------
    |
    | Here you can find the error messages for the application. You can modify
    | or translate the error message as you like.
    |
    | Note that you can translate the error message directly, without wrapping
    | them in translate helper.
    |
    */
    'error_messages' => [
        'turnstile_check_message' => 'The CAPTCHA thinks you are a robot! Please refresh and try again.',
    ],
];

Optionally, you can publish the views using:

php artisan vendor:publish --tag="turnstile-views"

Turnstile Keys

To be able to use Cloudflare Turnstile, you need to get the SiteKey, and the SecretKey from your Cloudflare dashboard

After Generating the keys, use TURNSTILE_SITE_KEY, and TURNSTILE_SECRET_KEY in your .env file

TURNSTILE_SITE_KEY=2x00000000000000000000AB
TURNSTILE_SECRET_KEY=2x0000000000000000000000000000000AA

If you want to test the widget, you can use the Dummy site keys and secret keys that Cloudflare provides.

Usage

Turnstile Widget Component

Once you require this package, you can use the turnstile widget in your form, like the following

<x-turnstile-widget 
    theme="dark"
    language="en-US"
    size="normal"
    callback="callbackFunction"
    errorCallback="errorCallbackFunction"
/>

As you can see, the widget has few options to use. You can know more about them in the configuration section

Turnstile Backend Validation

Once you used the widget component, in the frontend. You can validate Cloudflare Response, by using the validate method.

Here's an example:

use Coderflex\LaravelTurnstile\Facades\LaravelTurnstile;

public function store(Request $request)
{
    // maybe you want to validate your form first

    $response = LaravelTurnstile::validate();


    if (! $response['success']) { // will return boolean
        // do your logic
    }
}

You may, optionally, send the Cloudflare response with the validation method. Something like the following:

public function store(Request $request)
{
    ...
    $response = LaravelTurnstile::validate(
        $request->get('cf-turnstile-response'); // this will be created from the cloudflare widget.
    );
    ...
}

Turnstile Custom Rule

If you want clean validation, you can use the TurnstileCheck custom rule, along with your form validation. Here's an example:

use Coderflex\LaravelTurnstile\Rules\TurnstileCheck;

public function store(Request $request)
{
    $request->validate([
        'cf-turnstile-response' => [new TurnstileCheck()]
    ]);
}

The custom rule, will use the same logic, as the backend validation, but instead will check for the response, and return a validation message, if the captcha fails.

You can change the content of the validation message, in config/turnstile.php file

return [
    ...
    'error_messages' => [
        'turnstile_check_message' => 'The CAPTCHA thinks you are a robot! Please refresh and try again.',
    ],
];

PS: If you want to translate the message, just copy the message and translate it, because it uses the translator method behind the scene.

Real Life Example

In your blade file

<form action="" method="post">
    @csrf
    <div>
        <input type="text" name="name" />
        @error('name')
            <p class="error">{{ $message }}</p>
        @enderror
    </div>

    <div>
        <x-turnstile-widget theme="auto" language="fr"/>
        @error('cf-turnstile-response')
            <p class="error">{{ $message }}</p>
        @enderror
    </div>

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

In your controller:

use Coderflex\LaravelTurnstile\Rules\TurnstileCheck;
use Coderflex\LaravelTurnstile\Facades\LaravelTurnstile;

...

public function store(Request $request)
{
    $request->validate([
        'name' => ['required', 'string', 'max:250'],
        'cf-turnstile-response' => ['required', new TurnstileCheck()],
    ]);

    // or
    $response = LaravelTurnstile::validate();

    if (! $response['success']) {
        // do your thing.
    }

    // do your things.
}

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 the License File for more information.

coderflex / laravel-turnstile

Maintainers

Details