README

A PHP SDK for Cloudflare Turnstile CAPTCHA alternative.

Installation

composer require wolfcode/cloudflare-turnstile

Quick Start

1. Render Widget (Frontend)

use Wolfcode\CloudflareTurnstile\Widget;

$widget = new Widget(
    siteKey: 'YOUR_SITE_KEY',
);
echo $widget->render();

2. Validate Token (Backend)

use Wolfcode\CloudflareTurnstile\Turnstile;
use Wolfcode\CloudflareTurnstile\Exception\ValidationException;

$turnstile = new Turnstile(
    secretKey: 'YOUR_SECRET_KEY',
);

try {
    $result = $turnstile->validate($_POST['cf-turnstile-response']);
    // Validation passed
} catch (ValidationException $e) {
    // Validation failed
    echo $e->getMessage();
}

Widget Configuration

Turnstile Configuration

Advanced Usage

Custom Guzzle Client

use GuzzleHttp\Client;
use Wolfcode\CloudflareTurnstile\Turnstile;

$client = new Client([
    'proxy' => 'tcp://localhost:8080',
    'timeout' => 30,
]);

$turnstile = new Turnstile(
    secretKey: 'YOUR_SECRET_KEY',
    client: $client,
);

Check Validity Without Exception

if ($turnstile->isValid($_POST['cf-turnstile-response'])) {
    // Valid token
}

Get Remote IP and Token

$token = Turnstile::getToken();
$remoteIp = Turnstile::getRemoteIp();

Widget Render Methods

Basic Render

$widget = new Widget(siteKey: 'YOUR_SITE_KEY');
echo $widget->render();

With Action

echo $widget->render(action: 'login');

With Custom Data

echo $widget->render(data: 'session-12345');

With Script Tag

echo $widget->renderComplete();

Testing

Cloudflare provides test keys for development:

These keys always pass validation and won't count against your quota.

Error Handling

use Wolfcode\CloudflareTurnstile\Exception\ValidationException;

try {
    $turnstile->validate($token);
} catch (ValidationException $e) {
    $errorCodes = $e->getErrorCodes();
    
    foreach ($errorCodes as $code) {
        match ($code) {
            'missing-input-response' => // Token not provided
            'invalid-input-response' => // Invalid or expired token
            'timeout-or-duplicate' => // Token already used
            'hostname_mismatch' => // Hostname doesn't match
            'action_mismatch' => // Action doesn't match
            default => // Unknown error
        };
    }
}

License

MIT License - see LICENSE for details.