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

Commit e650896

Browse files
andrepimpaoandrepimpao
committed
docs: added Length rule
1 parent 09a51a4 commit e650896

File tree

3 files changed

+181
-7
lines changed

3 files changed

+181
-7
lines changed

‎docs/03-rules.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
## String Rules
1717

1818
- [Email](03-rules_email.md)
19+
- [Length](03-rules_length.md)
1920
- [URL](03-rules_url.md)
2021

2122
## Comparison Rules

‎docs/03-rules_count.md‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ Validator::count(max: 1)->validate(['a', 'b', 'c']); // false
2525

2626
// min and max value
2727
Validator::count(min: 2, max: 4)->validate(['a', 'b', 'c']); // true
28-
2928
// exact value
3029
Validator::count(min: 3, max: 3)->validate(['a', 'b', 'c']); // true
3130
```
@@ -34,10 +33,10 @@ Validator::count(min: 3, max: 3)->validate(['a', 'b', 'c']); // true
3433
> An `UnexpectedValueException` will be thrown when either `min` or `max` options are not given.
3534
3635
> [!NOTE]
37-
> An `UnexpectedValueException` will be thrown when the input value is not an `array` or an object implementing `\Countable`.
36+
> An `UnexpectedValueException` will be thrown when the `min` value is greater than the `max` value.
3837
3938
> [!NOTE]
40-
> An `UnexpectedValueException` will be thrown when the `min` value is greater than the `max` value.
39+
> An `UnexpectedValueException` will be thrown when the input value is not an `array` or an object implementing `\Countable`.
4140
4241
## Options
4342

@@ -47,16 +46,12 @@ type: `?int` default: `null`
4746

4847
It defines the minimum number of elements required.
4948

50-
For example, if `min` is 2, the input value must have at least 2 elements.
51-
5249
### `max`
5350

5451
type: `?int` default: `null`
5552

5653
It defines the maximum number of elements required.
5754

58-
For example, if `max` is 2, the input value must have at most 2 elements.
59-
6055
### `minMessage`
6156

6257
type: `?string` default: `The {{ name }} value should contain {{ min }} elements or more, {{ numElements }} elements given.`

‎docs/03-rules_length.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Length
2+
3+
Validates that a given string is between a minimum and maximum length.
4+
5+
```php
6+
Length(
7+
?int $min = null,
8+
?int $max = null,
9+
string $charset = 'UTF-8',
10+
string $countUnit = 'codepoints',
11+
?callable $normalizer = null,
12+
?string $minMessage = null,
13+
?string $maxMessage = null,
14+
?string $exactMessage = null,
15+
?string $charsetMessage = null
16+
);
17+
```
18+
19+
## Basic Usage
20+
21+
```php
22+
// min value
23+
Validator::length(min: 1)->validate('abc'); // true
24+
Validator::length(min: 5)->validate('abc'); // false
25+
26+
// max value
27+
Validator::length(max: 5)->validate('abc'); // true
28+
Validator::length(max: 1)->validate('abc'); // false
29+
30+
// min and max value
31+
Validator::length(min: 2, max: 4)->validate('abc'); // true
32+
// exact value
33+
Validator::length(min: 3, max: 3)->validate('abc'); // true
34+
35+
// charset
36+
Validator::length(min: 2, charset: 'ASCII')->validate('テスト'); // false
37+
38+
// count unit
39+
Validator::length(max: 1, countUnit: 'bytes')->validate('🔥'); // false
40+
Validator::length(max: 1, countUnit: 'graphemes')->validate('🔥'); // true
41+
```
42+
43+
> [!NOTE]
44+
> An `UnexpectedValueException` will be thrown when either `min` or `max` options are not given.
45+
46+
> [!NOTE]
47+
> An `UnexpectedValueException` will be thrown when the `min` value is greater than the `max` value.
48+
49+
> [!NOTE]
50+
> An `UnexpectedValueException` will be thrown when the `charset` value is not a valid option.
51+
> Check all the supported character encodings [here](https://www.php.net/manual/en/mbstring.supported-encodings.php).
52+
53+
> [!NOTE]
54+
> An `UnexpectedValueException` will be thrown when the `countUnit` value is not a valid option.
55+
56+
> [!NOTE]
57+
> An `UnexpectedValueException` will be thrown when the input value is not a `string` or an object implementing `\Stringable`.
58+
59+
## Options
60+
61+
### `min`
62+
63+
type: `?int` default: `null`
64+
65+
It defines the minimum number of characters required.
66+
67+
### `max`
68+
69+
type: `?int` default: `null`
70+
71+
It defines the maximum number of characters required.
72+
73+
### `charset`
74+
75+
type: `string` default: `UTF-8`
76+
77+
Charset to be used when measuring a string length.
78+
79+
Check all the supported character encodings [here](https://www.php.net/manual/en/mbstring.supported-encodings.php).
80+
81+
### `countUnit`
82+
83+
type: `string` default: `codepoints`
84+
85+
The character count unit to use when measuring a string length.
86+
87+
Available options are:
88+
89+
- `bytes` uses [`strlen`](https://www.php.net/manual/en/function.strlen) to count the length of the string in bytes.
90+
- `codepoints` uses [`mb_strlen`](https://www.php.net/manual/en/function.mb-strlen.php) to count the length of the string in Unicode code points.
91+
- `graphemes` uses [`grapheme_strlen`](https://www.php.net/manual/en/function.grapheme-strlen.php) to count the length of the string in grapheme units.
92+
93+
### `normalizer`
94+
95+
type: `callable` default: `null`
96+
97+
Allows to define a `callable` that will be applied to the value before checking if it is valid.
98+
99+
For example, use `trim`, or pass your own function, to not measure whitespaces at the end of a string:
100+
101+
```php
102+
// existing php callables
103+
Validator::length(max: 3, normalizer: 'trim')->validate('abc '); // true
104+
// function
105+
Validator::length(max: 3, normalizer: fn($value) => trim($value))->validate('abc '); // false
106+
```
107+
108+
### `minMessage`
109+
110+
type: `?string` default: `The {{ name }} value should have {{ min }} characters or more, {{ numChars }} characters given.`
111+
112+
Message that will be shown when the input value has fewer characters than the defined in `min`.
113+
114+
The following parameters are available:
115+
116+
| Parameter | Description |
117+
|-------------------|------------------------------------------|
118+
| `{{ value }}` | The current invalid value |
119+
| `{{ name }}` | Name of the invalid value |
120+
| `{{ min }}` | The minimum number of valid characters |
121+
| `{{ max }}` | The maximum number of valid characters |
122+
| `{{ numChars }}` | The current invalid number of characters |
123+
| `{{ charset }}` | Selected charset encoding |
124+
| `{{ countUnit }}` | Selected count unit |
125+
126+
### `maxMessage`
127+
128+
type: `?string` default: `The {{ name }} value should have {{ max }} characters or less, {{ numChars }} characters given.`
129+
130+
Message that will be shown when the input value has more characters than the defined in `max`.
131+
132+
The following parameters are available:
133+
134+
| Parameter | Description |
135+
|-------------------|------------------------------------------|
136+
| `{{ value }}` | The current invalid value |
137+
| `{{ name }}` | Name of the invalid value |
138+
| `{{ min }}` | The minimum number of valid characters |
139+
| `{{ max }}` | The maximum number of valid characters |
140+
| `{{ numChars }}` | The current invalid number of characters |
141+
| `{{ charset }}` | Selected charset encoding |
142+
| `{{ countUnit }}` | Selected count unit |
143+
144+
### `exactMessage`
145+
146+
type: `?string` default: `The {{ name }} value should have exactly {{ min }} characters, {{ numChars }} characters given.`
147+
148+
Message that will be shown when `min` and `max` options have the same value and the input value has a different number of characters.
149+
150+
The following parameters are available:
151+
152+
| Parameter | Description |
153+
|-------------------|------------------------------------------|
154+
| `{{ value }}` | The current invalid value |
155+
| `{{ name }}` | Name of the invalid value |
156+
| `{{ min }}` | The minimum number of valid characters |
157+
| `{{ max }}` | The maximum number of valid characters |
158+
| `{{ numChars }}` | The current invalid number of characters |
159+
| `{{ charset }}` | Selected charset encoding |
160+
| `{{ countUnit }}` | Selected count unit |
161+
162+
### `charsetMessage`
163+
164+
type: `?string` default: `The {{ name }} value does not match the expected {{ charset }} charset.`
165+
166+
Message that will be shown if the string does not match the given `charset`.
167+
168+
The following parameters are available:
169+
170+
| Parameter | Description |
171+
|-------------------|------------------------------------------|
172+
| `{{ value }}` | The current invalid value |
173+
| `{{ name }}` | Name of the invalid value |
174+
| `{{ charset }}` | Selected charset encoding |
175+
176+
## Changelog
177+
178+
- `0.7.0` Created

0 commit comments

Comments
 (0)