CaptchaValidator

API reference › yii › captcha › CaptchaValidator

class	`yii\captcha\CaptchaValidator`
Extends	`yii\validators\Validator` » `yii\base\Component` » `yii\base\BaseObject`
Implements	`yii\base\Configurable`
Since	2.0
Source	`framework/captcha/CaptchaValidator.php`

CaptchaValidator validates that the attribute value is the same as the verification code displayed in the CAPTCHA.

CaptchaValidator should be used together with CaptchaAction.

Note that once CAPTCHA validation succeeds, a new CAPTCHA will be generated automatically. As a result, CAPTCHA validation should not be used in AJAX validation mode because it may fail the validation even if a user enters the same code as shown in the CAPTCHA image which is actually different from the latest CAPTCHA code.

Properties

Property	Type	Description	Defined by
`$attributeNames` read-only	`array`	Attribute names.	`yii\validators\Validator`
`$attributes`	`array\|string`	Attributes to be validated by this validator. Default: `[]`.	`yii\validators\Validator`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$builtInValidators` static	`array`	List of built-in validators (name => class or configuration) Default: ['boolean' => 'yii\validators\BooleanValidator', 'captcha' => 'yii\captcha\CaptchaValidator', 'compare' => 'yii\validators\CompareValidator', 'date' => 'yii\validators\DateValidator', 'datetime' => ['class' => 'yii\validators\DateValidator', 'type' => \yii\validators\DateValidator::TYPE_DATETIME], 'time' => ['class' => 'yii\validators\DateValidator', 'type' => \yii\validators\DateValidator::TYPE_TIME], 'default' => 'yii\validators\DefaultValueValidator', 'double' => 'yii\validators\NumberValidator', 'each' => 'yii\validators\EachValidator', 'email' => 'yii\validators\EmailValidator', 'exist' => 'yii\validators\ExistValidator', 'file' => 'yii\validators\FileValidator', 'filter' => 'yii\validators\FilterValidator', 'image' => 'yii\validators\ImageValidator', 'in' => 'yii\validators\RangeValidator', 'integer' => ['class' => 'yii\validators\NumberValidator', 'integerOnly' => true], 'match' => 'yii\validators\RegularExpressionValidator', 'number' => 'yii\validators\NumberValidator', 'required' => 'yii\validators\RequiredValidator', 'safe' => 'yii\validators\SafeValidator', 'string' => 'yii\validators\StringValidator', 'trim' => ['class' => 'yii\validators\TrimValidator', 'skipOnArray' => true], 'unique' => 'yii\validators\UniqueValidator', 'url' => 'yii\validators\UrlValidator', 'ip' => 'yii\validators\IpValidator'].	`yii\validators\Validator`
`$captchaAction`	`string`	The route of the controller action that renders the CAPTCHA image. Default: `'site/captcha'`.	`CaptchaValidator`
`$caseSensitive`	`bool`	Whether the comparison is case sensitive. Default: `false`.	`CaptchaValidator`
`$clientScript`	`array\|yii\validators\client\ClientValidatorScriptInterface\|null`	Client script strategy used to register CAPTCHA client-side validation. Default: `null`.	`CaptchaValidator`
`$enableClientValidation`	`bool`	Whether to enable client-side validation for this validator. Default: `true`.	`yii\validators\Validator`
`$except`	`array\|string`	Scenarios that the validator should not be applied to. Default: `[]`.	`yii\validators\Validator`
`$isEmpty`	`callable\|null`	A PHP callable that replaces the default implementation of `isEmpty()`. Default: `null`.	`yii\validators\Validator`
`$message`	`string\|null`	The user-defined error message. Default: `null`.	`yii\validators\Validator`
`$on`	`array\|string`	Scenarios that the validator can be applied to. Default: `[]`.	`yii\validators\Validator`
`$skipOnEmpty`	`bool`	Whether to skip this validator if the input is empty. Default: `false`.	`CaptchaValidator`
`$skipOnError`	`bool`	Whether this validation rule should be skipped if the attribute being validated already has some validation error according to some previous rules. Default: `true`.	`yii\validators\Validator`
`$validationAttributes` read-only	`array\|null`	List of attribute names.	`yii\validators\Validator`
`$when`	`callable\|null`	A PHP callable whose return value determines whether this validator should be applied. Default: `null`.	`yii\validators\Validator`
`$whenClient`	`string\|null`	A JavaScript function name whose return value determines whether this validator should be applied on the client-side. Default: `null`.	`yii\validators\Validator`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__call()`	Calls the named method which is not a class method.	`yii\base\Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`yii\base\Component`
`__get()`	Returns the value of a component property.	`yii\base\Component`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\Component`
`__set()`	Sets the value of a component property.	`yii\base\Component`
`__unset()`	Sets a component property to be null.	`yii\base\Component`
`addError()`	Adds an error about the specified attribute to the model object.	`yii\validators\Validator`
`attachBehavior()`	Attaches a behavior to this component.	`yii\base\Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`yii\base\Component`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`yii\base\Component`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\Component`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\Component`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`clientValidateAttribute()`	Returns the JavaScript needed for performing client-side validation.	`CaptchaValidator`
`createCaptchaAction()`	Creates the CAPTCHA action object from the route specified by `$captchaAction`.	`CaptchaValidator`
`createValidator()` static	Creates a validator object.	`yii\validators\Validator`
`detachBehavior()`	Detaches a behavior from the component.	`yii\base\Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`yii\base\Component`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`yii\base\Component`
`getAttributeNames()`	Returns cleaned attribute names without the `!` character at the beginning.	`yii\validators\Validator`
`getBehavior()`	Returns the named behavior object.	`yii\base\Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`yii\base\Component`
`getClientOptions()`	Returns the client-side validation options.	`CaptchaValidator`
`getFormattedClientMessage()`	Returns the formatted validation message for client-side validation.	`yii\validators\Validator`
`getValidationAttributes()`	Returns a list of attributes this validator applies to.	`yii\validators\Validator`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`yii\base\Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`init()`	Initializes the object.	`CaptchaValidator`
`isActive()`	Returns a value indicating whether the validator is active for the given scenario and attribute.	`yii\validators\Validator`
`isEmpty()`	Checks if the given value is empty.	`yii\validators\Validator`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`on()`	Attaches an event handler to an event.	`yii\base\Component`
`trigger()`	Triggers an event.	`yii\base\Component`
`validate()`	Validates a given value.	`yii\validators\Validator`
`validateAttribute()`	Validates a single attribute.	`yii\validators\Validator`
`validateAttributes()`	Validates the specified object.	`yii\validators\Validator`
`formatMessage()` protected	Formats a mesage using the I18N, or simple strtr if `\Yii::$app` is not available.	`yii\validators\Validator`
`validateValue()` protected	Validates a value.	`CaptchaValidator`

Property details

$caseSensitive

public bool $caseSensitive = false

Whether the comparison is case sensitive.

Defaults to false.

$clientScript

public array|yii\validators\client\ClientValidatorScriptInterface|null $clientScript = null

Client script strategy used to register CAPTCHA client-side validation.

When null, client-side validation is disabled and server-side validation still runs. Assign an instance of a class implementing ClientValidatorScriptInterface (typically provided by yiisoft/yii2-jquery via DI) to enable client-side validation.

Method details

clientValidateAttribute()

public function clientValidateAttribute(mixed $model, mixed $attribute, mixed $view): string|null

Returns the JavaScript needed for performing client-side validation.

Calls getClientOptions() to generate options array for client-side validation.

You may override this method to return the JavaScript validation code if the validator can support client-side validation.

The following JavaScript variables are predefined and can be used in the validation code:

attribute: an object describing the the attribute being validated.
value: the value being validated.
messages: an array used to hold the validation error messages for the attribute.
deferred: an array used to hold deferred objects for asynchronous validation
$form: a jQuery object containing the form element

The attribute object contains the following properties:

id: a unique ID identifying the attribute (e.g. “loginform-username”) in the form
name: attribute name or expression (e.g. “[0]content” for tabular input)
container: the jQuery selector of the container of the input field
input: the jQuery selector of the input field under the context of the form
error: the jQuery selector of the error tag under the context of the container
status: status of the input field, 0: empty, not entered before, 1: validated, 2: pending validation, 3: validating

Parameters

Parameter	Type	Description
`$model`	`mixed`	The data model being validated
`$attribute`	`mixed`	The name of the attribute to be validated.
`$view`	`mixed`	The view object that is going to be used to render views or view files containing a model form with this validator applied.

Returns

string|null: The client-side validation script. Null if the validator does not support client-side validation.

createCaptchaAction()

public function createCaptchaAction(): yii\captcha\CaptchaAction

Creates the CAPTCHA action object from the route specified by $captchaAction.

Returns

CaptchaAction: The action object

Throws

yii\base\InvalidConfigException

getClientOptions()

public function getClientOptions(mixed $model, mixed $attribute): array

Returns the client-side validation options.

This method is usually called from clientValidateAttribute(). You may override this method to modify options that will be passed to the client-side validation.

Parameters

Parameter	Type	Description
`$model`	`mixed`	The model being validated
`$attribute`	`mixed`	The attribute name being validated

Returns

array: The client-side validation options

Since

2.0.11

init()

public function init(): mixed

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

Returns

mixed

validateValue()

protected function validateValue(mixed $value): array|null

Validates a value.

A validator class can implement this method to support data validation out of the context of a data model.

Parameters

Parameter	Type	Description
`$value`	`mixed`	The data value to be validated.

Returns

array|null: The error message and the array of parameters to be inserted into the error message. if (!$valid) { return [$this->message, [ ‘param1’ => $this->param1, ‘formattedLimit’ => Yii::$app->formatter->asShortSize($this->getSizeLimit()), ‘mimeTypes’ => implode(’, ’, $this->mimeTypes), ‘param4’ => ‘etc…’, ]]; } return null; for this example message template can contain {param1}, {formattedLimit}, {mimeTypes}, {param4} Null should be returned if the data is valid.

Throws

yii\base\NotSupportedException: if the validator does not supporting data validation without a model