A Cloudflare Turnstile Validator for Laravel

This package provides a validator for Laravel to validate Cloudflare Turnstile responses. It is useful when you want to validate a reCAPTCHA response from a form.

Requirements

PHP 8.3 or higher
Laravel 11.0 or higher
Cloudflare Turnstile API key and secret

Installation

You can install the package via composer:

composer require versaorigin/cloudflare-turnstile

You can publish the config file with:

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

or, you can publish the config file with:

php artisan cloudflare-turnstile:install

This is the contents of the published config file:

return [
    'enabled' => env('CLOUDFLARE_TURNSTILE_ENABLED', true),

    'key' => env('CLOUDFLARE_TURNSTILE_KEY', ''),

    'secret' => env('CLOUDFLARE_TURNSTILE_SECRET', ''),

    'timeout' => env('CLOUDFLARE_TURNSTILE_TIMEOUT', 30),

    'connect_timeout' => env('CLOUDFLARE_TURNSTILE_CONNECT_TIMEOUT', 10),

    'retry' => [
        'times' => env('CLOUDFLARE_TURNSTILE_RETRY_TIMES', 3),
        'sleep' => env('CLOUDFLARE_TURNSTILE_RETRY_SLEEP', 1000),
    ],

    'cache' => [
        'enabled' => env('CLOUDFLARE_TURNSTILE_CACHE_ENABLED', true),
        'ttl' => env('CLOUDFLARE_TURNSTILE_CACHE_TTL', 300),
    ],
];

Usage

Basic Validation

$request->validate([
    "cf-turnstile-response" => ["required", "string", "turnstile"],
]);

Using the Validation Rule Class

use VersaOrigin\CloudflareTurnstile\Rules\CloudflareTurnstileRule;

$request->validate([
    "cf-turnstile-response" => ["required", "string", new CloudflareTurnstileRule],
]);

Blade Directive

Add the Turnstile widget to your forms easily:

<form method="POST" action="/submit">
    @csrf

    <!-- Your form fields -->

    @turnstile

    <button type="submit">Submit</button>
</form>

Middleware Protection

Protect entire routes with the Turnstile middleware:

use VersaOrigin\CloudflareTurnstile\Middleware\CloudflareTurnstileMiddleware;

Route::post('/api/protected', function () {
    // Your protected logic
})->middleware(CloudflareTurnstileMiddleware::class);

Programmatic Validation

use VersaOrigin\CloudflareTurnstile\Facades\CloudflareTurnstile;

$token = $request->input('cf-turnstile-response');
$ip = $request->ip();

if (CloudflareTurnstile::validate($token, $ip)) {
    // Valid response
} else {
    // Invalid response
    $errorMessage = CloudflareTurnstile::getErrorMessage();
}

Configuration Options

Retry Logic: Automatically retries failed requests with configurable attempts and delays
Caching: Prevents token replay attacks by caching successful validations
Logging: Failed validations are logged for debugging
Timeout Control: Configure connection and request timeouts

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.