README

A CakePHP plugin for working with Cloudflare Turnstile.

Requirements

• PHP 8.2+
• CakePHP 5.x

Installation

composer require oppara/cakephp-turnstile

Load the plugin

bin/cake plugin load Oppara/Turnstile

Configuration

Set your Turnstile keys in the environment:

TURNSTILE_SITE_KEY=your-site-key
TURNSTILE_SECRET_KEY=your-secret-key

The plugin bootstrap exposes the following defaults through Configure::read('Turnstile'):

[
    'siteKey' => getenv('TURNSTILE_SITE_KEY') ?: null,
    'secretKey' => getenv('TURNSTILE_SECRET_KEY') ?: null,
    'verifyUrl' => 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
    'timeout' => 5,
    'responseFieldName' => 'cf-turnstile-response',
]

Usage examples

Views

Load the helper in src/View/AppView.php:

public function initialize(): void
{
    parent::initialize();

    $this->loadHelper('Turnstile.Turnstile');
}

Render the script tag and widget in a template:

echo $this->Turnstile->script();
echo $this->Turnstile->widget([
    'theme' => 'light',
    'size' => 'flexible',
]);

Or render both in one call:

echo $this->Turnstile->render([
    'theme' => 'light',
]);

If your site enforces a strict Content-Security-Policy with script-src 'nonce-…', pass the nonce to script():

echo $this->Turnstile->script(['nonce' => $cspNonce]);

src is always set to the official Cloudflare URL and cannot be overridden, so any attribute you pass is added to the script tag without touching src.

Controllers

Load the component in your controller:

public function initialize(): void
{
    parent::initialize();

    $this->loadComponent('Turnstile.Turnstile');
}

Read the token from the current request automatically:

use Oppara\Turnstile\Exception\TurnstileException;
use Psr\Log\LogLevel;

try {
    $success = $this->Turnstile->verify();
} catch (TurnstileException $e) {
    // Infrastructure / configuration error — not the user's fault.
    $this->log('Turnstile: ' . $e->getMessage(), LogLevel::ERROR);
    $this->Flash->error(__('Verification is temporarily unavailable. Please try again later.'));

    return $this->redirect(['action' => 'index']);
}

if (!$success) {
    // Cloudflare rejected the challenge — typically a user-side issue
    // (expired token, replayed token, unsolved challenge, …).
    $errors = $this->Turnstile->getResult()['error-codes'] ?? [];
    $this->log(
        sprintf('Turnstile rejected the challenge: %s', json_encode($errors)),
        LogLevel::WARNING,
    );
    $this->Flash->error(__('The challenge could not be verified. Please try again.'));

    return $this->redirect(['action' => 'index']);
}

// Verification passed — continue with the normal form handling.

Pass the token explicitly when needed:

$success = $this->Turnstile->verify(
    (string)$this->request->getData('cf-turnstile-response'),
    $this->request->clientIp(),
);

Note
When verify() is called without arguments, the component reads the token and remote IP from the current ServerRequest.
The component therefore assumes a controller with an initialized request property (the normal Web request lifecycle).
If you instantiate the component manually — for instance from a CLI command, queue worker, or isolated unit test — pass both arguments explicitly, or attach a ServerRequest to the controller first.

License

MIT