Yii3 reCAPTCHA ¶

1. Requirements
2. Installation
3. Configuration
4. Usage
5. License

Google reCAPTCHA v2 and v3 field + server-side validator for Yii3.

Requirements ¶

• PHP 8.3+
• PSR-18 HTTP client
• PSR-17 request + stream factories

Installation ¶

composer require yiirocks/recaptcha

A PSR-18 client and PSR-17 factories are required. If your application already has them configured (e.g. via Guzzle, Symfony HTTP Client, or any other implementation), no further setup is needed.

If not, install any compatible library, for example:

composer require guzzlehttp/guzzle nyholm/psr7

Configuration ¶

Set your site keys and secrets either via environment variables or directly in your application's config/params.php:

Environment variables (recommended) ¶

// config/params.php
return [
    'yiirocks/recaptcha' => [
        'siteKeyV2' => $_ENV['RECAPTCHA_SITE_KEY_V2'] ?? '',
        'secretV2'  => $_ENV['RECAPTCHA_SECRET_V2'] ?? '',
        'siteKeyV3' => $_ENV['RECAPTCHA_SITE_KEY_V3'] ?? '',
        'secretV3'  => $_ENV['RECAPTCHA_SECRET_V3'] ?? '',
    ],
];

If the env vars are not set the values fall back to empty strings — override them in your config/params.php as needed (the config-plugin merges them).

All parameters ¶

Tip: Once your site keys are set, fields will pull them from the registry automatically — no need to call withSiteKey() in your view code.

DI Configuration ¶

The config-plugin (config-plugin in composer.json) wires everything automatically:

• RecaptchaClient receives RecaptchaConfig plus PSR services from the container
• RecaptchaV2RuleHandler and RecaptchaV3RuleHandler are wired with optional client, request provider, and translator
• The translation category source is registered with the translation.categorySource tag
• The bootstrap callback populates RecaptchaRegistry with the client, request provider, and translator. This means fields and handlers work out of the box — no explicit withSiteKey() needed.

Usage ¶

All fields are rendered with a form model via the ::field() static method — the standard Yii3 form field pattern. Validation errors are shown automatically.

reCAPTCHA v2 ¶

use Yiisoft\FormModel\FormModel;
use YiiRocks\Recaptcha\RecaptchaV2Field;
use YiiRocks\Recaptcha\RecaptchaV2Theme;
use YiiRocks\Recaptcha\RecaptchaV2Size;
use YiiRocks\Recaptcha\RecaptchaV2Type;

echo RecaptchaV2Field::field($form, 'captcha')
    ->withTheme(RecaptchaV2Theme::Dark)
    ->withSize(RecaptchaV2Size::Compact)
    ->withType(RecaptchaV2Type::Audio)
    ->withId('my-captcha')
    ->withCallback('onSuccess')
    ->render();

Available options:

reCAPTCHA v3 ¶

The reCAPTCHA token is fetched on form submit (not on page load), preventing unexpected challenge popups:

use Yiisoft\FormModel\FormModel;
use YiiRocks\Recaptcha\RecaptchaV3Field;
use YiiRocks\Recaptcha\RecaptchaV3Badge;

echo RecaptchaV3Field::field($form, 'captcha')
    ->withAction('login')
    ->withFormId('login-form')
    ->withBadge(RecaptchaV3Badge::Hidden)
    ->render();

Available options:

Inherited from InputField:

• ->name(string) — override the hidden input name (default: auto-derived from form model as FormName[attribute])
• ->inputId(?string) — override the hidden input ID (default: auto-generated unique ID)

Container (inherited from BaseField):

• ->containerTag(string) — wrapper tag (default: div)
• ->containerClass(string ...) — wrapper CSS class(es) (default: mb-3)
• ->useContainer(bool) — enable/disable wrapper (default: true)
• ->containerAttributes(array) — set all wrapper attributes
• ->addContainerAttributes(array) — merge additional wrapper attributes

Hidden badge: When Badge::Hidden is selected, the legal notice text ("This site is protected by reCAPTCHA…") is displayed automatically and translated when a translator is available (either via withTranslator() or through RecaptchaRegistry).

Server-side validation ¶

v2 ¶

use YiiRocks\Recaptcha\RecaptchaV2Rule;

final class ContactForm
{
    #[RecaptchaV2Rule]
    public string $gRecaptchaResponse = '';
}

v3 ¶

use YiiRocks\Recaptcha\RecaptchaV3Rule;

final class LoginForm
{
    #[RecaptchaV3Rule(
        threshold: 0.5,
        action: 'login',
    )]
    public string $gRecaptchaResponse = '';
}

Important: If you set ->withAction('...') on the field, you must also set action: '...' on the rule with the same value. Otherwise Google will return a different action and validation will fail with "The CAPTCHA action does not match." If neither is set, no action is sent and the check is skipped entirely.

License ¶

MIT. See LICENSE.md.