# StringValidator

> StringValidator validates that the attribute value is of certain length.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [validators](/docs/api/yii/validators/index.md) › StringValidator

| class | `yii\validators\StringValidator` |
| --- | --- |
| Extends | [`Validator`](/docs/api/yii/validators/validator/index.md) » [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/validators/StringValidator.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/validators/StringValidator.php#L22) |

StringValidator validates that the attribute value is of certain length.

Note, this validator should only be used with string-typed attributes.

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-attributeNames"></span>[`$attributeNames`](/docs/api/yii/validators/validator/index.md#property-attributeNames) read-only | `array` | Attribute names. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-attributes"></span>[`$attributes`](/docs/api/yii/validators/validator/index.md#property-attributes) | `array\|string` | Attributes to be validated by this validator. Default: `[]`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="property-builtInValidators"></span>[`$builtInValidators`](/docs/api/yii/validators/validator/index.md#property-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']`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-clientScript"></span>`$clientScript` | `array\|`[`yii\validators\client\ClientValidatorScriptInterface`](/docs/api/yii/validators/client/clientvalidatorscriptinterface/index.md)`\|null` | Client script class to use for client-side validation. Default: `null`. | `StringValidator` |
| <span id="property-enableClientValidation"></span>[`$enableClientValidation`](/docs/api/yii/validators/validator/index.md#property-enableClientValidation) | `bool` | Whether to enable client-side validation for this validator. Default: `true`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| [`$encoding`](#property-encoding) | `string\|null` | The encoding of the string value to be validated (e.g. 'UTF-8'). Default: `null`. | `StringValidator` |
| <span id="property-except"></span>[`$except`](/docs/api/yii/validators/validator/index.md#property-except) | `array\|string` | Scenarios that the validator should not be applied to. Default: `[]`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-isEmpty"></span>[`$isEmpty`](/docs/api/yii/validators/validator/index.md#property-isEmpty) | `callable\|null` | A PHP callable that replaces the default implementation of [`isEmpty()`](/docs/api/yii/validators/validator/index.md#method-isEmpty). Default: `null`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| [`$length`](#property-length) | `int\|array\|null` | Specifies the length limit of the value to be validated. Default: `null`. | `StringValidator` |
| [`$max`](#property-max) | `int\|null` | Maximum length. Default: `null`. | `StringValidator` |
| <span id="property-message"></span>`$message` | `string` | User-defined error message used when the value is not a string. Default: `null`. | `StringValidator` |
| [`$min`](#property-min) | `int\|null` | Minimum length. Default: `null`. | `StringValidator` |
| <span id="property-notEqual"></span>`$notEqual` | `string` | User-defined error message used when the length of the value is not equal to [`$length`](/docs/api/yii/validators/stringvalidator/index.md#property-length). Default: `null`. | `StringValidator` |
| <span id="property-on"></span>[`$on`](/docs/api/yii/validators/validator/index.md#property-on) | `array\|string` | Scenarios that the validator can be applied to. Default: `[]`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-skipOnEmpty"></span>[`$skipOnEmpty`](/docs/api/yii/validators/validator/index.md#property-skipOnEmpty) | `bool` | Whether this validation rule should be skipped if the attribute value is null or an empty string. Default: `true`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-skipOnError"></span>[`$skipOnError`](/docs/api/yii/validators/validator/index.md#property-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`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| [`$strict`](#property-strict) | `bool` | Whether to require the value to be a string data type. Default: `true`. Available since 2.0.33. | `StringValidator` |
| <span id="property-tooLong"></span>`$tooLong` | `string` | User-defined error message used when the length of the value is greater than [`$max`](/docs/api/yii/validators/stringvalidator/index.md#property-max). Default: `null`. | `StringValidator` |
| <span id="property-tooShort"></span>`$tooShort` | `string` | User-defined error message used when the length of the value is smaller than [`$min`](/docs/api/yii/validators/stringvalidator/index.md#property-min). Default: `null`. | `StringValidator` |
| <span id="property-validationAttributes"></span>[`$validationAttributes`](/docs/api/yii/validators/validator/index.md#property-validationAttributes) read-only | `array\|null` | List of attribute names. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-when"></span>[`$when`](/docs/api/yii/validators/validator/index.md#property-when) | `callable\|null` | A PHP callable whose return value determines whether this validator should be applied. Default: `null`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |
| <span id="property-whenClient"></span>[`$whenClient`](/docs/api/yii/validators/validator/index.md#property-whenClient) | `string\|null` | A JavaScript function name whose return value determines whether this validator should be applied on the client-side. Default: `null`. | [`Validator`](/docs/api/yii/validators/validator/index.md) |

## Methods

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

## Property details

### $encoding <span id="property-encoding"></span>

```php
public string|null $encoding = null
```

The encoding of the string value to be validated (e.g. 'UTF-8').

If this property is not set, [`Application::$charset`](/docs/api/yii/base/application/index.md#property-charset) will be used.

### $length <span id="property-length"></span>

```php
public int|array|null $length = null
```

Specifies the length limit of the value to be validated.

This can be specified in one of the following forms:

- an integer: the exact length that the value should be of;
- an array of one element: the minimum length that the value should be of. For example, `[8]`.
  This will overwrite [`$min`](/docs/api/yii/validators/stringvalidator/index.md#property-min).
- an array of two elements: the minimum and maximum lengths that the value should be of.
  For example, `[8, 128]`. This will overwrite both [`$min`](/docs/api/yii/validators/stringvalidator/index.md#property-min) and [`$max`](/docs/api/yii/validators/stringvalidator/index.md#property-max).

### $max <span id="property-max"></span>

```php
public int|null $max = null
```

Maximum length.

If not set, it means no maximum length limit.

### $min <span id="property-min"></span>

```php
public int|null $min = null
```

Minimum length.

If not set, it means no minimum length limit.

### $strict <span id="property-strict"></span>

```php
public bool $strict = true
```

Whether to require the value to be a string data type.

If false any scalar value will be treated as it's string equivalent.

**Since**

2.0.33

## Method details

### clientValidateAttribute() <span id="method-clientValidateAttribute"></span>

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

Returns the JavaScript needed for performing client-side validation.

Calls [`getClientOptions()`](/docs/api/yii/validators/stringvalidator/index.md#method-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.

### getClientOptions() <span id="method-getClientOptions"></span>

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

Returns the client-side validation options.

This method is usually called from [`clientValidateAttribute()`](/docs/api/yii/validators/stringvalidator/index.md#method-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() <span id="method-init"></span>

```php
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`

### validateAttribute() <span id="method-validateAttribute"></span>

```php
public function validateAttribute(mixed $model, mixed $attribute): mixed
```

Validates a single attribute.

Child classes must implement this method to provide the actual validation logic.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$model` | `mixed` | The data model to be validated |
| `$attribute` | `mixed` | The name of the attribute to be validated. |

**Returns**

`mixed`

### validateValue() <span id="method-validateValue"></span>

```php
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`](/docs/api/yii/base/notsupportedexception/index.md): if the validator does not supporting data validation without a model