Prepare library for the next major version

Version 3.0 will include a few crucial deprecations. This commit adds
some soft deprecations to warn users about these changes.

Some of the biggest changes are:

* The method `validate()` will be renamed to `isValid()`.

* The method `validate()` will be repurposed to return an object with
  failures.

* It won't be possible to handle rules directly; users will need to use
  the `Validator` class to validate with any rule.

There will some more changes, but those are some of the most important
ones, and are the ones that are easy to deprecate right now.

.github/workflows/continuous-integration.yml

@@ -22,6 +22,7 @@ jobs:
           - "8.1"
           - "8.2"
           - "8.3"
+          - "8.4"
 
     steps:
       - name: Checkout

README.md

@@ -8,7 +8,7 @@
 
 The most awesome validation engine ever created for PHP.
 
-- Complex rules made simple: `v::numericVal()->positive()->between(1, 255)->validate($input)`.
+- Complex rules made simple: `v::numericVal()->positive()->between(1, 255)->isValid($input)`.
 - [Granularity control](docs/02-feature-guide.md#validation-methods) for advanced reporting.
 - [More than 150](docs/08-list-of-rules-by-category.md) (fully tested) validation rules.
 - [A concrete API](docs/05-concrete-api.md) for non fluent usage.

composer.json

@@ -18,7 +18,7 @@
         }
     },
     "require": {
-        "php": "^8.1 || ^8.2",
+        "php": ">=8.1",
         "respect/stringifier": "^0.2.0",
         "symfony/polyfill-mbstring": "^1.2"
     },

docs/02-feature-guide.md

@@ -15,7 +15,7 @@ The Hello World validator is something like this:
 
 ```php
 $number = 123;
-v::numericVal()->validate($number); // true
+v::numericVal()->isValid($number); // true
 ```
 
 ## Chained validation
@@ -25,7 +25,7 @@ containing numbers and letters, no whitespace and length between 1 and 15.
 
 ```php
 $usernameValidator = v::alnum()->noWhitespace()->length(1, 15);
-$usernameValidator->validate('alganet'); // true
+$usernameValidator->isValid('alganet'); // true
 ```
 
 ## Validating object attributes
@@ -44,7 +44,7 @@ Is possible to validate its attributes in a single chain:
 $userValidator = v::attribute('name', v::stringType()->length(1, 32))
                   ->attribute('birthdate', v::date()->minAge(18));
 
-$userValidator->validate($user); // true
+$userValidator->isValid($user); // true
 ```
 
 Validating array keys is also possible using `v::key()`
@@ -78,7 +78,7 @@ v::key(
         ->key('field2', v::stringType())
         ->key('field3', v::boolType())
     )
-    ->assert($data); // You can also use check() or validate()
+    ->assert($data); // You can also use check() or isValid()
 ```
 
 ## Input optional
@@ -93,11 +93,11 @@ For that reason all rules are mandatory now but if you want to treat a value as
 optional you can use `v::optional()` rule:
 
 ```php
-v::alpha()->validate(''); // false input required
-v::alpha()->validate(null); // false input required
+v::alpha()->isValid(''); // false input required
+v::alpha()->isValid(null); // false input required
 
-v::optional(v::alpha())->validate(''); // true
-v::optional(v::alpha())->validate(null); // true
+v::optional(v::alpha())->isValid(''); // true
+v::optional(v::alpha())->isValid(null); // true
 ```
 
 By _optional_ we consider `null` or an empty string (`''`).
@@ -109,17 +109,17 @@ See more on [Optional](rules/Optional.md).
 You can use the `v::not()` to negate any rule:
 
 ```php
-v::not(v::intVal())->validate(10); // false, input must not be integer
+v::not(v::intVal())->isValid(10); // false, input must not be integer
 ```
 
 ## Validator reuse
 
 Once created, you can reuse your validator anywhere. Remember `$usernameValidator`?
 
 ```php
-$usernameValidator->validate('respect');            //true
-$usernameValidator->validate('alexandre gaigalas'); // false
-$usernameValidator->validate('#$%');                //false
+$usernameValidator->isValid('respect');            //true
+$usernameValidator->isValid('alexandre gaigalas'); // false
+$usernameValidator->isValid('#$%');                //false
 ```
 
 ## Exception types
@@ -144,7 +144,7 @@ $usernameValidator->validate('#$%');                //false
 ## Informative exceptions
 
 When something goes wrong, Validation can tell you exactly what's going on. For this,
-we use the `assert()` method instead of `validate()`:
+we use the `assert()` method instead of `isValid()`:
 
 ```php
 use Respect\Validation\Exceptions\NestedValidationException;
@@ -239,7 +239,7 @@ v::dateTime('Y-m-d')->between('1980-02-02', 'now')->setName('Member Since');
 
 ## Validation methods
 
-We've seen `validate()` that returns true or false and `assert()` that throws a complete
+We've seen `isValid()` that returns true or false and `assert()` that throws a complete
 validation report. There is also a `check()` method that returns an Exception
 only with the first error found:
 

docs/05-concrete-api.md

@@ -8,7 +8,7 @@ or magic methods. We'll use a traditional dependency injection approach.
 use Respect\Validation\Validator as v;
 
 $usernameValidator = v::alnum()->noWhitespace()->length(1, 15);
-$usernameValidator->validate('alganet'); // true
+$usernameValidator->isValid('alganet'); // true
 ```
 
 If you `var_dump($usernameValidator)`, you'll see a composite of objects with
@@ -18,28 +18,31 @@ the chain only builds the structure. You can build it by yourself:
 
 ```php
 use Respect\Validation\Rules;
+use Respect\Validation\Validator;
 
-$usernameValidator = new Rules\AllOf(
+$usernameValidator = Validator::create(
     new Rules\Alnum(),
     new Rules\NoWhitespace(),
     new Rules\Length(1, 15)
 );
-$usernameValidator->validate('alganet'); // true
+$usernameValidator->isValid('alganet'); // true
 ```
 
 This is still a very lean API. You can use it in any dependency injection
 container or test it in the way you want. Nesting is still possible:
 
 ```php
 use Respect\Validation\Rules;
+use Respect\Validation\Validator;
 
-$usernameValidator = new Rules\AllOf(
+$usernameValidator = Validator::create(
     new Rules\Alnum(),
     new Rules\NoWhitespace(),
     new Rules\Length(1, 15)
 );
-$userValidator = new Rules\Key('name', $usernameValidator);
-$userValidator->validate(['name' => 'alganet']); // true
+
+$userValidator = Validator::create(new Rules\Key('name', $usernameValidator));
+$userValidator->isValid(['name' => 'alganet']); // true
 ```
 
 ## How It Works?
@@ -63,7 +66,7 @@ something complex and returns for you.
 
 > I really don't like static calls, can I avoid it?
 
-Yes. Just use `$validator = new Validator();` each time you want a new validator,
+Yes. Just use `$validator = Validator::create();` each time you want a new validator,
 and continue from there.
 
 > Do you have a static method for each rule?

docs/07-comparable-values.md

@@ -16,15 +16,15 @@ that can be parsed by PHP
 Below you can see some examples:
 
 ```php
-v::min(100)->validate($collection); // true if it has at least 100 items
+v::min(100)->isValid($collection); // true if it has at least 100 items
 
 v::dateTime()
     ->between(new DateTime('yesterday'), new DateTime('tomorrow'))
-    ->validate(new DateTime('now')); // true
+    ->isValid(new DateTime('now')); // true
 
-v::numericVal()->max(10)->validate(5); // true
+v::numericVal()->max(10)->isValid(5); // true
 
-v::stringVal()->between('a', 'f')->validate('d'); // true
+v::stringVal()->between('a', 'f')->isValid('d'); // true
 
-v::dateTime()->between('yesterday', 'tomorrow')->validate('now'); // true
+v::dateTime()->between('yesterday', 'tomorrow')->isValid('now'); // true
 ```

docs/index.md

@@ -2,7 +2,7 @@
 
 The most awesome validation engine ever created for PHP.
 
-- Complex rules made simple: `v::numericVal()->positive()->between(1, 255)->validate($input)`.
+- Complex rules made simple: `v::numericVal()->positive()->between(1, 255)->isValid($input)`.
 - [Granularity control](02-feature-guide.md#validation-methods) for advanced reporting.
 - [More than 150](08-list-of-rules-by-category.md) (fully tested) validation rules.
 - [A concrete API](05-concrete-api.md) for non fluent usage.

docs/rules/AllOf.md

@@ -5,7 +5,7 @@
 Will validate if all inner validators validates.
 
 ```php
-v::allOf(v::intVal(), v::positive())->validate(15); // true
+v::allOf(v::intVal(), v::positive())->isValid(15); // true
 ```
 
 ## Categorization

docs/rules/Alnum.md

@@ -9,18 +9,18 @@ Alphanumeric is a combination of alphabetic (a-z and A-Z) and numeric (0-9)
 characters.
 
 ```php
-v::alnum()->validate('foo 123'); // false
-v::alnum(' ')->validate('foo 123'); // true
-v::alnum()->validate('100%'); // false
-v::alnum('%')->validate('100%'); // true
-v::alnum('%', ',')->validate('10,5%'); // true
+v::alnum()->isValid('foo 123'); // false
+v::alnum(' ')->isValid('foo 123'); // true
+v::alnum()->isValid('100%'); // false
+v::alnum('%')->isValid('100%'); // true
+v::alnum('%', ',')->isValid('10,5%'); // true
 ```
 
 You can restrict case using the [Lowercase](Lowercase.md) and
 [Uppercase](Uppercase.md) rules.
 
 ```php
-v::alnum()->uppercase()->validate('example'); // false
+v::alnum()->uppercase()->isValid('example'); // false
 ```
 
 Message template for this validator includes `{{additionalChars}}` as the string

docs/rules/Alpha.md

@@ -7,18 +7,18 @@ Validates whether the input contains only alphabetic characters. This is similar
 to [Alnum](Alnum.md), but it does not allow numbers.
 
 ```php
-v::alpha()->validate('some name'); // false
-v::alpha(' ')->validate('some name'); // true
-v::alpha()->validate('Cedric-Fabian'); // false
-v::alpha('-')->validate('Cedric-Fabian'); // true
-v::alpha('-', '\'')->validate('\'s-Gravenhage'); // true
+v::alpha()->isValid('some name'); // false
+v::alpha(' ')->isValid('some name'); // true
+v::alpha()->isValid('Cedric-Fabian'); // false
+v::alpha('-')->isValid('Cedric-Fabian'); // true
+v::alpha('-', '\'')->isValid('\'s-Gravenhage'); // true
 ```
 
 You can restrict case using the [Lowercase](Lowercase.md) and
 [Uppercase](Uppercase.md) rules.
 
 ```php
-v::alpha()->uppercase()->validate('example'); // false
+v::alpha()->uppercase()->isValid('example'); // false
 ```
 
 ## Categorization

docs/rules/AlwaysInvalid.md

@@ -5,7 +5,7 @@
 Validates any input as invalid.
 
 ```php
-v::alwaysInvalid()->validate('whatever'); // false
+v::alwaysInvalid()->isValid('whatever'); // false
 ```
 
 ## Categorization

docs/rules/AlwaysValid.md

@@ -5,7 +5,7 @@
 Validates any input as valid.
 
 ```php
-v::alwaysValid()->validate('whatever'); // true
+v::alwaysValid()->isValid('whatever'); // true
 ```
 
 ## Categorization

docs/rules/AnyOf.md

@@ -5,7 +5,7 @@
 This is a group validator that acts as an OR operator.
 
 ```php
-v::anyOf(v::intVal(), v::floatVal())->validate(15.5); // true
+v::anyOf(v::intVal(), v::floatVal())->isValid(15.5); // true
 ```
 
 In the sample above, `IntVal()` doesn't validates, but `FloatVal()` validates,

docs/rules/ArrayType.md

@@ -5,9 +5,9 @@
 Validates whether the type of an input is array.
 
 ```php
-v::arrayType()->validate([]); // true
-v::arrayType()->validate([1, 2, 3]); // true
-v::arrayType()->validate(new ArrayObject()); // false
+v::arrayType()->isValid([]); // true
+v::arrayType()->isValid([1, 2, 3]); // true
+v::arrayType()->isValid(new ArrayObject()); // false
 ```
 
 ## Categorization

docs/rules/ArrayVal.md

@@ -6,9 +6,9 @@ Validates if the input is an array or if the input can be used as an array
 (instance of `ArrayAccess` or `SimpleXMLElement`).
 
 ```php
-v::arrayVal()->validate([]); // true
-v::arrayVal()->validate(new ArrayObject); // true
-v::arrayVal()->validate(new SimpleXMLElement('<xml></xml>')); // true
+v::arrayVal()->isValid([]); // true
+v::arrayVal()->isValid(new ArrayObject); // true
+v::arrayVal()->isValid(new SimpleXMLElement('<xml></xml>')); // true
 ```
 
 ## Categorization

docs/rules/Attribute.md

@@ -10,19 +10,19 @@ Validates an object attribute, even private ones.
 $obj = new stdClass;
 $obj->foo = 'bar';
 
-v::attribute('foo')->validate($obj); // true
+v::attribute('foo')->isValid($obj); // true
 ```
 
 You can also validate the attribute itself:
 
 ```php
-v::attribute('foo', v::equals('bar'))->validate($obj); // true
+v::attribute('foo', v::equals('bar'))->isValid($obj); // true
 ```
 
 Third parameter makes the attribute presence optional:
 
 ```php
-v::attribute('lorem', v::stringType(), false)->validate($obj); // true
+v::attribute('lorem', v::stringType(), false)->isValid($obj); // true
 ```
 
 The name of this validator is automatically set to the attribute name.

docs/rules/Base.md

@@ -5,11 +5,11 @@
 Validate numbers in any base, even with non regular bases.
 
 ```php
-v::base(2)->validate('011010001'); // true
-v::base(3)->validate('0120122001'); // true
-v::base(8)->validate('01234567520'); // true
-v::base(16)->validate('012a34f5675c20d'); // true
-v::base(2)->validate('0120122001'); // false
+v::base(2)->isValid('011010001'); // true
+v::base(3)->isValid('0120122001'); // true
+v::base(8)->isValid('01234567520'); // true
+v::base(16)->isValid('012a34f5675c20d'); // true
+v::base(2)->isValid('0120122001'); // false
 ```
 
 ## Categorization

docs/rules/Base64.md

@@ -5,8 +5,8 @@
 Validate if a string is Base64-encoded.
 
 ```php
-v::base64()->validate('cmVzcGVjdCE='); // true
-v::base64()->validate('respect!'); // false
+v::base64()->isValid('cmVzcGVjdCE='); // true
+v::base64()->isValid('respect!'); // false
 ```
 
 ## Categorization

docs/rules/Between.md

@@ -5,9 +5,9 @@
 Validates whether the input is between two other values.
 
 ```php
-v::intVal()->between(10, 20)->validate(10); // true
-v::intVal()->between(10, 20)->validate(15); // true
-v::intVal()->between(10, 20)->validate(20); // true
+v::intVal()->between(10, 20)->isValid(10); // true
+v::intVal()->between(10, 20)->isValid(15); // true
+v::intVal()->between(10, 20)->isValid(20); // true
 ```
 
 Validation makes comparison easier, check out our supported

docs/rules/BoolType.md

@@ -5,8 +5,8 @@
 Validates whether the type of the input is [boolean](http://php.net/types.boolean).
 
 ```php
-v::boolType()->validate(true); // true
-v::boolType()->validate(false); // true
+v::boolType()->isValid(true); // true
+v::boolType()->isValid(false); // true
 ```
 
 ## Categorization