Respect\Validation 3.0

Respect\Validation 3.0 is a major release with breaking changes, improved performance, and new features for more flexible validation. This version requires PHP 8.5+ (up from 8.1+ in 2.x). Update via:

composer require respect/validation:^3.0

For detailed migration instructions, see the Migration Guide.

Breaking Changes

• Class and Namespace Renames:
  • Validator renamed to ValidatorBuilder
  • Rules namespace to Validators
  • Rule interface to Validator
  • Factory to ValidatorFactory
  • InvalidRuleConstructorException to InvalidValidatorException.
• Validation Methods:
  • validate() now returns a ResultQuery object instead of a boolean (use isValid() for boolean checks)
  • check() and assert() now throw a unified ValidationException (validator-specific exceptions removed; NestedValidationException removed).
• Removed Validators:
  • Type (use specific type validators like stringType())
  • Yes/No (use trueVal()/falseVal())
  • KeyNested (use nested key())
  • Age/MinAge/MaxAge (use dateTimeDiff())
  • PrimeNumber/Fibonacci/PerfectSquare/FilterVar/Uploaded (use satisfies())
  • VideoUrl (no direct replacement).
• Behavior Changes:
  • Attribute replaced by Property/PropertyOptional/PropertyExists
  • Key split into Key/KeyOptional/KeyExists
  • Length and Size signatures changed to use composition (e.g., length(v::between(5, 10)))
  • Each stricter (rejects non-iterables like stdClass)
  • Composite validators (AllOf, etc.) require at least two validators
  • After (ex-Call) no longer handles callback errors
  • Contains/ContainsAny/In/EndsWith/StartsWith now strict by default
  • Url validates domains/IPs, drops news scheme, adds Email for mailto
  • New dependencies for some validators (sokil/php-isocodes, ramsey/uuid).
• Renamed Validators:
  • Call to After
  • Callback to Satisfies
  • Min to GreaterThanOrEqual
  • Max to LessThanOrEqual
  • Nullable to NullOr
  • Optional to UndefOr
  • KeyValue to Factory
  • NotBlank inverted to Blank (use not(v::blank()))
  • NotEmpty inverted/renamed to Falsy (use not(v::falsy()))
  • NoWhitespace inverted/renamed to Spaced (use not(v::spaced()))
  • IterableType to IterableVal (stricter IterableType now exists separately).
• Custom Messages:
  • setTemplate() and setName() removed (use templated() and named())
  • {{name}} placeholder renamed to {{subject}}.
• Factory/Container: Factory replaced by PSR-11 container via ContainerRegistry.
• Custom Validators: No longer need separate exception classes
  • use #[Template] attributes on validator classes.

New Features

• Result-Based Validation: validate() returns a ResultQuery for detailed error inspection.

  $result = v::numericVal()->positive()->between(1, 255)->validate($input);
  $result->hasFailed(); // bool
  $result->getFullMessage(); // All errors as tree

• Attribute Validation: Validate object properties via PHP attributes.

  class User {
      #[Validators\Email] public string $email;
      #[Validators\Between(18, 120)] public int $age;
  }
  v::attributes()->assert($user); // Validates all annotated properties

• ShortCircuit Validation: Stops at first failure for dependent checks.

  v::shortCircuit(
      v::key('countryCode', v::countryCode()),
      v::factory(fn($input) => v::key('subdivisionCode', v::subdivisionCode($input['countryCode'])))
  )->assert(['countryCode' => 'US', 'subdivisionCode' => 'CA']); // Passes

• Dynamic Factory Validators: Create validators based on input.

  v::factory(fn($input) => v::key('confirmation', v::equals($input['password'] ?? null)))
      ->assert(['password' => 'secret', 'confirmation' => 'secret']); // Passes

• Prefixed Shortcuts: Convenient wrappers for common patterns.

  v::nullOrEmail()->assert(null); // Passes
  v::allPositive()->assert([1, 2, 3]); // Passes
  v::notBlank()->assert('hello'); // Passes

• Result Composition: Nested results for clearer messages (e.g., all(v::intType()) → "Every item must be an integer").

• Paths in Errors: Full dot-notation paths for nested failures (e.g., .mysql.host must be a string).

• Helpful Stack Traces: Traces point to user code, not library internals.

• Custom Exceptions: Pass exceptions to assert().

  v::email()->assert($input, new DomainException('Invalid email'));

• Placeholder Pipes: Customize template rendering (e.g., {{haystack|list:or}} → "active" or "pending").

• Symfony Translation: Uses Symfony contracts for message translation.

• New Validators: All, BetweenExclusive, ContainsCount, DateTimeDiff, Formatted, Hetu, KeyExists, KeyOptional, Named, PropertyExists, PropertyOptional, Templated.

For more details, see the Feature Guide, Validators List, or open an issue on GitHub.