Final Class Yiisoft\Validator\Rule\Compare
Defines validation options to compare the specified value with "target" value provided directly ({@see GreaterThanOrEqual::$targetValue}) or within a property ({@see GreaterThanOrEqual::$targetProperty}).
The default comparison is based on number values (including float values). It's also possible to compare values as strings byte by byte and compare original values as is. See {@see \Yiisoft\Validator\Rule\GreaterThanOrEqual::$type} for all possible options.
It supports different comparison operators, specified via the {@see \Yiisoft\Validator\Rule\Compare::$operator}.
There are shortcut classes to use instead of specifying operator manually:
- {@see \Yiisoft\Validator\Rule\Equal} is a shortcut for
new Compare(operator: '==')andnew Compare(operator: '==='). - {@see \Yiisoft\Validator\Rule\NotEqual} is a shortcut for
new Compare(operator: '!=')andnew Compare(operator: '!=='). - {@see \Yiisoft\Validator\Rule\GreaterThan} is a shortcut for
new Compare(operator: '>'). - {@see \Yiisoft\Validator\Rule\GreaterThanOrEqual} is a shortcut for
new Compare(operator: '>='). - {@see \Yiisoft\Validator\Rule\LessThan} is a shortcut for
new Compare(operator: '<'). - {@see \Yiisoft\Validator\Rule\LessThanOrEqual} is a shortcut for
new Compare(operator: '<=').
See also Yiisoft\Validator\Rule\CompareHandler.
Public Methods
Constants
| Constant | Value | Description | Defined By |
|---|---|---|---|
| DEFAULT_INCORRECT_DATA_SET_TYPE_MESSAGE | '{Property} returned from a custom data set must have ' . 'one of the following types: integer, float, string, boolean, null or an object implementing \Stringable ' . 'interface or \DateTimeInterface.' | A default for {@see $incorrectDataSetTypeMessage}. | Yiisoft\Validator\Rule\AbstractCompare |
| DEFAULT_INCORRECT_INPUT_MESSAGE | 'The allowed types for {property} are integer, float, string, ' . 'boolean, null and object implementing \Stringable interface or \DateTimeInterface. {type} given.' | A default for {@see $incorrectInputMessage}. | Yiisoft\Validator\Rule\AbstractCompare |
| VALID_OPERATORS_MAP | [ '==' => 1, '===' => 1, '!=' => 1, '!==' => 1, '>' => 1, '>=' => 1, '<' => 1, '<=' => 1, ] | Map of valid operators. It's used instead of a list for better performance. | Yiisoft\Validator\Rule\AbstractCompare |
| VALID_TYPES | [ \Yiisoft\Validator\Rule\CompareType::ORIGINAL, \Yiisoft\Validator\Rule\CompareType::STRING, \Yiisoft\Validator\Rule\CompareType::NUMBER, ] | List of valid types. | Yiisoft\Validator\Rule\AbstractCompare |
Method Details
| public mixed __construct ( mixed $targetValue = null, string|null $targetProperty = null, string $incorrectInputMessage = self::DEFAULT_INCORRECT_INPUT_MESSAGE, string $incorrectDataSetTypeMessage = self::DEFAULT_INCORRECT_DATA_SET_TYPE_MESSAGE, string|null $message = null, string $type = CompareType::NUMBER, string $operator = '==', boolean|callable|null $skipOnEmpty = null, boolean $skipOnError = false, Closure|null $when = null ) | ||
| $targetValue | mixed |
The value to be compared with. When both this property and {@see $targetProperty} are set, this property takes precedence. |
| $targetProperty | string|null |
The name of the property to be compared with. When both this property and {@see $targetValue} are set, the {@see $targetValue} takes precedence. |
| $incorrectInputMessage | string |
A message used when the input is incorrect. You may use the following placeholders in the message:
|
| $incorrectDataSetTypeMessage | string |
A message used when the value returned from a custom data set is neither scalar nor null. You may use the following placeholders in the message:
|
| $message | string|null |
A message used when the value is not valid. You may use the following placeholders in the message:
When {@see \Yiisoft\Validator\Rule\CompareType::ORIGINAL} is used with complex types (neither scalar nor |
| $type | string |
The type of the values being compared:
{@see \Yiisoft\Validator\Rule\CompareType::NUMBER} and {@see \Yiisoft\Validator\Rule\CompareType::STRING} allow only scalar and {@see \Yiisoft\Validator\Rule\CompareType::ORIGINAL} allows any values. All PHP comparison rules apply here, see comparison operators - {@see https://www.php.net/manual/en/language.operators.comparison.php} and PHP type comparison tables - {@see https://www.php.net/manual/en/types.comparisons.php} sections in official PHP documentation. |
| $operator | string |
The operator for comparison. The following operators are supported:
|
| $skipOnEmpty | boolean|callable|null |
Whether to skip this rule if the value validated is empty. See {@see \Yiisoft\Validator\SkipOnEmptyInterface}. |
| $skipOnError | boolean |
Whether to skip this rule if any of the previous rules gave an error. See {@see \Yiisoft\Validator\SkipOnErrorInterface}. |
| $when | Closure|null |
A callable to define a condition for applying the rule. See {@see \Yiisoft\Validator\WhenInterface}. |
public function __construct(
private mixed $targetValue = null,
private ?string $targetProperty = null,
private string $incorrectInputMessage = self::DEFAULT_INCORRECT_INPUT_MESSAGE,
private string $incorrectDataSetTypeMessage = self::DEFAULT_INCORRECT_DATA_SET_TYPE_MESSAGE,
private ?string $message = null,
private string $type = CompareType::NUMBER,
private string $operator = '==',
bool|callable|null $skipOnEmpty = null,
private bool $skipOnError = false,
private ?Closure $when = null,
) {
if (!in_array($this->type, self::VALID_TYPES)) {
$validTypesString = $this->getQuotedList(self::VALID_TYPES);
$message = "Type \"$this->type\" is not supported. The valid types are: $validTypesString.";
throw new InvalidArgumentException($message);
}
if (!isset(self::VALID_OPERATORS_MAP[$this->operator])) {
$validOperators = array_keys(self::VALID_OPERATORS_MAP);
$validOperatorsString = $this->getQuotedList($validOperators);
$message = "Operator \"$operator\" is not supported. The valid operators are: $validOperatorsString.";
throw new InvalidArgumentException($message);
}
$this->skipOnEmpty = $skipOnEmpty;
}
| public string getHandler ( ) |
public function getHandler(): string
{
return CompareHandler::class;
}
Defined in: Yiisoft\Validator\Rule\AbstractCompare::getIncorrectDataSetTypeMessage()
Get message used when the value returned from a custom data set s not scalar.
| public string getIncorrectDataSetTypeMessage ( ) | ||
| return | string |
Error message. |
|---|---|---|
public function getIncorrectDataSetTypeMessage(): string
{
return $this->incorrectDataSetTypeMessage;
}
Defined in: Yiisoft\Validator\Rule\AbstractCompare::getIncorrectInputMessage()
Get message used when the input is incorrect.
| public string getIncorrectInputMessage ( ) | ||
| return | string |
Error message. |
|---|---|---|
public function getIncorrectInputMessage(): string
{
return $this->incorrectInputMessage;
}
Defined in: Yiisoft\Validator\Rule\AbstractCompare::getMessage()
Get a message used when the value is not valid.
| public string getMessage ( ) | ||
| return | string |
Error message. |
|---|---|---|
public function getMessage(): string
{
return $this->message ?? match ($this->operator) {
'==', => '{Property} must be equal to "{targetValueOrProperty}".',
'===' => '{Property} must be strictly equal to "{targetValueOrProperty}".',
'!=' => '{Property} must not be equal to "{targetValueOrProperty}".',
'!==' => '{Property} must not be strictly equal to "{targetValueOrProperty}".',
'>' => '{Property} must be greater than "{targetValueOrProperty}".',
'>=' => '{Property} must be greater than or equal to "{targetValueOrProperty}".',
'<' => '{Property} must be less than "{targetValueOrProperty}".',
'<=' => '{Property} must be less than or equal to "{targetValueOrProperty}".',
};
}
Defined in: Yiisoft\Validator\Rule\AbstractCompare::getOperator()
Get the operator for comparison.
| public string getOperator ( ) | ||
| return | string |
The operator for comparison. |
|---|---|---|
public function getOperator(): string
{
return $this->operator;
}
| public array getOptions ( ) |
public function getOptions(): array
{
$isTargetValueSimple = $this->targetValue === null || is_scalar($this->targetValue);
if (!$isTargetValueSimple) {
$messageParameters = ['targetProperty' => $this->targetProperty];
} else {
$messageParameters = [
'targetValue' => $this->targetValue,
'targetProperty' => $this->targetProperty,
'targetValueOrProperty' => $this->targetProperty ?? $this->targetValue,
];
}
$options = [
'targetProperty' => $this->targetProperty,
'incorrectInputMessage' => [
'template' => $this->incorrectInputMessage,
'parameters' => $messageParameters,
],
'incorrectDataSetTypeMessage' => [
'template' => $this->incorrectDataSetTypeMessage,
'parameters' => $messageParameters,
],
'message' => [
'template' => $this->getMessage(),
'parameters' => $messageParameters,
],
'type' => $this->type,
'operator' => $this->operator,
'skipOnEmpty' => $this->getSkipOnEmptyOption(),
'skipOnError' => $this->skipOnError,
];
if (!$isTargetValueSimple) {
return $options;
}
return array_merge(['targetValue' => $this->targetValue], $options);
}
Defined in: Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait::getSkipOnEmpty()
A getter for $skipOnEmpty property.
| public boolean|callable|null getSkipOnEmpty ( ) | ||
| return | boolean|callable|null |
A current raw (non-normalized) value. |
|---|---|---|
public function getSkipOnEmpty(): bool|callable|null
{
return $this->skipOnEmpty;
}
Defined in: Yiisoft\Validator\Rule\AbstractCompare::getTargetProperty()
Get the name of the property to be compared with.
| public string|null getTargetProperty ( ) | ||
| return | string|null |
Name of the property to be compared with or |
|---|---|---|
public function getTargetProperty(): ?string
{
return $this->targetProperty;
}
Defined in: Yiisoft\Validator\Rule\AbstractCompare::getTargetValue()
Get value to be compared with.
| public mixed getTargetValue ( ) | ||
| return | mixed |
Value to be compared with or |
|---|---|---|
public function getTargetValue(): mixed
{
return $this->targetValue;
}
Defined in: Yiisoft\Validator\Rule\AbstractCompare::getType()
Get the type of the values being compared.
| public string getType ( ) | ||
| return | string |
The type of the values being compared. Either {@see \Yiisoft\Validator\Rule\CompareType::STRING} or {@see \Yiisoft\Validator\Rule\CompareType::NUMBER}. |
|---|---|---|
public function getType(): string
{
return $this->type;
}
Defined in: Yiisoft\Validator\Rule\Trait\WhenTrait::getWhen()
A getter for $when property.
| public Closure|null getWhen ( ) | ||
| return | Closure|null |
Current value:
|
|---|---|---|
public function getWhen(): ?Closure
{
return $this->when;
}
Defined in: Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait::shouldSkipOnError()
A getter for $skipOnError property.
| public boolean shouldSkipOnError ( ) | ||
| 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 $this skipOnEmpty ( boolean|callable|null $value ) | ||
| $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 $this skipOnError ( boolean $value ) | ||
| $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 $this when ( Closure|null $value ) | ||
| $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.