2015-01-30 09:40:06 +01:00
|
|
|
# Feature Guide
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Namespace import
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
Respect\Validation is namespaced, but you can make your life easier by importing
|
|
|
|
a single class into your context:
|
|
|
|
|
|
|
|
```php
|
|
|
|
use Respect\Validation\Validator as v;
|
|
|
|
```
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Simple validation
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
The Hello World validator is something like this:
|
|
|
|
|
|
|
|
```php
|
|
|
|
$number = 123;
|
2016-11-06 18:45:44 +01:00
|
|
|
v::numericVal()->validate($number); // true
|
2015-01-30 09:40:06 +01:00
|
|
|
```
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Chained validation
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
It is possible to use validators in a chain. Sample below validates a string
|
|
|
|
containing numbers and letters, no whitespace and length between 1 and 15.
|
|
|
|
|
|
|
|
```php
|
2015-10-22 04:30:30 +02:00
|
|
|
$usernameValidator = v::alnum()->noWhitespace()->length(1, 15);
|
2015-10-20 02:53:25 +02:00
|
|
|
$usernameValidator->validate('alganet'); // true
|
2015-01-30 09:40:06 +01:00
|
|
|
```
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Validating object attributes
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
Given this simple object:
|
|
|
|
|
|
|
|
```php
|
|
|
|
$user = new stdClass;
|
|
|
|
$user->name = 'Alexandre';
|
|
|
|
$user->birthdate = '1987-07-01';
|
|
|
|
```
|
|
|
|
|
|
|
|
Is possible to validate its attributes in a single chain:
|
|
|
|
|
|
|
|
```php
|
2019-02-04 03:20:24 +01:00
|
|
|
$userValidator = v::attribute('name', v::stringType()->length(1, 32))
|
2019-05-12 18:33:38 +02:00
|
|
|
->attribute('birthdate', v::date()->minAge(18));
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2015-10-20 02:53:25 +02:00
|
|
|
$userValidator->validate($user); // true
|
2015-01-30 09:40:06 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
Validating array keys is also possible using `v::key()`
|
|
|
|
|
2017-05-01 08:54:18 +02:00
|
|
|
Note that we used `v::stringType()` and `v::dateTime()` in the beginning of the validator.
|
2015-01-30 09:40:06 +01:00
|
|
|
Although is not mandatory, it is a good practice to use the type of the
|
|
|
|
validated object as the first node in the chain.
|
|
|
|
|
2018-04-11 10:31:39 +02:00
|
|
|
## Validating array keys and values
|
|
|
|
|
2018-08-23 02:09:43 +02:00
|
|
|
Validating array keys into another array is also possible using [Key](rules/Key.md).
|
2018-04-11 10:31:39 +02:00
|
|
|
|
|
|
|
If we got the array below:
|
|
|
|
|
|
|
|
```php
|
|
|
|
$data = [
|
|
|
|
'parentKey' => [
|
|
|
|
'field1' => 'value1',
|
|
|
|
'field2' => 'value2'
|
|
|
|
'field3' => true,
|
|
|
|
]
|
|
|
|
];
|
|
|
|
```
|
|
|
|
|
|
|
|
Using the next combination of rules, we can validate child keys.
|
|
|
|
|
|
|
|
```php
|
|
|
|
v::key(
|
|
|
|
'parentKey',
|
|
|
|
v::key('field1', v::stringType())
|
|
|
|
->key('field2', v::stringType())
|
|
|
|
->key('field3', v::boolType())
|
|
|
|
)
|
|
|
|
->assert($data); // You can also use check() or validate()
|
|
|
|
```
|
|
|
|
|
2015-10-07 07:41:38 +02:00
|
|
|
## Input optional
|
|
|
|
|
|
|
|
On oldest versions of Respect\Validation all validators treat input as optional
|
|
|
|
and accept an empty string input as valid. Even though a useful feature that
|
|
|
|
caused a lot of troubles for our team and neither was an obvious behavior. Also
|
|
|
|
there was some people who likes to accept `null` as optional value, not only an
|
|
|
|
empty string.
|
|
|
|
|
|
|
|
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::optional(v::alpha())->validate(''); // true
|
|
|
|
v::optional(v::alpha())->validate(null); // true
|
|
|
|
```
|
|
|
|
|
2015-10-15 16:10:47 +02:00
|
|
|
By _optional_ we consider `null` or an empty string (`''`).
|
2015-10-07 07:41:38 +02:00
|
|
|
|
2018-08-23 01:38:24 +02:00
|
|
|
See more on [Optional](rules/Optional.md).
|
2015-10-07 07:41:38 +02:00
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Negating rules
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
You can use the `v::not()` to negate any rule:
|
|
|
|
|
|
|
|
```php
|
2015-10-20 02:53:25 +02:00
|
|
|
v::not(v::intVal())->validate(10); // false, input must not be integer
|
2015-01-30 09:40:06 +01:00
|
|
|
```
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Validator reuse
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2015-02-17 17:41:56 +01:00
|
|
|
Once created, you can reuse your validator anywhere. Remember `$usernameValidator`?
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
```php
|
|
|
|
$usernameValidator->validate('respect'); //true
|
2015-10-20 02:53:25 +02:00
|
|
|
$usernameValidator->validate('alexandre gaigalas'); // false
|
2015-01-30 09:40:06 +01:00
|
|
|
$usernameValidator->validate('#$%'); //false
|
|
|
|
```
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Exception types
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2018-05-24 08:25:57 +02:00
|
|
|
- `Respect\Validation\Exceptions\Exception`:
|
2017-03-28 11:53:14 +02:00
|
|
|
- All exceptions implement this interface;
|
|
|
|
- `Respect\Validation\Exceptions\ValidationException`:
|
2018-05-24 08:25:57 +02:00
|
|
|
- Implements the `Respect\Validation\Exceptions\Exception` interface
|
2017-03-28 11:53:14 +02:00
|
|
|
- Thrown when the `check()` fails
|
|
|
|
- All validation exceptions extend this class
|
|
|
|
- Available methods:
|
2018-05-22 13:42:10 +02:00
|
|
|
- `getMessage()`;
|
2018-05-24 07:47:09 +02:00
|
|
|
- `updateMode($mode)`;
|
|
|
|
- `updateTemplate($template)`;
|
2017-03-28 11:53:14 +02:00
|
|
|
- `Respect\Validation\Exceptions\NestedValidationException`:
|
|
|
|
- Extends the `Respect\Validation\Exceptions\ValidationException` class
|
|
|
|
- Usually thrown when the `assert()` fails
|
|
|
|
- Available methods:
|
|
|
|
- `getFullMessage()`;
|
|
|
|
- `getMessages()`;
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Informative exceptions
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
When something goes wrong, Validation can tell you exactly what's going on. For this,
|
|
|
|
we use the `assert()` method instead of `validate()`:
|
|
|
|
|
|
|
|
```php
|
2015-10-23 12:33:37 +02:00
|
|
|
use Respect\Validation\Exceptions\NestedValidationException;
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
try {
|
|
|
|
$usernameValidator->assert('really messed up screen#name');
|
2015-10-23 12:33:37 +02:00
|
|
|
} catch(NestedValidationException $exception) {
|
2015-01-30 09:40:06 +01:00
|
|
|
echo $exception->getFullMessage();
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
The printed message is exactly this, as a nested Markdown list:
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2015-02-17 17:41:56 +01:00
|
|
|
```no-highlight
|
2015-10-22 04:30:30 +02:00
|
|
|
- All of the required rules must pass for "really messed up screen#name"
|
|
|
|
- "really messed up screen#name" must contain only letters (a-z) and digits (0-9)
|
|
|
|
- "really messed up screen#name" must not contain whitespace
|
|
|
|
- "really messed up screen#name" must have a length between 1 and 15
|
2015-02-17 17:41:56 +01:00
|
|
|
```
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Getting all messages as an array
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2018-03-07 19:07:52 +01:00
|
|
|
If you want to get all the messages as an array you can use `getMessages()` for
|
|
|
|
that. The `getMessages()` method returns an array with all the messages.
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
```php
|
2015-01-30 09:40:06 +01:00
|
|
|
try {
|
|
|
|
$usernameValidator->assert('really messed up screen#name');
|
2015-10-23 12:33:37 +02:00
|
|
|
} catch(NestedValidationException $exception) {
|
2015-10-22 04:30:30 +02:00
|
|
|
print_r($exception->getMessages());
|
2015-01-30 09:40:06 +01:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2018-03-07 19:07:52 +01:00
|
|
|
The `getMessages()` returns an array in which the keys are the name of the
|
2018-08-23 02:09:43 +02:00
|
|
|
validators, or its reference in case you are using [Key](rules/Key.md) or
|
|
|
|
[Attribute](rules/Attribute.md) rule:
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
```no-highlight
|
|
|
|
Array
|
|
|
|
(
|
2018-03-07 19:07:52 +01:00
|
|
|
[alnum] => "really messed up screen#name" must contain only letters (a-z) and digits (0-9)
|
|
|
|
[noWhitespace] => "really messed up screen#name" must not contain whitespace
|
|
|
|
[length] => "really messed up screen#name" must have a length between 1 and 15
|
2015-10-22 04:30:30 +02:00
|
|
|
)
|
|
|
|
```
|
2015-09-11 00:10:18 +02:00
|
|
|
|
2018-03-07 19:07:52 +01:00
|
|
|
## Custom messages
|
|
|
|
|
|
|
|
Getting messages as an array is fine, but sometimes you need to customize them
|
|
|
|
in order to present them to the user. This is possible using the `getMessages()`
|
|
|
|
method as well by passing the templates as an argument:
|
|
|
|
|
|
|
|
```php
|
|
|
|
try {
|
|
|
|
$usernameValidator->assert('really messed up screen#name');
|
|
|
|
} catch(NestedValidationException $exception) {
|
|
|
|
print_r(
|
|
|
|
$exception->getMessages([
|
|
|
|
'alnum' => '{{name}} must contain only letters and digits',
|
|
|
|
'noWhitespace' => '{{name}} cannot contain spaces',
|
|
|
|
'length' => '{{name}} must not have more than 15 chars',
|
|
|
|
])
|
|
|
|
);
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
For all messages, the `{{name}}` variable is available for templates. If you do
|
|
|
|
not define a name it uses the input to replace this placeholder.
|
|
|
|
|
|
|
|
The result of the code above will be:
|
|
|
|
|
|
|
|
```no-highlight
|
|
|
|
Array
|
|
|
|
(
|
|
|
|
[alnum] => "really messed up screen#name" must contain only letters and digits
|
|
|
|
[noWhitespace] => "really messed up screen#name" cannot contain spaces
|
|
|
|
[length] => "really messed up screen#name" must not have more than 15 chars
|
|
|
|
)
|
|
|
|
```
|
|
|
|
|
|
|
|
Note that `getMessage()` will only return a message when the specific validation
|
|
|
|
in the chain fails.
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Validator name
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
On `v::attribute()` and `v::key()`, `{{name}}` is the attribute/key name. For others,
|
|
|
|
is the same as the input. You can customize a validator name using:
|
|
|
|
|
|
|
|
```php
|
2017-05-01 08:54:18 +02:00
|
|
|
v::dateTime('Y-m-d')->between('1980-02-02', 'now')->setName('Member Since');
|
2015-01-30 09:40:06 +01:00
|
|
|
```
|
|
|
|
|
2023-02-13 05:59:06 +01:00
|
|
|
## Symfony validators
|
2015-01-30 09:40:06 +01:00
|
|
|
|
2023-02-13 05:59:06 +01:00
|
|
|
It is also possible to reuse validators from Symfony if they are installed:
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
```php
|
|
|
|
$timeValidator = v::sf('Time')->assert('22:00:01');
|
|
|
|
```
|
|
|
|
|
2015-10-22 04:30:30 +02:00
|
|
|
## Validation methods
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
We've seen `validate()` 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:
|
|
|
|
|
|
|
|
```php
|
2015-10-23 12:46:12 +02:00
|
|
|
use Respect\Validation\Exceptions\ValidationException;
|
2015-01-30 09:40:06 +01:00
|
|
|
|
|
|
|
try {
|
|
|
|
$usernameValidator->check('really messed up screen#name');
|
2015-10-23 12:46:12 +02:00
|
|
|
} catch(ValidationException $exception) {
|
2018-05-22 13:42:10 +02:00
|
|
|
echo $exception->getMessage();
|
2015-01-30 09:40:06 +01:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Message:
|
|
|
|
|
2015-02-17 17:41:56 +01:00
|
|
|
```no-highlight
|
|
|
|
"really messed up screen#name" must contain only letters (a-z) and digits (0-9)
|
|
|
|
```
|