README

Cloudflare Turnstile for Laravel 10+

Turnstile is a new user-friendly, privacy preserving alternative to CAPTCHA. This package provides a flexible way of integrating turnstile into your Laravel application. This package can be turned on and off for your convenience.

Info This package focuses on server side validation. You are free to implement your preferable client side technology such vue, reach, blade e.t.c

Version compatibility

Installation

You can install the package via composer:

composer require njoguamos/laravel-turnstile

You can initialise the package with:

php artisan turnstile:install

The install command will publish the config file.

Ensure that you have update your application .env with credentials from cloudflare i.e.

TURNSTILE_SITE_KEY=
TURNSTILE_SECRET_KEY=
TURNSTILE_ENABLED=true
#TURNSTILE_ENABLED=false -> when you want to disable e.g when testing

Usage

There are three way to use this package.

1. As a middleware

To use turnstile is specific routes of your application, you can register a new middleware in your laravel app/Http/Kernel.php.

class Kernel extends HttpKernel {
    // other class code
    
    protected $routeMiddleware = [
    // Other middlewares
        'turnstile' => \NjoguAmos\Turnstile\Http\Middleware\TurnstileMiddleware::class
    ];
}

Once the middleware has been defined in the HTTP kernel, you may use the middleware method to assign middleware to a route:

Route::get('/register', function () {
    //
})->middleware('turnstile');

Ensure your client side technology submit a turnstile token using a name defined in turnstile config file. Your can learn how to implement client side render from cloudflare website. Example:

Upon submitting the form, the turnstile token will be validated against turnstile api. If it fails, the request will be redirected back with status message. You can handle this message however you want in client side.

2. As a validation rule (v2.x.x)

You can user the inbuilt validation to validate form input

use NjoguAmos\Turnstile\Rules\TurnstileRule;

class RegisterRequest extends FormRequest
{
    /** @return array<string, array> */
    public function rules(): array
    {
        return [
            # Other fields
            'token'   => ['required', new TurnstileRule() ],
        ];
    }
    
    # Other code
}

3. Manual

You can validate turnstile token by calling validate method of Turnstile facade. The result will be true when token passed and false when token fails.

use NjoguAmos\Turnstile\Turnstile;

$isValid = (new Turnstile())->validate($token);

// Code is valid or invalid

If you would like to have more control on the response, you can use getResponse method of Turnstile facade. The result will be an instance of TurnstileResponse class.

use NjoguAmos\Turnstile\Turnstile;

$response = (new Turnstile())->getResponse($token);

// Result is an instance of \NjoguAmos\Turnstile\TurnstileResponse

Disabling

To increase the speed of your unit tests, you may wish to disable the turnstile. You can do so by setting TURNSTILE_ENABLED to false. i.e

#.env
TURNSTILE_ENABLED=false

When disabled,

• turnstile middleware will always pass
• turnstile validation rule will always pass

😀 Remember to turn turnstile on when you deploy.

Testing

Info This package does not mock request. It uses the secret keys provided by Cloudflare. Therefore, test scenarios hits the real turnstile api.

composer test

Changelog

Please see releases 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

• Njogu Amos
• All Contributors

License

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