ket-php/turnstile

KetPHP-Turnstile is a PHP library for seamless integration of the Cloudflare Turnstile bot protection system. It provides an object-oriented interface for token verification and detailed analysis of API responses.

1.0 2026-03-13 12:46 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.10

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Alexander Mikhno

• php
• middleware
• captcha
• cloudflare
• anti spam
• turnstile
• anti bot
• cfturnstile
• ketphp
• ket-php

README

Installation

Install via Composer:

composer require ket-php/turnstile

Usage

Basic token verification:

use KetPHP\Turnstile\Turnstile;

$secretKey = '<YOUR_SECRET_KEY>';
$token = $_POST['cf-turnstile-response'];

$turnstile = new Turnstile($secretKey);
if ($turnstile->verify($token)) {
    echo 'Valid!';
} else {
    echo 'Invalid.';
    print_r($turnstile->getResponse()->getErrorCodes());
}

// Inline variant
echo Turnstile::newInstance($secretKey)->verify($token) ? 'Valid' : 'Invalid';

Detailed response processing:

use KetPHP\Turnstile\Turnstile;

$secretKey = '<YOUR_SECRET_KEY>';
$token = $_POST['cf-turnstile-response'];

$turnstile = new Turnstile($secretKey);

$turnstile->verify($token, $_SERVER['REMOTE_ADDR']);

$response = $turnstile->getResponse();

if ($response->isSuccess()) {
    echo 'Host: ' . $response->getHostName();
    echo 'Time: ' . $response->getChallengeAt()->format('Y-m-d H:i:s');
    
    // Checking whether the test key has been used
    if ($response->getMetaData()->isTest()) {
        echo 'Is test request.';
    }
} else {
    foreach ($response->getErrorCodes() as $code) {
        echo 'Description: ' . \KetPHP\Turnstile\ErrorCode::getDescription($code);
        echo 'Action: ' . \KetPHP\Turnstile\ErrorCode::getAction($code);
    }
}