respect/validation 2.4.0

First release of the 2.4 series

on PHP Packagist

This release just deprecates a few things to prepare users to the next major version. Migrating to this release will probably make migrating to version 3.0 a bit less painful, but feel free to skip this version as it has no new features.

Deprecations

Here are a few important changes coming into version 3.0.

Method validate() is now called isValid()

The method validate() will be repurposed to return an object with failures, so users can iterate over them and get more detailed information about the validation that just occurred.

Consider changing your code as indicated below:

- v::stringType()->validate($input)
+ v::stringType()->isValid($input)

In most cases, a single find and replace from your IDE should fix it. You could also run a a few commands in your command line to fix that too; here's an example:

rg '\->validate\(' --files-with-matches |
    xargs -n 1 sed --in-place 's,->validate(,->isValid(,g'

WARNING: the commands above will replace any method that is called validate in your codebase. Make sure that you only call the method validate from this library.

Calling rules directly

All existing methods in the class rules rules will be removed in favor of a single method that will return an object with the validation result. That will help us with providing more granularity control, more flexibility, and more rich and customisable validation messages.

Consider changing your code as indicated below:

Calling assert():

- (new Email())->assert($input)
+ Validator::create(new Email())->assert($input)

Calling check():

- (new Email())->check($input)
+ Validator::create(new Email())->check($input)

Calling validate():

- (new Email())->validate($input)
+ Validator::create(new Email())->isValid($input)

Catching rule exceptions

All exception messages will be removed. Instead, users will need to catch ValidationException or NestedValidationException. The current exceptions can be quite complex, and although they're heavily tested, it's not a good idea to have to much logic after a code already fails.

Consider changing your code as indicated below:

-use Respect\Validation\Exceptions\EmailException;
+use Respect\Validation\Exceptions\ValidationException;
 use Respect\Validation\Validator as v;

 try {
    v::email()->assert('invalid-email');
-} catch(EmailException $exception) {
+} catch(ValidationException $exception) {
     echo $exception->getMessage() . PHP_EOL;
 }

CAVEAT: The NestedValidationException will also be removed by a simplified version of ValidationException, but there's no substitute for it at the moment.

Class AbstractRule is now called Simple

We no longer use Abstract as a prefix, and since the validate() method will be deprecated, and we no longer can call rules directly, the API of this class needs to change to something else.

Consider changing your code as indicated below.

-use Respect\Validation\Rules\AbstractRule;
+use Respect\Validation\Rules\Core\Simple;

-final class MyRule extends AbstractRule
+final class MyRule extends Simple
 {
-    public function validate($input): bool
+    public function isValid(mixed $input): bool

Class AbstractWrapper is now called Wrapper

We no longer use Abstract as a prefix.

Consider changing your code as indicated below:

-use Respect\Validation\Rules\AbstractWrapper;
+use Respect\Validation\Rules\Core\Wrapper;

-final class MyRule extends AbstractWrapper
+final class MyRule extends Wrapper

Class AbstractEnvelope is now called Envelope

We no longer use Abstract as a prefix.

Consider changing your code as indicated below:

-use Respect\Validation\Rules\AbstractEnvelope;
+use Respect\Validation\Rules\Core\Envelope;

-final class MyRule extends AbstractEnvelope
+final class MyRule extends Envelope

Class AbstractComposite is now called Composite

We no longer use Abstract as a prefix, and a Composite class needs to have at least 2 rules to be able to compare them.

Consider changing your code as indicated below:

-use Respect\Validation\Rules\AbstractComposite;
+use Respect\Validation\Rules\Core\Composite;

-final class MyRule extends AbstractComposite
+final class MyRule extends Composite

Disclosure

There will be a lot more deprecations coming in version 3.0, but not all of them can be described in an in-between version like this one. Version 3.0 should be coming in the upcoming month or months, but I can't make promises because life has been quite unpredictable in 2024; who knows what's coming in 2025?!

Full Changelog: 2.3.13...2.4.0