Final Class Yiisoft\Validator\Rule\Nested
Used to define rules for validation of nested structures:
- For one-to-one relation, using
Nestedrule is enough. - One-to-many and many-to-many relations require pairing with Yiisoft\Validator\Rule\Each rule.
An example with blog post:
$rule = new Nested([
'title' => [new Length(max: 255)],
// One-to-one relation
'author' => new Nested([
'name' => [new Length(min: 1)],
]),
// One-to-many relation
'files' => new Each([
new Nested([
'url' => [new Url()],
]),
]),
]);
There is an alternative way to write this using dot notation and shortcuts:
$rule = new Nested([
'title' => [new Length(max: 255)],
'author.name' => [new Length(min: 1)],
'files.*.url' => [new Url()],
]);
Also it's possible to use plain keys and omit arrays for single rules:
$rules = [ new Nested([ 'author' => [ 'name' => new Length(min: 1), ], ]), ];
For more examples please refer to the guide.
It's also possible to use DTO objects with PHP attributes, see Yiisoft\Validator\DataSet\ObjectDataSet documentation and guide for details.
Supports propagation of options (see Yiisoft\Validator\Helper\PropagateOptionsHelper::propagate() for available options and requirements).
See also Yiisoft\Validator\Rule\NestedHandler Corresponding handler performing the actual validation.
Psalm Types
Public Methods
| Method | Description | Defined By |
|---|---|---|
| __construct() | Yiisoft\Validator\Rule\Nested | |
| afterInitAttribute() | Yiisoft\Validator\Rule\Nested | |
| getHandler() | Yiisoft\Validator\Rule\Nested | |
| getIncorrectDataSetTypeMessage() | Gets error message used when validation fails because the validated value is an object providing wrong type of data (neither array nor an object). | Yiisoft\Validator\Rule\Nested |
| getIncorrectInputMessage() | Gets error message used when validation fails because the validated value is neither an array nor an object. | Yiisoft\Validator\Rule\Nested |
| getName() | Yiisoft\Validator\Rule\Nested | |
| getNoPropertyPathMessage() | Gets error message used when validation fails because $requirePropertyPath option was enabled and the validated array contains missing data item. | Yiisoft\Validator\Rule\Nested |
| getNoRulesWithNoObjectMessage() | Gets error message used when validation fails because the validated value is not an object and the rules were not explicitly specified via $rules. | Yiisoft\Validator\Rule\Nested |
| getOptions() | Yiisoft\Validator\Rule\Nested | |
| getRules() | Gets a set of rules for running the validation. | Yiisoft\Validator\Rule\Nested |
| getSkipOnEmpty() | A getter for $skipOnEmpty property. |
Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait |
| getValidatedObjectPropertyVisibility() | Gets visibility levels to use for parsed properties when validated value is an object providing rules / data. | Yiisoft\Validator\Rule\Nested |
| getWhen() | A getter for $when property. |
Yiisoft\Validator\Rule\Trait\WhenTrait |
| isPropertyPathRequired() | Whether to require a single data item to be passed in data according to declared nesting level structure (all keys in the sequence must be the present). Disabled by default. | Yiisoft\Validator\Rule\Nested |
| propagateOptions() | Yiisoft\Validator\Rule\Nested | |
| shouldSkipOnError() | A getter for $skipOnError property. |
Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait |
| skipOnEmpty() | An immutable setter to change $skipOnEmpty property. |
Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait |
| skipOnError() | An immutable setter to change $skipOnError property. |
Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait |
| when() | An immutable setter to change $when property. |
Yiisoft\Validator\Rule\Trait\WhenTrait |
Constants
| Constant | Value | Description | Defined By |
|---|---|---|---|
| EACH_SHORTCUT | '*' | A character acting as a shortcut when using alternative (short) syntax with Yiisoft\Validator\Rule\Nested and Yiisoft\Validator\Rule\Each combinations. | Yiisoft\Validator\Rule\Nested |
| SEPARATOR | '.' | A character acting as a separator when using alternative (short) syntax. | Yiisoft\Validator\Rule\Nested |
Method Details
| public __construct( iterable|object|string|null $rules = null, integer $validatedObjectPropertyVisibility = ReflectionProperty::IS_PRIVATE | ReflectionProperty::IS_PROTECTED | ReflectionProperty::IS_PUBLIC, integer $rulesSourceClassPropertyVisibility = ReflectionProperty::IS_PRIVATE | ReflectionProperty::IS_PROTECTED | ReflectionProperty::IS_PUBLIC, string $noRulesWithNoObjectMessage = 'Nested rule without rules requires {property} to be an object. ' . '{type} given.', string $incorrectDataSetTypeMessage = 'An object data set data for {property} can only have an array ' . 'type. {type} given.', string $incorrectInputMessage = '{Property} must be an array or an object. {type} given.', boolean $requirePropertyPath = false, string $noPropertyPathMessage = 'Property "{path}" is not found in {property}.', boolean $handleEachShortcut = true, boolean $propagateOptions = false, boolean|callable|null $skipOnEmpty = null, boolean $skipOnError = false, Closure|null $when = null ): mixed | ||
| $rules | iterable|object|string|null |
Rules for validating nested structure. The following types are supported:
|
| $validatedObjectPropertyVisibility | integer |
Visibility levels to use for parsed properties when validated value is an object providing rules / data. For example: public and protected only, this means that the rest (private ones) will be skipped. Defaults to all visibility levels (public, protected and private). See Yiisoft\Validator\DataSet\ObjectDataSet for details on providing rules / data in validated object and \Yiisoft\Validator\Rule\ObjectParser for overview how parsing works. |
| $rulesSourceClassPropertyVisibility | integer |
Visibility levels to use for parsed properties when $rules source is a name of the class providing rules. For example: public and protected only, this means that the rest (private ones) will be skipped. Defaults to all visibility levels (public, protected and private). See Yiisoft\Validator\DataSet\ObjectDataSet for details on providing rules via class and \Yiisoft\Validator\Rule\ObjectParser for overview how parsing works. |
| $noRulesWithNoObjectMessage | string |
Error message used when validation fails because the validated value is not an object and the rules were not explicitly specified via $rules: You may use the following placeholders in the message:
|
| $incorrectDataSetTypeMessage | string |
Error message used when validation fails because the validated value is an object providing wrong type of data (neither array nor an object). You may use the following placeholders in the message:
|
| $incorrectInputMessage | string |
Error message used when validation fails because the validated value is neither an array nor an object. You may use the following placeholders in the message:
|
| $requirePropertyPath | boolean |
Whether to require a single data item to be passed in data according to declared nesting level structure (all keys in the sequence must be the present). Used only when validated value is an array. Enabled by default. See $noPropertyPathMessage for customization of error message. |
| $noPropertyPathMessage | string |
Error message used when validation fails because $requirePropertyPath option was enabled and the validated array contains missing data item. You may use the following placeholders in the message:
|
| $handleEachShortcut | boolean |
Whether to handle \Yiisoft\Validator\Rule\EACH_SHORTCUT. Enabled by default meaning shortcuts are supported. Can be disabled if they are not used to prevent additional checks and improve performance. |
| $propagateOptions | boolean |
Whether the propagation of options is enabled (see Yiisoft\Validator\Helper\PropagateOptionsHelper::propagate() for supported options and requirements). Disabled by default. |
| $skipOnEmpty | boolean|callable|null |
Whether to skip this |
| $skipOnError | boolean |
Whether to skip this |
| $when | Closure|null |
A callable to define a condition for applying this |
public function __construct(
iterable|object|string|null $rules = null,
private int $validatedObjectPropertyVisibility = ReflectionProperty::IS_PRIVATE
| ReflectionProperty::IS_PROTECTED
| ReflectionProperty::IS_PUBLIC,
private int $rulesSourceClassPropertyVisibility = ReflectionProperty::IS_PRIVATE
| ReflectionProperty::IS_PROTECTED
| ReflectionProperty::IS_PUBLIC,
private string $noRulesWithNoObjectMessage = 'Nested rule without rules requires {property} to be an object. '
. '{type} given.',
private string $incorrectDataSetTypeMessage = 'An object data set data for {property} can only have an array '
. 'type. {type} given.',
private string $incorrectInputMessage = '{Property} must be an array or an object. {type} given.',
private bool $requirePropertyPath = false,
private string $noPropertyPathMessage = 'Property "{path}" is not found in {property}.',
private bool $handleEachShortcut = true,
private bool $propagateOptions = false,
bool|callable|null $skipOnEmpty = null,
private bool $skipOnError = false,
private ?Closure $when = null,
) {
$this->skipOnEmpty = $skipOnEmpty;
$this->prepareRules($rules);
}
| public afterInitAttribute( object $object ): void | ||
| $object | object | |
public function afterInitAttribute(object $object): void
{
if ($this->rules === null) {
return;
}
foreach ($this->rules as $rules) {
if (is_array($rules)) {
foreach ($rules as $rule) {
if ($rule instanceof AfterInitAttributeEventInterface) {
$rule->afterInitAttribute($object);
}
}
} else {
if ($rules instanceof AfterInitAttributeEventInterface) {
$rules->afterInitAttribute($object);
}
}
}
}
Gets error message used when validation fails because the validated value is an object providing wrong type of data (neither array nor an object).
| public getIncorrectDataSetTypeMessage( ): string | ||
| return | string |
Error message / template. |
|---|---|---|
public function getIncorrectDataSetTypeMessage(): string
{
return $this->incorrectDataSetTypeMessage;
}
Gets error message used when validation fails because the validated value is neither an array nor an object.
| public getIncorrectInputMessage( ): string | ||
| return | string |
Error message / template. |
|---|---|---|
public function getIncorrectInputMessage(): string
{
return $this->incorrectInputMessage;
}
Gets error message used when validation fails because $requirePropertyPath option was enabled and the validated array contains missing data item.
| public getNoPropertyPathMessage( ): string | ||
| return | string |
Error message / template. |
|---|---|---|
public function getNoPropertyPathMessage(): string
{
return $this->noPropertyPathMessage;
}
Gets error message used when validation fails because the validated value is not an object and the rules were not explicitly specified via $rules.
| public getNoRulesWithNoObjectMessage( ): string | ||
| return | string |
Error message / template. |
|---|---|---|
public function getNoRulesWithNoObjectMessage(): string
{
return $this->noRulesWithNoObjectMessage;
}
| public getOptions( ): array |
#[ArrayShape([
'requirePropertyPath' => 'bool',
'noRulesWithNoObjectMessage' => 'array',
'incorrectDataSetTypeMessage' => 'array',
'incorrectInputMessage' => 'array',
'noPropertyPathMessage' => 'array',
'skipOnEmpty' => 'bool',
'skipOnError' => 'bool',
'rules' => 'array|null',
])]
public function getOptions(): array
{
return [
'noRulesWithNoObjectMessage' => [
'template' => $this->noRulesWithNoObjectMessage,
'parameters' => [],
],
'incorrectDataSetTypeMessage' => [
'template' => $this->incorrectDataSetTypeMessage,
'parameters' => [],
],
'incorrectInputMessage' => [
'template' => $this->incorrectInputMessage,
'parameters' => [],
],
'noPropertyPathMessage' => [
'template' => $this->getNoPropertyPathMessage(),
'parameters' => [],
],
'requirePropertyPath' => $this->isPropertyPathRequired(),
'skipOnEmpty' => $this->getSkipOnEmptyOption(),
'skipOnError' => $this->skipOnError,
'rules' => $this->rules === null ? null : RulesDumper::asArray($this->rules),
];
}
Gets a set of rules for running the validation.
| public getRules( ): array|null | ||
| return | array|null |
A set of rules. |
|---|---|---|
public function getRules(): ?array
{
return $this->rules;
}
Defined in: Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait::getSkipOnEmpty()
A getter for $skipOnEmpty property.
| public getSkipOnEmpty( ): boolean|callable|null | ||
| return | boolean|callable|null |
A current raw (non-normalized) value. |
|---|---|---|
public function getSkipOnEmpty(): bool|callable|null
{
return $this->skipOnEmpty;
}
Gets visibility levels to use for parsed properties when validated value is an object providing rules / data.
Defaults to all visibility levels (public, protected and private)
| public getValidatedObjectPropertyVisibility( ): integer | ||
| return | integer |
A number representing visibility levels. |
|---|---|---|
public function getValidatedObjectPropertyVisibility(): int
{
return $this->validatedObjectPropertyVisibility;
}
Defined in: Yiisoft\Validator\Rule\Trait\WhenTrait::getWhen()
A getter for $when property.
| public getWhen( ): Closure|null | ||
| return | Closure|null |
Current value:
|
|---|---|---|
public function getWhen(): ?Closure
{
return $this->when;
}
Whether to require a single data item to be passed in data according to declared nesting level structure (all keys in the sequence must be the present). Disabled by default.
| public isPropertyPathRequired( ): boolean | ||
| return | boolean |
|
|---|---|---|
public function isPropertyPathRequired(): bool
{
return $this->requirePropertyPath;
}
| public propagateOptions( ): void |
public function propagateOptions(): void
{
if ($this->rules === null) {
return;
}
$rules = [];
foreach ($this->rules as $attributeRulesIndex => $attributeRules) {
$rules[$attributeRulesIndex] = is_iterable($attributeRules)
? PropagateOptionsHelper::propagate($this, $attributeRules)
: PropagateOptionsHelper::propagateToRule($this, $attributeRules);
}
$this->rules = $rules;
}
Defined in: Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait::shouldSkipOnError()
A getter for $skipOnError property.
| public shouldSkipOnError( ): boolean | ||
| return | boolean |
Current value. |
|---|---|---|
public function shouldSkipOnError(): bool
{
return $this->skipOnError;
}
Defined in: Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait::skipOnEmpty()
An immutable setter to change $skipOnEmpty property.
| public skipOnEmpty( boolean|callable|null $value ): $this | ||
| $value | boolean|callable|null |
A new value. |
| return | $this |
The new instance with a changed value. |
|---|---|---|
public function skipOnEmpty(bool|callable|null $value): static
{
$new = clone $this;
$new->skipOnEmpty = $value;
return $new;
}
Defined in: Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait::skipOnError()
An immutable setter to change $skipOnError property.
| public skipOnError( boolean $value ): $this | ||
| $value | boolean |
A new value. |
| return | $this |
The new instance with a changed value. |
|---|---|---|
public function skipOnError(bool $value): static
{
$new = clone $this;
$new->skipOnError = $value;
return $new;
}
Defined in: Yiisoft\Validator\Rule\Trait\WhenTrait::when()
An immutable setter to change $when property.
| public when( Closure|null $value ): $this | ||
| $value | Closure|null |
A new value:
|
| return | $this |
The new instance with a changed value. |
|---|---|---|
public function when(?Closure $value): static
{
$new = clone $this;
$new->when = $value;
return $new;
}
Signup or Login in order to comment.