omnishield/turnstile

Cloudflare Turnstile as an Omnishield captcha: Cloudflare's widget (https://challenges.cloudflare.com/turnstile/v0/api.js) in the page, its token checked by POST https://challenges.cloudflare.com/turnstile/v0/siteverify. The visitor's browser talks to Cloudflare; Turnstile sets no cookie. Cloudflare publishes testing keys that answer for any host, which the gateway recognises.

Installation

composer require omnishield/turnstile

PHP 8.2 or later, omnisense/omnishield and symfony/http-client (a library; give the factory your application's client, a MockHttpClient in a test).

Credentials

A site key (the widget's) and a secret (siteverify's) of a Turnstile widget made in Cloudflare's dashboard for the site's hosts. For development, Cloudflare's testing keys (below).

The sources

Written from Cloudflare's documentation as it read on 2026-10-07: server-side validation (siteverify, its parameters, its answer, its error codes, a token's length and life), client-side rendering (the script, .cf-turnstile, its data-* attributes, the cf-turnstile-response field), testing (the dummy keys), and the Turnstile privacy addendum.

Options

new TurnstileGatewayFactory(?HttpClientInterface $http = null): the application's HTTP client. Constants: TurnstileGateway::SCRIPT, FIELD, MAX_LENGTH (2048), BASE_URI.

Capabilities

The check

POST https://challenges.cloudflare.com/turnstile/v0/siteverify: secret, response, remoteip (the attempt's address), idempotency_key. A token lasts 300 seconds, serves once and is at most 2048 characters long; a longer one, or an empty one, is refused without asking.

Verdict::$at is challenge_ts, $hostname and $action as Cloudflare read them.

Testing keys

The testing site keys produce the token XXXX.DUMMY.TOKEN.XXXX, which production secrets refuse. Cloudflare answers them with metadata.result_with_testing_key: true, the host example.com and no action: with them the action and the host are not checked, and the verdict's codes say result_with_testing_key.

Example

The widget, then a token checked four ways and two failures, Cloudflare's answers given by a MockHttpClient (run in omnishield's workspace on 2026-10-26, offline):

<?php

require 'vendor/autoload.php';

use Omnishield\Exception\InvalidKeyException;
use Omnishield\Exception\UnreachableException;
use Omnishield\Model\Attempt;
use Omnishield\Turnstile\TurnstileGatewayFactory;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;

$json = static fn (array $answer) => new MockResponse(json_encode($answer));
$http = new MockHttpClient([
    $json(['success' => true, 'challenge_ts' => '2026-10-25T08:00:00.000Z', 'hostname' => 'www.example.org', 'action' => 'contact', 'error-codes' => []]),
    $json(['success' => true, 'challenge_ts' => '2026-10-25T08:00:00.000Z', 'hostname' => 'www.example.org', 'action' => 'signup', 'error-codes' => []]),
    $json(['success' => false, 'error-codes' => ['timeout-or-duplicate']]),
    $json(['success' => false, 'error-codes' => ['invalid-input-secret']]),
    new MockResponse('', ['http_code' => 503]), new MockResponse('', ['http_code' => 503]),   // twice: the retry under the same idempotency key
]);
$turnstile = (new TurnstileGatewayFactory($http))->create(['site_key' => '0x4AAAAAAA-example', 'secret' => '0x4AAAAAAA-secret']);

$widget = $turnstile->widget('contact');
echo $widget->html(), "\n";
foreach (['contact', 'contact', 'contact'] as $action) {
    $verdict = $turnstile->verify(new Attempt('0.token-from-the-widget', '192.0.2.10', $action, 'www.example.org'));
    echo $verdict->passed ? 'passed' : 'refused: '.implode(', ', $verdict->reasons).' ('.implode(', ', $verdict->codes).')', "\n";
}
foreach ([InvalidKeyException::class, UnreachableException::class] as $expected) {
    try {
        $turnstile->verify(new Attempt('0.token-from-the-widget'));
    } catch (InvalidKeyException|UnreachableException $e) {
        echo $e::class, ': ', $e->getMessage(), "\n";
    }
}
echo $turnstile->verify(new Attempt(''))->reasons[0], ' (nothing sent); requests: ', $http->getRequestsCount(), "\n";

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script><div class="cf-turnstile" data-sitekey="0x4AAAAAAA-example" data-action="contact"></div>
passed
refused: action ()
refused: spent (timeout-or-duplicate)
Omnishield\Exception\InvalidKeyException: [turnstile] The secret was refused: invalid-input-secret.
Omnishield\Exception\UnreachableException: [turnstile] HTTP 503: 
missing (nothing sent); requests: 6

The two 503s are one check and its retry under the same idempotency key; the empty token is refused without a request.

In Symfony:

omnishield:
    gateways:
        cloudflare:
            factory: turnstile
            options: { site_key: '%env(TURNSTILE_SITE_KEY)%', secret: '%env(TURNSTILE_SECRET)%', appearance: interaction-only }

Errors

Verified, and not

Responsibility

This package is an independent, unofficial client: it is not affiliated with, endorsed by or sponsored by Cloudflare, Inc. It reaches their service on behalf of whoever runs it, and it does not redistribute their data beyond the short excerpts recorded as test fixtures. Its MIT licence covers this package's code only and grants no right to the service or to its data.

Whoever installs and runs this package is responsible for complying with Turnstile's terms (Cloudflare service-specific terms), for obtaining whatever they require (an account, a key, a licence or subscription, an attribution or a citation, a rate limit to respect), and for any use made of what it returns. The authors publish it free of charge, make no commercial use of it, and accept no liability for how it is used (see the package's LICENSE).