README

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

• Adrian Mejias
• All Contributors

License

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