PHPackages                             wolfcode/cloudflare-turnstile - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. wolfcode/cloudflare-turnstile

ActiveLibrary[Utility & Helpers](/categories/utility)

wolfcode/cloudflare-turnstile
=============================

v0.0.3(1mo ago)0267↑144.4%3MITPHPPHP >8.0

Since Jun 2Pushed 1mo agoCompare

[ Source](https://github.com/wolf-leo/cloudflare-turnstile)[ Packagist](https://packagist.org/packages/wolfcode/cloudflare-turnstile)[ RSS](/packages/wolfcode-cloudflare-turnstile/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (3)Dependencies (1)Versions (4)Used By (3)

Cloudflare Turnstile PHP
========================

[](#cloudflare-turnstile-php)

A PHP SDK for Cloudflare Turnstile CAPTCHA alternative.

Installation
------------

[](#installation)

```
composer require wolfcode/cloudflare-turnstile
```

Quick Start
-----------

[](#quick-start)

### 1. Render Widget (Frontend)

[](#1-render-widget-frontend)

```
use Wolfcode\CloudflareTurnstile\Widget;

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

### 2. Validate Token (Backend)

[](#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
--------------------

[](#widget-configuration)

ParameterTypeDefaultDescription`siteKey`stringrequiredSite key from Cloudflare dashboard`theme`string`auto`Widget theme: `light`, `dark`, or `auto``size`string`normal`Widget size: `normal` or `compact``language`string`null`Language code (e.g., `en`, `zh-CN`)`appearance`string`null``always` or `interaction-only``retryEnabled`bool`true`Enable retry on network failure`retryInterval`int`1500`Retry interval in millisecondsTurnstile Configuration
-----------------------

[](#turnstile-configuration)

ParameterTypeDefaultDescription`secretKey`stringrequiredSecret key from Cloudflare dashboard`expectedHostname`string`null`Expected hostname for validation`action`string`null`Action identifier for validation`timeout`int`10000`Request timeout in millisecondsAdvanced Usage
--------------

[](#advanced-usage)

### Custom Guzzle Client

[](#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

[](#check-validity-without-exception)

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

### Get Remote IP and Token

[](#get-remote-ip-and-token)

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

Widget Render Methods
---------------------

[](#widget-render-methods)

### Basic Render

[](#basic-render)

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

### With Action

[](#with-action)

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

### With Custom Data

[](#with-custom-data)

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

### With Script Tag

[](#with-script-tag)

```
echo $widget->renderComplete();
```

Testing
-------

[](#testing)

Cloudflare provides test keys for development:

KeyValueSite Key`1x00000000000000000000AA`Secret Key`1x0000000000000000000000000000000AA`These keys always pass validation and won't count against your quota.

Error Handling
--------------

[](#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
-------

[](#license)

MIT License - see [LICENSE](LICENSE) for details.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance90

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity31

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

53d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/120efb64d81a9a893c2b64ca5e85db8574bde280628221e3897b9230487f01fd?d=identicon)[wolfcode](/maintainers/wolfcode)

---

Top Contributors

[![wolf-leo](https://avatars.githubusercontent.com/u/37436228?v=4)](https://github.com/wolf-leo "wolf-leo (5 commits)")

### Embed Badge

![Health badge](/badges/wolfcode-cloudflare-turnstile/health.svg)

```
[![Health](https://phpackages.com/badges/wolfcode-cloudflare-turnstile/health.svg)](https://phpackages.com/packages/wolfcode-cloudflare-turnstile)
```

###  Alternatives

[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k46](/packages/neuron-core-neuron-ai)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)[oat-sa/tao-core

TAO core extension

65143.7k124](/packages/oat-sa-tao-core)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)