v3
Field
The token is fetched on form submit (not on page load),
preventing unexpected challenge popups. The form is auto-resolved
via closest("form") — no formId needed
when the hidden input is inside the form.
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();
Options
withSiteKey(string)
Explicit site key override. Optional — pulled from config by default. Default: from config.
withAction(string)
Action name sent to Google (must match the rule's action if set). Default: ''.
withFormId(string)
Explicit form ID. When omitted the form is auto-resolved via closest("form").
withBadge(RecaptchaV3Badge)
BottomRight, BottomLeft, or Hidden. Default: BottomRight.
withJsApiUrl(string)
Custom JS API URL. Default: Google CDN.
withTranslator(?TranslatorInterface)
Translator for the hidden badge legal notice. Default: from registry.
withExecuteTimeout(?int)
Fallback form submission timeout (null = disabled). Default: 5000 ms.
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).
Validation
Use the attribute on your form model property:
use YiiRocks\Recaptcha\RecaptchaV3Rule;
final class LoginForm
{
#[RecaptchaV3Rule(
threshold: 0.5,
action: 'login',
sendRemoteIp: true,
)]
public string $gRecaptchaResponse = '';
}
Important: If you set ->withAction('...') on the v3 field,
you must also set action: '...' on the rule with the same value.
If neither is set, no action is sent and the check is skipped entirely.
Rule parameters
threshold
Minimum score (0.0 — 1.0). Default: 0.5.
action
Expected action name (skipped if null). Default: null.
message
Error message (translatable). Default: 'The CAPTCHA verification failed.'.
scoreTooLowMessage
Error when score is below threshold. Default: 'The CAPTCHA score is too low.'.
actionMismatchMessage
Error when action doesn't match. Default: 'The CAPTCHA action does not match.'.
secret
Custom secret (uses config default if null). Default: null.
sendRemoteIp
Whether to include the user's IP in verification. Default: false.
