UPGRADE.md

Upgrading Instructions for Yii Validator

!!!IMPORTANT!!!

The following upgrading instructions are cumulative. That is, if you want to upgrade from version A to version C and there is version B between A and C, you need to follow the instructions for both A and B.

Upgrade from 1.x

• Renamed classes/interfaces/traits:

  • Yiisoft\Validator\AttributeTranslator\ArrayAttributeTranslator to Yiisoft\Validator\PropertyTranslator\ArrayPropertyTranslator,
  • Yiisoft\Validator\AttributeTranslator\NullAttributeTranslator to Yiisoft\Validator\PropertyTranslator\NullPropertyTranslator,
  • Yiisoft\Validator\AttributeTranslator\TranslatorAttributeTranslator to Yiisoft\Validator\PropertyTranslator\TranslatorPropertyTranslator,
  • Yiisoft\Validator\AttributeTranslatorInterface to Yiisoft\Validator\PropertyTranslatorInterface,
  • Yiisoft\Validator\Rule\AtLeast to Yiisoft\Validator\Rule\FilledAtLeast,
  • Yiisoft\Validator\Rule\OneOf to Yiisoft\Validator\Rule\FilledOnlyOneOf.

• Changed interface Yiisoft\Validator\AttributeTranslatorProviderInterface:

  • renamed to Yiisoft\Validator\PropertyTranslatorProviderInterface,
  • method getAttributeTranslator() renamed to getPropertyTranslator().

• Renamed methods in DataSetInterface:

  • getAttributeValue() to getPropertyValue(),
  • hasAttribute() to hasProperty().

• Renamed methods in ObjectParser:

  • getAttributeValue() to getPropertyValue(),
  • hasAttribute() to hasProperty(),
  • getAttributeTranslator() to getPropertyTranslator().

• Renamed methods in Result:

  • isAttributeValid() to isPropertyValid(),
  • getErrorMessagesIndexedByAttribute() to getErrorMessagesIndexedByProperty(),
  • getFirstErrorMessagesIndexedByAttribute() to getFirstErrorMessagesIndexedByProperty(),
  • getAttributeErrors() to getPropertyErrors(),
  • getAttributeErrorMessages() to getPropertyErrorMessages(),
  • getAttributeErrorMessagesIndexedByPath() to getPropertyErrorMessagesIndexedByPath().

• Renamed methods in Yiisoft\Validator\ValidationContext:

  • setAttributeTranslator() to setPropertyTranslator(),
  • getAttribute() to getProperty(),
  • setAttribute() to setProperty(),
  • isAttributeMissing() to isPropertyMissing().

• Renamed rule message placeholders and the corresponding properties/methods of rules:

  • {attribute} to {property},
  • {targetAttribute} to {targetProperty},
  • {targetAttributeValue} to {targetPropertyValue},
  • {targetValueOrAttribute} to {targetValueOrProperty},
  • {attributes} to {properties}.

• The signature for Yiisoft\Validator\RuleHandlerInterface::validate() changed. If you have classes that implement RuleHandlerInterface, change the type of $rule parameter in method validate() from object to RuleInterface. For example:

  use Yiisoft\Validator\ValidationContext;
  
  public function validate(mixed $value, object $rule, ValidationContext $context): Result;

  Change to:

  use Yiisoft\Validator\RuleInterface;
  use Yiisoft\Validator\ValidationContext;
  
  public function validate(mixed $value, RuleInterface $rule, ValidationContext $context): Result;

• The type of $escape argument in Yiisoft\Validator\Error::getValuePath() changed from bool|string|null to string|null. If you used bool, replace false with null and true with dot (.).

• For custom rules using Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait, apply the following changes for $skipOnEmpty property in the constructor:

  • Turn in it into argument (remove private visibility).
  • Change type from mixed to more specific bool|callable|null
  • Add manual initialization of property value.

  For example:

  public function __construct(
      // ...
      private mixed $skipOnEmpty = null,
      // ...
  ) {
      // ...
  }

  Change to:

  public function __construct(
      // ...
      bool|callable|null $skipOnEmpty = null,
      // ...
  ) {
      $this->skipOnEmpty = $skipOnEmpty;
  }