PHPackages                             rasuvaeff/yii3-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. [Validation & Sanitization](/categories/validation)
4. /
5. rasuvaeff/yii3-turnstile

ActiveLibrary[Validation & Sanitization](/categories/validation)

rasuvaeff/yii3-turnstile
========================

Cloudflare Turnstile CAPTCHA widget and validator for Yii3.

v1.0.5(3w ago)03BSD-3-ClausePHPPHP 8.3 - 8.5CI passing

Since Jun 2Pushed 3w agoCompare

[ Source](https://github.com/rasuvaeff/yii3-turnstile)[ Packagist](https://packagist.org/packages/rasuvaeff/yii3-turnstile)[ Docs](https://github.com/rasuvaeff/yii3-turnstile)[ RSS](/packages/rasuvaeff-yii3-turnstile/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (3)Dependencies (40)Versions (7)Used By (0)

rasuvaeff/yii3-turnstile
========================

[](#rasuvaeffyii3-turnstile)

[![Stable Version](https://camo.githubusercontent.com/80c0820494765c7427b2703f165d2aa15f2a4c7d9b1a2d3a090cded9579ce2ae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7261737576616566662f796969332d7475726e7374696c653f6c6162656c3d737461626c6526736f72745f73656d7665723d31)](https://packagist.org/packages/rasuvaeff/yii3-turnstile)[![Total Downloads](https://camo.githubusercontent.com/ddb14eee15c402e55ca1ee7f52ba8dc58cbfcd2553a0c1cd03f84bea4e752ddc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7261737576616566662f796969332d7475726e7374696c65)](https://packagist.org/packages/rasuvaeff/yii3-turnstile)[![Build](https://camo.githubusercontent.com/01cbe56992e51f1932b36dcbb3b74383c00ca3b7256c1aba69c551f9d38416bc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d7475726e7374696c652f6275696c642e796d6c3f6272616e63683d6d6173746572)](https://github.com/rasuvaeff/yii3-turnstile/actions)[![Static analysis](https://camo.githubusercontent.com/5757aca9e789a3e508331e6ca76eb7b9ba9b50c9c041e1b0894c97a031c09d18/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d7475726e7374696c652f7374617469632d616e616c797369732e796d6c3f6272616e63683d6d6173746572266c6162656c3d737461746963253230616e616c79736973)](https://github.com/rasuvaeff/yii3-turnstile/actions)[![Psalm level](https://camo.githubusercontent.com/96f0376e917393dc04f5e50ef34fa74f202272a3100aa70c66ece3282f6a2e36/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7073616c6d2d6c6576656c253230312d3134314634383f6c6f676f3d7073616c6d266c6f676f436f6c6f723d7768697465)](https://github.com/rasuvaeff/yii3-turnstile/blob/master/psalm.xml)[![PHP](https://camo.githubusercontent.com/10f821ce061848aa592e627e7bfd7ad1db3a44d719bc0c329eabd3bbdf333a19/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7261737576616566662f796969332d7475726e7374696c652f706870)](https://packagist.org/packages/rasuvaeff/yii3-turnstile)[![License](https://camo.githubusercontent.com/fe4c30c361e41f5efa2bf2e423eb094b06c8323a5c8c34c609f7aa1a9193421f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7261737576616566662f796969332d7475726e7374696c65)](LICENSE.md)

Cloudflare Turnstile CAPTCHA widget and server-side validator for Yii3.

Provides a `Turnstile` widget for rendering the challenge in a form and a `TurnstileRule` / `TurnstileRuleHandler` pair for server-side verification through the Yii validator pipeline. HTTP calls go through any PSR-18 client.

> **Using an AI coding assistant?** [llms.txt](llms.txt) contains a compact API reference you can share with the model. Contributors: see [AGENTS.md](AGENTS.md).

Requirements
------------

[](#requirements)

RequirementVersionPHP`^8.3`A PSR-18 HTTP client + PSR-17 factoriesany implementation`yiisoft/widget``^2.2``yiisoft/html``^3.13`yiisoft/validator``^2.5``yiisoft/translator``^3.0``yiisoft/request-provider``^1.3`Installation
------------

[](#installation)

```
composer require rasuvaeff/yii3-turnstile
```

You also need a PSR-18 client and PSR-17 factories if your project doesn't already ship one:

```
composer require nyholm/psr7
# or: composer require guzzlehttp/guzzle
```

### DI configuration

[](#di-configuration)

Since v1.0.3 the package ships `config/bootstrap.php` via `config-plugin`. On every application boot it populates `TurnstileRegistry` with the handler dependencies, so `TurnstileRuleHandler` works even with the default `SimpleRuleHandlerContainer` — **no extra DI config required**.

If your app already uses `RuleHandlerContainer` for other reasons, keep it; this package is compatible with both resolvers.

Usage
-----

[](#usage)

### 1. Render the widget in a form

[](#1-render-the-widget-in-a-form)

```
use Rasuvaeff\Yii3Turnstile\Turnstile;
use Rasuvaeff\Yii3Turnstile\TurnstileTheme;
use Rasuvaeff\Yii3Turnstile\TurnstileSize;

// siteKey comes from DI config (TurnstileConfig)
echo Turnstile::widget()
    ->withTheme(TurnstileTheme::Light)
    ->withSize(TurnstileSize::Normal)
    ->withResponseFieldName('turnstileResponse'); // match your FormModel property name
```

Output:

```

```

### 2. Validate server-side with a validator rule

[](#2-validate-server-side-with-a-validator-rule)

```
use Rasuvaeff\Yii3Turnstile\TurnstileRule;
use Yiisoft\Validator\Validator;

class LoginForm
{
    #[TurnstileRule]
    public string $turnstileResponse = '';
}
```

> **Field name mapping with Yii3 FormModel**
>
> Cloudflare's widget submits the token as `cf-turnstile-response` (with hyphens) by default. PHP does **not** normalize hyphens in POST keys, so set `withResponseFieldName()` to a PHP-compatible name that matches your model property:
>
> ```
> echo Turnstile::widget()->withResponseFieldName('turnstileResponse');
> ```
>
>
>
> ```
> #[TurnstileRule]
> public string $turnstileResponse = '';
> ```

$result = (new Validator())->validate($loginForm);

```

The rule sends the token to Cloudflare's `siteverify` endpoint and reports
success/failure through the standard Yii validator `Result`.

### 3. Dependency injection (Yii3)

The package ships `config/params.php` and `config/di.php` compatible with
`yiisoft/config`. Override params in your application config:

```php
// config/params.php
return [
    'rasuvaeff/yii3-turnstile' => [
        'siteKey' => $_ENV['TURNSTILE_SITE_KEY'],
        'secret' => $_ENV['TURNSTILE_SECRET'],
        'verifyUrl' => 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
        'sendRemoteIp' => true,
        'translation.category' => 'yii3-turnstile',
    ],
];

```

The DI config registers a `CategorySource` tagged as `translation.categorySource`. When `yiisoft/translator-message-php` is installed, it reads message files from `messages//yii3-turnstile.php`. Without it, message IDs are returned as-is.

### 4. Translations

[](#4-translations)

The package includes Russian translations out of the box:

LocaleFile`ru``messages/ru/yii3-turnstile.php`To add more languages, create `messages//yii3-turnstile.php`:

```