Documentation menu
On this page
Components · v2.x
Validator
The Validator component checks objects, values and arrays against constraints. A constraint is a class used either as a PHP attribute or as an object; its validator is built by the container, so custom validators can use services.
Module
| Manager | NeoPHP\Component\Validator\ValidatorManager (final) |
| Interface | NeoPHP\Component\Validator\ValidatorManagerInterface |
| Attribute | #[Component(provider: ValidatorProvider::class)] |
| Requires | nothing |
Inject ValidatorManagerInterface in a service, a command or a controller:
use NeoPHP\Component\Validator\ValidatorManagerInterface;
public function __construct(private ValidatorManagerInterface $validator)
{
}
The module is enabled by default. To disable it in a project, add it to config/config.php (see the Kernel documentation):
NeoPHP\Component\Validator\ValidatorManager::class => false,
The public API of the module is its manager and its interface, Contract\, the attributes, the exceptions, the events and the classes documented below. The classes marked @internal are used by the framework only.
Quick start
<?php
declare(strict_types=1);
namespace App\Dto;
use NeoPHP\Component\Validator\Constraint as Assert;
class SignupDto
{
#[Assert\NotBlank]
#[Assert\Length(min: 3, max: 20)]
public ?string $username = null;
#[Assert\NotBlank]
#[Assert\Email]
public ?string $email = null;
#[Assert\Length(min: 8)]
public ?string $password = null;
#[Assert\EqualTo(propertyPath: 'password', message: 'The passwords do not match.')]
public ?string $confirm = null;
#[Assert\Valid]
public ?AddressDto $address = null;
}
In a controller, validate() returns the violations:
$violations = $this->validate($dto);
if (count($violations) > 0) {
return $this->json(['errors' => $violations->toArray()], 422);
}
Outside a controller, inject NeoPHP\Component\Validator\ValidatorManagerInterface.
Validating
| Call | Validates |
|---|---|
validate($object) |
the constraints declared with attributes on the object (properties and class) |
validate($value, new Email()) |
a value with one constraint |
validate($value, [new NotBlank(), new Length(min: 3)]) |
a value with several constraints |
validate($data, ['email' => [new NotBlank(), new Email()], 'age' => new Range(min: 18)]) |
an array (or object) field by field; a missing field is null |
validateProperty($object, 'email') |
one property of an object |
validateOrFail(...) |
same as validate(), throws a ValidationFailedException (HTTP 422) when it fails |
<?php
declare(strict_types=1);
namespace App\Service;
use NeoPHP\Component\Validator\Constraint\Email;
use NeoPHP\Component\Validator\Constraint\NotBlank;
use NeoPHP\Component\Validator\ValidatorManagerInterface;
final class NewsletterSubscriber
{
public function __construct(private ValidatorManagerInterface $validator)
{
}
public function subscribe(string $email): void
{
$this->validator->validateOrFail($email, [new NotBlank(), new Email()]);
}
}
Violations
validate() returns a ViolationList (countable and iterable over Violation objects):
| Method | Returns |
|---|---|
count($violations) / count() |
number of violations |
has(?string $path = null) |
whether there is a violation (for a path) |
first(?string $path = null) |
first message, or null |
messages(string $path) |
messages of a path |
get(string $path) |
Violation objects of a path |
all() |
all the Violation objects |
toArray() |
['email' => ['This value is not a valid email address.'], ...] |
add(Violation $violation) / addAll(ViolationList $list) |
adds violations |
Violation: getMessage(), getMessageTemplate(), getParameters(), getPropertyPath(), getInvalidValue(), getConstraint(); it can be cast to string.
Paths: email, address.city (with Valid), tags[1] (with All), data[email] (with Collection).
Constraints
All the constraints are in NeoPHP\Component\Validator\Constraint.
| Constraint | Options |
|---|---|
NotBlank |
allowNull, trim (blank: null, '', [], false) |
Blank, NotNull, IsNull, IsTrue, IsFalse |
|
Type |
type (string, int, float, bool, array, numeric, scalar, iterable, callable, object, alpha, digit, alnum or a class; several allowed) |
Length |
exactly, min, max (characters, UTF-8) |
Count |
exactly, min, max (elements of an array or Countable) |
Range |
min, max (numbers or dates) |
EqualTo, NotEqualTo, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual |
value or propertyPath (compares with another property) |
Positive, PositiveOrZero, Negative, NegativeOrZero |
|
Email, Uuid, Json, Date (Y-m-d) |
|
Url |
protocols (default ['http', 'https']) |
Ip |
version (4, 6 or all) |
DateTime |
format (default Y-m-d H:i:s) |
Regex |
pattern, match (false: the value must not match) |
Choice |
choices or callback, multiple, min, max, strict (default true) |
All |
constraints applied to each element |
Collection |
fields (['email' => [...]]), allowExtraFields, allowMissingFields |
Valid |
validates the nested object (or each object of an array); traverse |
Callback |
callback: method of the object or callable (class or property) |
File |
maxSize (500k, 2M, 1Gi or bytes), mimeTypes (['application/pdf', 'image/*']), extensions (['pdf']); validates an UploadedFile, a SplFileInfo or a path |
Image |
the File options (mimeTypes defaults to image/*), minWidth, maxWidth, minHeight, maxHeight |
Every constraint accepts groups. Except NotBlank, NotNull and IsNull, constraints accept null, and the string constraints (Length, Email, Url, Regex, Uuid, Ip, Date, DateTime...) also accept '': add NotBlank to make a value required. An object reached several times through Valid (a circular reference) is validated once.
File::parseSize(int|string $size): int converts a size (2M, 1Gi) into bytes.
Messages
The constraints accept message (the constraints with several messages, such as Length, Count, Range, Collection, File and Image, take only their specific messages), or their specific messages (minMessage, maxMessage, exactMessage, typeMessage, notInRangeMessage, multipleMessage, missingFieldsMessage, extraFieldsMessage, maxSizeMessage, mimeTypesMessage...).
#[Assert\Length(min: 3, minMessage: 'At least {{ limit }} characters.')]
public ?string $username = null;
Placeholders: {{ value }}, {{ limit }}, {{ min }}, {{ max }}, {{ compared_value }}, {{ choices }}, {{ type }}, and for files {{ size }}, {{ types }}, {{ extension }}, {{ width }}, {{ height }}.
The messages are translated in the current locale through the validators domain of the Translation package (the key is the English message); an untranslated message stays in English. The framework ships no translation: the application translates or rewords the messages it needs in translations/validators.{locale}.yaml (or .xlf):
"This value should not be blank.": "Cette valeur ne doit pas être vide."
"This value is too long. It should have {{ limit }} character(s) or less.": "Cette chaîne est trop longue. Elle doit avoir au maximum {{ limit }} caractère(s)."
The keys are the default messages of the constraints, or the message option given to a constraint.
Groups
A constraint belongs to the Default group (AbstractConstraint::DEFAULT_GROUP), unless groups is given. validate() validates the Default group, unless groups are given:
#[Assert\NotBlank(groups: ['create'])]
public ?string $password = null;
$this->validate($dto, null, ['Default', 'create']);
Nested data
<?php
declare(strict_types=1);
namespace App\Dto;
use NeoPHP\Component\Validator\Constraint as Assert;
class OrderDto
{
#[Assert\Valid]
public array $lines = [];
#[Assert\All([new Assert\NotBlank(), new Assert\Length(max: 20)])]
public array $tags = [];
#[Assert\Collection(fields: [
'email' => [new Assert\NotBlank(), new Assert\Email()],
'phone' => new Assert\Regex('/^\+?[0-9 ]+$/'),
], allowMissingFields: true)]
public array $contact = [];
}
Callback
<?php
declare(strict_types=1);
namespace App\Dto;
use DateTimeImmutable;
use NeoPHP\Component\Validator\Constraint as Assert;
use NeoPHP\Component\Validator\Context\ExecutionContext;
#[Assert\Callback('validatePeriod')]
class BookingDto
{
public ?DateTimeImmutable $start = null;
public ?DateTimeImmutable $end = null;
public function validatePeriod(ExecutionContext $context): void
{
if ($this->start !== null && $this->end !== null && $this->end < $this->start) {
$context->addViolation('The end must be after the start.', [], 'end');
}
}
}
On a property, the method receives ($value, ExecutionContext $context). new Callback(fn (mixed $value, ExecutionContext $context): mixed => ...) works with a closure.
Custom constraints
A constraint extends AbstractConstraint. Its validator is the class with the same name followed by Validator (override validatedBy() to change it). The validator is built by the container: its dependencies are autowired.
<?php
declare(strict_types=1);
namespace App\Validator;
use Attribute;
use NeoPHP\Component\Validator\Contract\AbstractConstraint;
#[Attribute(Attribute::TARGET_PROPERTY)]
class UniqueUsername extends AbstractConstraint
{
public string $message = 'The username {{ value }} is already used.';
}
<?php
declare(strict_types=1);
namespace App\Validator;
use App\Repository\UserRepository;
use NeoPHP\Component\Validator\Context\ExecutionContext;
use NeoPHP\Component\Validator\Contract\AbstractConstraintValidator;
use NeoPHP\Component\Validator\Contract\ConstraintInterface;
class UniqueUsernameValidator extends AbstractConstraintValidator
{
public function __construct(protected UserRepository $users)
{
}
public function validate(mixed $value, ConstraintInterface $constraint, ExecutionContext $context): void
{
$this->expect($constraint, UniqueUsername::class);
if ($this->isEmpty($value)) {
return;
}
if ($this->users->existsByUsername((string) $value)) {
$context->addViolation($constraint->message, ['value' => static::formatValue($value)]);
}
}
}
AbstractConstraintValidator helpers:
| Method | Description |
|---|---|
isEmpty(mixed $value): bool |
true for null and '' |
toString(mixed $value): ?string |
string of a scalar or Stringable, else null |
expect(ConstraintInterface $constraint, string $class): void |
throws a ValidatorException when the constraint has another class |
static formatValue(mixed $value): string |
value formatted for a message ("text", null, true, dates...) |
Execution context
NeoPHP\Component\Validator\Context\ExecutionContext is given to validators and callbacks:
| Method | Description |
|---|---|
addViolation(string $message, array $parameters = [], ?string $path = null, mixed $invalidValue = null) |
adds a violation; $path is relative to the current path |
validate(mixed $value, ConstraintInterface|array $constraints, string $path = '') |
validates a nested value |
validateObject(object $object, string $path = '') |
validates a nested object with its attributes |
getViolations() |
violations collected so far |
getPropertyPath(), getValue(), getConstraint() |
current path, value and constraint |
getObject() |
object being validated |
getRoot() |
value given to validate() |
getGroups() |
validated groups |
JSON errors
ValidationFailedException has the HTTP status 422. For a request that expects JSON, an uncaught one returns a 422 response with the violations:
{"error": {"status": 422, "message": "The data is not valid: 1 violation(s).", "violations": {"username": ["This value should not be blank."]}}}
API
ValidatorManagerInterface
NeoPHP\Component\Validator\ValidatorManagerInterface, implemented by ValidatorManager:
| Method | Description |
|---|---|
validate(mixed $value, ConstraintInterface|array|null $constraints = null, array $groups = ['Default']): ViolationList |
validates a value, an object or an array |
validateProperty(object $object, string $property, array $groups = ['Default']): ViolationList |
validates one property |
validateOrFail(mixed $value, ConstraintInterface|array|null $constraints = null, array $groups = ['Default']): void |
throws a ValidationFailedException |
Contracts
| Interface / class | Methods |
|---|---|
ConstraintInterface |
validatedBy(): string, getGroups(): array, inGroups(array $groups): bool |
AbstractConstraint |
implements ConstraintInterface, public $groups, protected setGroups(?array $groups) |
ConstraintValidatorInterface |
validate(mixed $value, ConstraintInterface $constraint, ExecutionContext $context): void |
AbstractConstraintValidator |
base class of the validators (see Custom constraints) |
Controllers
validate(mixed $value, ConstraintInterface|array|null $constraints = null, array $groups = ['Default']): ViolationList is available in controllers (see the Controller documentation).
Exceptions
| Exception | Description |
|---|---|
ValidatorException |
invalid constraint or validator |
ValidationFailedException |
thrown by validateOrFail(); create(ViolationList $violations), getViolations(): ViolationList; status 422 |
Changelog
- v2.0.1 — Bugfix: an object reached again through
Valid(circular reference) is validated once instead of recursing until memory is exhausted; the invalid value of a missingCollectionfield isnull. - v2.0.0 —
ValidatorManageris thefinalentry point of the module, declared with#[Component];ValidatorManagerInterfacereplacesContract\ValidatorInterface;Contract\AbstractValidatoris merged into the manager;Helper/Listeneris renamedHelper/Event; the internal classes are marked@internal. - v1.20.0 — Messages translated through the Translation package (domain validators).
- v1.12.0 —
FileandImageconstraints. - v1.10.0 — Constraints usable as attributes or objects, validation of objects, values and arrays, groups,
Valid,All,Collection,Callback, custom constraints with autowired validators,validate()in controllers, 422 JSON response forValidationFailedException.