Download the PHP package yiirocks/recaptcha without Composer

Yii3 reCAPTCHA

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

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:

Configuration

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

Environment variables (recommended)

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

Available options:

reCAPTCHA v3

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

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

v3

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.