Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prepare library for the next major version #1518

Closed
wants to merge 4 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
1 change: 1 addition & 0 deletions .github/workflows/continuous-integration.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ jobs:
- "8.1"
- "8.2"
- "8.3"
- "8.4"

steps:
- name: Checkout
Expand Down
53 changes: 7 additions & 46 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ create a validator that validates if a string is equal to "Hello World".

The rule itself needs to implement the `Validatable` interface but, it is
convenient to just extend the `AbstractRule` class.
Doing that, you'll only need to declare one method: `validate($input)`.
Doing that, you'll only need to declare one method: `isValid(mixed $input): bool`.
This method must return `true` or `false`.

If your validator class is `HelloWorld`, it will be available as `v::helloWorld()`
Expand All @@ -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 <[email protected]>
*/
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 <[email protected]>
* SPDX-License-Identifier: MIT
*/

declare(strict_types=1);

namespace Respect\Validation\Exceptions;

/**
* @author Your Name <[email protected]>
*/
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`
Expand All @@ -128,8 +89,8 @@ are able to use any methods of it. By extending `RuleTestCase` you should
implement two methods that should return a [data provider][] with the rule as
first item of the arrays:

- `providerForValidInput`: Will test when `validate()` should return `true`
- `providerForInvalidInput`: Will test when `validate()` should return `false`
- `providerForValidInput`: Will test when `isValid()` should return `true`
- `providerForInvalidInput`: Will test when `isValid()` should return `false`

```php
<?php
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions codecov.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
coverage:
status:
project:
default:
target: 94% # the required coverage value
threshold: 1% # the leniency in hitting the target
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
}
},
"require": {
"php": "^8.1 || ^8.2",
"php": ">=8.1",
"respect/stringifier": "^0.2.0",
"symfony/polyfill-mbstring": "^1.2"
},
Expand Down
28 changes: 14 additions & 14 deletions docs/02-feature-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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()`
Expand Down Expand Up @@ -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
Expand All @@ -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 (`''`).
Expand All @@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -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:

Expand Down
17 changes: 10 additions & 7 deletions docs/05-concrete-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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?
Expand All @@ -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?
Expand Down
6 changes: 3 additions & 3 deletions docs/06-custom-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down
10 changes: 5 additions & 5 deletions docs/07-comparable-values.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion docs/rules/AllOf.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions docs/rules/Alnum.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions docs/rules/Alpha.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/rules/AlwaysInvalid.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Validates any input as invalid.

```php
v::alwaysInvalid()->validate('whatever'); // false
v::alwaysInvalid()->isValid('whatever'); // false
```

## Categorization
Expand Down
2 changes: 1 addition & 1 deletion docs/rules/AlwaysValid.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Validates any input as valid.

```php
v::alwaysValid()->validate('whatever'); // true
v::alwaysValid()->isValid('whatever'); // true
```

## Categorization
Expand Down
2 changes: 1 addition & 1 deletion docs/rules/AnyOf.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading
Loading