Skip to content
This repository was archived by the owner on Mar 13, 2025. It is now read-only.

Commit 26d37c1

Browse files
andrepimpaoandrepimpao
authored
Merge pull request #62 from programmatordev/1.x
1.x
2 parents 63cf347 + 3abee54 commit 26d37c1

22 files changed

+570
-64
lines changed

‎README.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,6 @@
66

77
PHP validator with expressive error messages.
88

9-
> [!NOTE]
10-
> This library is not in version 1.x mainly because there are few available rules.
11-
> Hopefully, that will change in the near future.
12-
13-
> [!IMPORTANT]
14-
> Expect some breaking changes until version `1.0`.
15-
169
## Requirements
1710

1811
- PHP 8.1 or higher.

‎docs/03-rules.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
- [Date Rules](#date-rules)
77
- [Choice Rules](#choice-rules)
88
- [Iterable Rules](#iterable-rules)
9+
- [Other Rules](#other-rules)
910

1011
## Basic Rules
1112

@@ -41,5 +42,10 @@
4142

4243
## Iterable Rules
4344

45+
- [Collection](03-rules_collection.md)
4446
- [EachValue](03-rules_each-value.md)
45-
- [EachKey](03-rules_each-key.md)
47+
- [EachKey](03-rules_each-key.md)
48+
49+
## Other Rules
50+
51+
- [Optional](03-rules_optional.md)

‎docs/03-rules_choice.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,23 +18,23 @@ Choice(
1818
## Basic Usage
1919

2020
```php
21-
// Single choice
21+
// single choice
2222
Validator::choice(['red', 'green', 'blue'])->validate('green'); // true
2323
Validator::choice(['red', 'green', 'blue'])->validate('yellow'); // false
2424

25-
// Multiple choices
25+
// multiple choices
2626
Validator::choice(['red', 'green', 'blue'], multiple: true)->validate(['red', 'blue']); // true;
2727
Validator::choice(['red', 'green', 'blue'], multiple: true)->validate(['red', 'yellow']); // false;
2828

29-
// Multiple with minimum number of choices
29+
// multiple with minimum number of choices
3030
Validator::choice(['red', 'green', 'blue'], multiple: true, min: 2)->validate(['red', 'blue']); // true
3131
Validator::choice(['red', 'green', 'blue'], multiple: true, min: 2)->validate(['red']); // false
3232

33-
// Multiple with maximum number of choices
33+
// multiple with maximum number of choices
3434
Validator::choice(['red', 'green', 'blue'], multiple: true, max: 2)->validate(['red', 'blue']); // true
3535
Validator::choice(['red', 'green', 'blue'], multiple: true, max: 2)->validate(['red', 'green', 'blue']); // false
3636

37-
// Multiple with minimum and maximum number of choices
37+
// multiple with minimum and maximum number of choices
3838
Validator::choice(['red', 'green', 'blue'], multiple: true, min: 2, max: 3)->validate(['red', 'blue']); // true
3939
Validator::choice(['red', 'green', 'blue'], multiple: true, min: 2, max: 3)->validate(['red']); // false
4040
```

‎docs/03-rules_collection.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Collection
2+
3+
Validates each key of an `array`, or object implementing `\Traversable`, with a set of validation constraints.
4+
5+
```php
6+
/** @var array<mixed, Validator> $fields */
7+
Collection(
8+
array $fields,
9+
bool $allowExtraFields = false,
10+
?string $message = null,
11+
?string $extraFieldsMessage = null,
12+
?string $missingFieldsMessage = null
13+
);
14+
```
15+
16+
## Basic Usage
17+
18+
```php
19+
Validator::collection(fields: [
20+
'name' => Validator::notBlank(),
21+
'age' => Validator::type('int')->greaterThanOrEqual(18)
22+
])->validate([
23+
'name' => 'Name',
24+
'age' => 25
25+
]); // true
26+
27+
Validator::collection(fields: [
28+
'name' => Validator::notBlank(),
29+
'age' => Validator::type('int')->greaterThanOrEqual(18)
30+
])->validate([
31+
'name' => '',
32+
'age' => 25
33+
]); // false ("name" is blank)
34+
35+
///////////////////////////////
36+
37+
// by default, extra fields are not allowed
38+
Validator::collection(fields: [
39+
'name' => Validator::notBlank(),
40+
'age' => Validator::type('int')->greaterThanOrEqual(18)
41+
])->validate([
42+
'name' => 'Name',
43+
'age' => 25,
44+
'email' => 'mail@example.com'
45+
]); // false ("email" field is not allowed)
46+
47+
// to allow extra fields, set option to true
48+
Validator::collection(
49+
fields: [
50+
'name' => Validator::notBlank(),
51+
'age' => Validator::type('int')->greaterThanOrEqual(18)
52+
],
53+
allowExtraFields: true
54+
)->validate([
55+
'name' => 'Name',
56+
'age' => 25,
57+
'email' => 'mail@example.com'
58+
]); // true
59+
60+
///////////////////////////////
61+
62+
// by default, missing fields are not allowed
63+
Validator::collection(fields: [
64+
'name' => Validator::notBlank(),
65+
'age' => Validator::type('int')->greaterThanOrEqual(18)
66+
])->validate([
67+
'age' => 25
68+
]); // false ("name" is missing)
69+
70+
// but it is possible to use the Optional validation for optional fields
71+
Validator::collection(fields: [
72+
'name' => Validator::optional(
73+
Validator::notBlank()
74+
),
75+
'age' => Validator::type('int')->greaterThanOrEqual(18)
76+
])->validate([
77+
'age' => 25
78+
]); // true ("name" is optional)
79+
```
80+
81+
> [!NOTE]
82+
> An `UnexpectedValueException` will be thrown when a value in the `fields` associative array is not an instance of `Validator`.
83+
84+
> [!NOTE]
85+
> An `UnexpectedValueException` will be thrown when the input value is not an `array` or an object implementing `\Traversable`.
86+
87+
## Options
88+
89+
### `fields`
90+
91+
type: `array<mixed, Validator>` `required`
92+
93+
Associative array with a set of validation constraints for each key.
94+
95+
### `allowExtraFields`
96+
97+
type: `bool` default: `false`
98+
99+
By default, it is not allowed to have fields (array keys) that are not defined in the `fields` option.
100+
If set to `true`, it will be allowed (but not validated).
101+
102+
### `message`
103+
104+
type: `?string` default: `{{ message }}`
105+
106+
Message that will be shown when one of the fields is invalid.
107+
108+
The following parameters are available:
109+
110+
| Parameter | Description |
111+
|-----------------|---------------------------------------|
112+
| `{{ name }}` | Name of the invalid value |
113+
| `{{ field }}` | Name of the invalid field (array key) |
114+
| `{{ message }}` | The rule message of the invalid field |
115+
116+
### `extraFieldsMessage`
117+
118+
type: `?string` default: `The {{ field }} field is not allowed.`
119+
120+
Message that will be shown when the input value has a field that is not defined in the `fields` option
121+
and `allowExtraFields` is set to `false`.
122+
123+
The following parameters are available:
124+
125+
| Parameter | Description |
126+
|-----------------|---------------------------------------|
127+
| `{{ name }}` | Name of the invalid value |
128+
| `{{ field }}` | Name of the invalid field (array key) |
129+
130+
### `missingFieldsMessage`
131+
132+
type: `?string` default: `The {{ field }} field is missing.`
133+
134+
Message that will be shown when the input value *does not* have a field that is defined in the `fields` option.
135+
136+
The following parameters are available:
137+
138+
| Parameter | Description |
139+
|-----------------|---------------------------------------|
140+
| `{{ name }}` | Name of the invalid value |
141+
| `{{ field }}` | Name of the invalid field (array key) |
142+
143+
## Changelog
144+
145+
- `1.0.0` Created

‎docs/03-rules_country.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,11 @@ Country(
1212
## Basic Usage
1313

1414
```php
15-
// Default alpha-2 code
16-
Validator::country()->validate('PT'); // true
17-
Validator::country(code: 'alpha-2')->validate('PT'); // true
15+
// default alpha-2 code
16+
Validator::country()->validate('pt'); // true
1817

19-
// Alpha-3 code
20-
Validator::country(code: 'alpha-3')->validate('PRT'); // true
18+
// alpha-3 code
19+
Validator::country(code: 'alpha-3')->validate('prt'); // true
2120
```
2221

2322
> [!NOTE]

‎docs/03-rules_each-key.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ EachKey(
1313

1414
```php
1515
Validator::eachKey(
16-
Validator::notBlank()->type('string')
16+
Validator::type('string')->notBlank()
1717
)->validate(['red' => '#f00', 'green' => '#0f0']); // true
1818

1919
Validator::eachKey(
20-
Validator::notBlank()->type('string')
20+
Validator::type('string')->notBlank()
2121
)->validate(['red' => '#f00', 1 => '#0f0']); // false
2222
```
2323

‎docs/03-rules_each-value.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ EachValue(
1313

1414
```php
1515
Validator::eachValue(
16-
Validator::notBlank()->greaterThan(1)->lessThan(10)
16+
Validator::type('int')->range(1, 10)
1717
)->validate([4, 5, 6]); // true
1818

1919
Validator::eachValue(
20-
Validator::notBlank()->greaterThan(1)->lessThan(10)
20+
Validator::type('int')->range(1, 10)
2121
)->validate([4, 5, 20]); // false
2222
```
2323

‎docs/03-rules_email.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Email(
1313
## Basic Usage
1414

1515
```php
16-
// html5 mode (default)
16+
// default html5 mode
1717
Validator::email()->validate('test@example.com'); // true
1818
Validator::email()->validate('test@example'); // false
1919

‎docs/03-rules_optional.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Optional
2+
3+
Validates only if value is *not* `null`.
4+
5+
```php
6+
Optional(
7+
Validator $validator,
8+
);
9+
```
10+
11+
## Basic Usage
12+
13+
```php
14+
Validator::optional(
15+
Validator::type('int')->greaterThanEqualTo(18)
16+
)->validate(null); // true
17+
18+
Validator::optional(
19+
Validator::type('int')->greaterThanEqualTo(18)
20+
)->validate(20); // true
21+
22+
Validator::optional(
23+
Validator::type('int')->greaterThanEqualTo(18)
24+
)->validate(16); // false
25+
```
26+
27+
## Options
28+
29+
### `validator`
30+
31+
type: `Validator` `required`
32+
33+
Validator that will validate the input value only when it is *not* `null`.
34+
35+
## Changelog
36+
37+
- `1.0.0` Created

‎docs/03-rules_timezone.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,16 @@ Timezone(
1313
## Basic Usage
1414

1515
```php
16-
// All timezone identifiers
16+
// all timezone identifiers
1717
Validator::timezone()->validate('Europe/Lisbon'); // true
1818

19-
// Restrict timezone identifiers to a specific geographical zone
19+
// restrict timezone identifiers to a specific geographical zone
2020
Validator::timezone(timezoneGroup: \DateTimeZone::EUROPE)->validate('Europe/Lisbon'); // true
2121
Validator::timezone(timezoneGroup: \DateTimeZone::AFRICA)->validate('Europe/Lisbon'); // false
22-
// Or multiple geographical zones
22+
// or multiple geographical zones
2323
Validator::timezone(timezoneGroup: \DateTimeZone::AFRICA | \DateTimeZone::EUROPE)->validate('Europe/Lisbon'); // true
2424

25-
// Restrict timezone identifiers to a specific country
25+
// restrict timezone identifiers to a specific country
2626
Validator::timezone(timezoneGroup: \DateTimeZone::PER_COUNTRY, countryCode: 'pt')->validate('Europe/Lisbon'); // true
2727
Validator::timezone(timezoneGroup: \DateTimeZone::PER_COUNTRY, countryCode: 'en')->validate('Europe/Lisbon'); // false
2828
```

0 commit comments

Comments
 (0)