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.

* It won't be possible to catch specific exceptions; users will need to
  catch `ValidationException`.

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

CONTRIBUTING.md

@@ -62,61 +62,22 @@ declare(strict_types=1);
 
 namespace Respect\Validation\Rules;
 
+use Respect\Validation\Rules\Core\Simple;
+
 /**
  * Explain in one sentence what this rule does.
  *
  * @author Your Name <youremail@yourdomain.tld>
  */
-final class HelloWorld extends AbstractRule
+final class HelloWorld extends Simple
 {
-    /**
-     * {@inheritDoc}
-     */
-    public function validate($input): bool
+    public function isValid(mixed $input): bool
     {
         return $input === 'Hello World';
     }
 }
 ```
 
-### Creating the rule exception
-
-Just that and we're done with the rule code. The Exception requires you to
-declare messages used by `assert()` and `check()`. Messages are declared in
-affirmative and negative moods, so if anyone calls `v::not(v::helloWorld())` the
-library will show the appropriate message.
-
-```php
-<?php
-
-/*
- * Copyright (c) Alexandre Gomes Gaigalas <alganet@gmail.com>
- * SPDX-License-Identifier: MIT
- */
-
-declare(strict_types=1);
-
-namespace Respect\Validation\Exceptions;
-
-/**
- * @author Your Name <youremail@yourdomain.tld>
- */
-final class HelloWorldException extends ValidationException
-{
-    /**
-     * {@inheritDoc}
-     */
-    protected $defaultTemplates = [
-        self::MODE_DEFAULT => [
-            self::STANDARD => '{{name}} must be a Hello World',
-        ],
-        self::MODE_NEGATIVE => [
-            self::STANDARD => '{{name}} must not be a Hello World',
-        ]
-    ];
-}
-```
-
 ### Creating unit tests
 
 Finally, we need to test if everything is running smooth. We have `RuleTestCase`

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()`
@@ -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

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/06-custom-rules.md

@@ -10,11 +10,11 @@ validate method will be executed. Here's how the class should look:
 ```php
 namespace My\Validation\Rules;
 
-use Respect\Validation\Rules\AbstractRule;
+use Respect\Validation\Rules\Core\Simple;
 
-final class Something extends AbstractRule
+final class Something extends Simple
 {
-    public function validate($input): bool
+    public function isValid(mixed $input): bool
     {
         // Do something here with the $input and return a boolean value
     }

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.