Inspired on recaptcha
- Installation
- Getting started
- Usage
composer require usarise/turnstile
composer require symfony/http-client nyholm/psr7 usarise/turnstile
<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use Symfony\Component\HttpClient\Psr18Client;
use Turnstile\Error\Code;
use Turnstile\Turnstile;
// Get real API keys at https://dash.cloudflare.com/?to=/:account/turnstile
$siteKey = '1x00000000000000000000AA'; // Always passes (Dummy Testing)
$secretKey = '1x0000000000000000000000000000000AA'; // Always passes (Dummy Testing)
if ($token = $_POST['cf-turnstile-response'] ?? null) {
$turnstile = new Turnstile(
client: new Psr18Client(),
secretKey: $secretKey,
);
$response = $turnstile->verify(
$token, // The response provided by the Turnstile client-side render on your site.
$_SERVER['REMOTE_ADDR'], // With usage CloudFlare: $_SERVER['HTTP_CF_CONNECTING_IP']
);
if ($response->success) {
echo 'Success!';
} else {
$errors = $response->errorCodes;
var_dump($errors);
var_dump(Code::toDescription($errors));
}
exit;
}
?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Turnstile example</title>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
<form action="" method="POST">
<!-- The following line controls and configures the Turnstile widget. -->
<div class="cf-turnstile" data-sitekey="<?php echo $siteKey; ?>" data-theme="light"></div>
<!-- end. -->
<button type="submit" value="Submit">Verify</button>
</form>
</body>
</html>var_dump((string) $response);var_dump($response->toArray());var_dump($response->toArray(strict: true));use Turnstile\Client\Client;
use Turnstile\Turnstile;
$turnstile = new Turnstile(
client: new Client(...),
secretKey: 'secret key',
idempotencyKey: 'idempotency key',
);PSR-18 Clients like php-http/discovery
$turnstile = new Turnstile(
client: new Psr18Client(),
secretKey: 'secret key',
idempotencyKey: 'idempotency key',
);use Turnstile\Client\Client;
use Turnstile\TurnstileInterface;
$client = new Client(
client: ..., // implementation Psr\Http\Client\ClientInterface
requestFactory: ..., // implementation Psr\Http\Message\RequestFactoryInterface (default: requestFactory = client)
streamFactory: ..., // implementation Psr\Http\Message\StreamFactoryInterface (default: streamFactory = requestFactory)
siteVerifyUrl: TurnstileInterface::SITE_VERIFY_URL, // https://challenges.cloudflare.com/turnstile/v0/siteverify (default)
);composer require guzzlehttp/guzzle
use GuzzleHttp\Client as GuzzleHttpClient;
use GuzzleHttp\Psr7\HttpFactory;
use Turnstile\Client\Client;
$client = new Client(
new GuzzleHttpClient(),
new HttpFactory(),
);composer require symfony/http-client nyholm/psr7
use Symfony\Component\HttpClient\Psr18Client;
use Turnstile\Client\Client;
$client = new Client(
new Psr18Client(),
);use Symfony\Component\HttpClient\Psr18Client;
$client = new Psr18Client();composer require symfony/http-client guzzlehttp/psr7
use GuzzleHttp\Psr7\HttpFactory;
use Symfony\Component\HttpClient\Psr18Client;
use Turnstile\Client\Client;
$client = new Client(
new Psr18Client(
responseFactory: new HttpFactory(),
),
);use GuzzleHttp\Psr7\HttpFactory;
use Symfony\Component\HttpClient\Psr18Client;
$client = new Psr18Client(
responseFactory: new HttpFactory(),
);composer require symfony/http-client guzzlehttp/psr7 php-http/discovery
use Symfony\Component\HttpClient\Psr18Client;
use Turnstile\Client\Client;
$client = new Client(
new Psr18Client(),
);use Symfony\Component\HttpClient\Psr18Client;
$client = new Psr18Client();composer require nyholm/psr7 php-http/curl-client
use Http\Client\Curl\Client as CurlClient;
use Nyholm\Psr7\Factory\Psr17Factory;
use Turnstile\Client\Client;
$psr17Factory = new Psr17Factory();
$client = new Client(
client: new CurlClient(
responseFactory: $psr17Factory,
streamFactory: $psr17Factory,
),
requestFactory: $psr17Factory,
);composer require php-http/discovery
use Http\Discovery\Psr18Client;
use Turnstile\Client\Client;
$client = new Client(
new Psr18Client(),
);use Http\Discovery\Psr18Client;
$client = new Psr18Client();The widget’s secret key. The secret key can be found under widget settings in the Cloudflare dashboard under Turnstile.
API keys at https://dash.cloudflare.com/?to=/:account/turnstile
1x0000000000000000000000000000000AA Always passes
2x0000000000000000000000000000000AA Always fails
3x0000000000000000000000000000000AA Yields a “token already spent” error
use Turnstile\Client\Client;
use Turnstile\Turnstile;
// Real API keys at https://dash.cloudflare.com/?to=/:account/turnstile
$secretKey = '1x0000000000000000000000000000000AA';
$turnstile = new Turnstile(
client: $client,
secretKey: $secretKey,
);If an application requires to retry failed requests, it must utilize the idempotency functionality.
You can do so by providing a UUID as the idempotencyKey parameter and then use $turnstile->verify(...) with the same token the required number of times.
composer require ramsey/uuid
use Ramsey\Uuid\Uuid;
use Turnstile\Client\Client;
use Turnstile\Turnstile;
$turnstile = new Turnstile(
client: $client,
secretKey: $secretKey, // The site’s secret key.
idempotencyKey: (string) Uuid::uuid4(), // The UUID to be associated with the response.
);
$response = $turnstile->verify(
$token, // The response that will be associated with the UUID (idempotencyKey)
);
if ($response->success) {
// ...
}
$response = $turnstile->verify(
$token, // The response associated with UUID (idempotencyKey)
);
if ($response->success) {
// ...
}$response = $turnstile->verify(
token: $_POST['cf-turnstile-response'], // The response provided by the Turnstile client-side render on your site.
);The remoteIp parameter helps to prevent abuse by ensuring the current visitor is the one who received the token.
This is currently not strictly validated.
$response = $turnstile->verify(
token: $_POST['cf-turnstile-response'], // The response provided by the Turnstile client-side render on your site.
remoteIp: $_SERVER['REMOTE_ADDR'], // The visitor’s IP address.
);$response = $turnstile->verify(
token: $_POST['cf-turnstile-response'], // The response provided by the Turnstile client-side render on your site.
remoteIp: $_SERVER['HTTP_CF_CONNECTING_IP'], // The visitor’s IP address.
);$response = $turnstile->verify(
...
challengeTimeout: 300, // Number of allowed seconds after the challenge was solved.
expectedHostname: $_SERVER['SERVER_NAME'], // Expected hostname for which the challenge was served.
expectedAction: 'login', // Expected customer widget identifier passed to the widget on the client side.
expectedCdata: 'sessionid-123456789', // Expected customer data passed to the widget on the client side.
);$response->success$response->errorCodes$response->challengeTs$response->hostname$response->action$response->cdataString with raw json data
(string) $responseDecoded json data
$response->toArray()Array of processed json data based on properties of Response class:
success, errorCodes, challengeTs, hostname, action, cdata
$response->toArray(strict: true)Convert error codes to a description in a suitable language (default english)
use Turnstile\Error\{Code, Description};
var_dump(
Code::toDescription(
codes: $response->errorCodes,
descriptions: Description::TEXTS, // Default
),
);