Validation

Validation in Winter is declarative: the rules are attributes on an object’s fields, and #[Valid] on a method parameter switches the checking on. The framework collects every violation in one pass and answers 422 with a field-to-errors map.

What validation is and why

Validation is checking that incoming data matches expectations before it reaches business logic.

The problem. The client cannot be trusted: it will send an empty name, a broken email, a negative quantity. Checking that by hand means a wall of ifs at the top of every method, mixed in with the logic and living far away from where the data is described. Worse, hand-written checks nearly always stop at the first error, so the user fixes the form one field at a time and submits it five times over.

The solution. Describe the rules as attributes right where the fields are declared. The framework checks them all, collects the violations at once and returns 422 with a field-to-error-list map. The object reaches your method already validated — there is nothing left to check in the handler.

Switching it on

Rules go on the object’s constructor parameters; #[Valid] on the method parameter turns the checking on:

<?php

namespace Main;

use Flytachi\Winter\Kernel\Http\Request\Validation\{Required, NotBlank, Size, Email, Min, Max};

class CreateUserDto
{
  public function __construct(
      #[Required] #[NotBlank] #[Size(2, 100)]
      public readonly string $name,

      #[Required] #[Email]
      public readonly string $email,

      #[Min(0)] #[Max(150)]
      public readonly int $age = 0,
  ) {}
}

#[PostMapping('users')]
public function create(#[Valid, RequestJson] CreateUserDto $dto): ResponseEntity
{
  // $dto only gets here validated
  return ResponseEntity::created($this->service->create($dto));
}

Attributes stack: a field may carry as many as you like and all of them run.

On scalar parameters — no #[Valid] needed

One exception worth knowing: a constraint placed directly on a scalar method parameter fires by itself.

#[GetMapping]
public function index(#[RequestParam, Min(1)] int $page = 1): ResponseEntity
{
  // ?page=0 → 422 {"page": ["must be at least 1"]}
}

#[PathVariable], #[RequestHeader] and single-field extraction via field: behave the same way. #[Valid] is only needed where the thing being checked is an object.

The error format

A failure returns 422 Unprocessable Entity with a map: the key is the field name, the value is the list of all its violations.

{
"code": 422,
"message": "Validation failed",
"errors": {
  "name":  ["is required"],
  "email": ["must be a valid email address"],
  "age":   ["must not exceed 150"]
}
}

Keys for nested structures are built from the path to the field:

Constraint reference

They all live in Flytachi\Winter\Kernel\Http\Request\Validation. Every one takes an optional message argument — covered below.

Presence

Numbers

#[Min] and #[Max] accept whole and fractional thresholds alike.

Size

What exactly is measured depends on the value’s type:

There are only two forms — exact and range. #[Size(2, 255)] is the same as #[Size(min: 2, max: 255)] if you prefer named arguments.

Strings and formats

#[In] takes a second argument strict (true by default) — type-aware comparison. Pass strict: false if the string "1" should count as equal to the number 1.

Network and phone

#[Msisdn] is the stricter one: it is for a number heading into a gateway, so it allows digits only. #[Phone] is for what a human typed.

Date and time

These constraints check a string. If the field is declared as DateTimeImmutable, parsing happens earlier, during binding, and an invalid date produces 400 before validation is reached.

Nested objects and collections

A nested object

Declaring a field with another object’s type is enough — checking descends into it by itself, no #[Valid] on the field required:

class FilterDto
{
  public function __construct(
      #[Min(0)] public readonly int $minPrice = 0,
      #[Max(1_000_000)] public readonly int $maxPrice = 0,
  ) {}
}

class SearchDto
{
  public function __construct(
      #[NotBlank] public readonly string $query,
      public readonly FilterDto $filter,     // checked along with its parent
  ) {}
}

{"errors": {"filter.minPrice": ["must be at least 0"]}}

A collection of objects

An array has no element type, so it is named with the #[ListOf] attribute. Each element is parsed and checked like an ordinary object:

class OrderDto
{
  public function __construct(
      #[NotBlank] public readonly string $customer,

      #[ListOf(ItemDto::class)]
      public readonly array $items = [],
  ) {}
}

{"errors": {"items[1].name": ["must not be blank"]}}

The index in the key shows exactly which element failed — uploading a batch of a hundred positions, that is the only thing that lets you find the culprit.

Bulk upload

When a batch of objects arrives as the root of the body, a variadic parameter takes the place of a collection. Error keys then start with the index:

#[PostMapping('orders/bulk')]
public function bulk(#[Valid, RequestBody] OrderDto ...$orders): ResponseEntity {}
// {"errors": {"[0].customer": ["must not be blank"]}}

Custom messages

Every constraint takes a message argument that replaces the default text:

#[Size(2, 100, message: 'The name must be between 2 and 100 characters')]
public readonly string $name,

#[Min(0, message: 'Quantity cannot be negative')]
public readonly int $qty,

Translation

If the message is wrapped entirely in braces it is treated as a translation key and resolved through localization:

#[Size(2, 100, message: '{order.name_length}')]
public readonly string $name,

return [
  'order' => [
      'name_length' => 'Field ":field": from :min to :max characters',
  ],
];

The substitutions include :field — the field name — and any public property of the constraint itself: :min, :max, :value, :format, :pattern, :values. Which ones are available is visible from the constructor arguments.

A key that is not found comes back as it is, with no exception — a typo in the key shows up as a string in the response rather than as a crash.

A check of your own — #[Assert]

When no built-in constraint fits, plug in your own function. It receives the value and the field name, and returns null on success or a string with the error:

<?php

namespace Main;

class OrderRules
{
  public static function multipleOf100(mixed $value, string $field): ?string
  {
      return is_int($value) && $value > 0 && $value % 100 === 0
          ? null
          : 'must be a positive multiple of 100';
  }
}

use Flytachi\Winter\Kernel\Http\Request\Validation\Assert;

class CreateOrderDto
{
  public function __construct(
      #[Assert(OrderRules::class . '::multipleOf100')]
      public readonly int $amount,
  ) {}
}

The attribute is repeatable — one field can carry several checks and all of them run:

#[Assert(OrderRules::class . '::multipleOf100')]
#[Assert(OrderRules::class . '::withinCreditLimit')]
public readonly int $amount,

Your own constraint — the Constraint interface

#[Assert] is good for a one-off check. When a rule repeats across several DTOs, or has parameters of its own, make it your own attribute — it will be no different from the built-in ones.

You need a class implementing Constraint: one method, null on success, a string with the error on failure.

<?php

namespace Main\Validation;

use Attribute;
use Flytachi\Winter\Kernel\Http\Request\Validation\Constraint;

#[Attribute(Attribute::TARGET_PARAMETER)]
final readonly class DivisibleBy implements Constraint
{
  public function __construct(
      public int $step,
      public ?string $message = null,
  ) {}

  public function validate(mixed $value, string $field): ?string
  {
      if ($value === null) {
          return null;                       // an empty field is #[Required]'s business
      }

      return is_int($value) && $value % $this->step === 0
          ? null
          : $this->message ?? "must be divisible by {$this->step}";
  }
}

From then on it is used like any built-in one, alongside them and with its own message:

class CreateOrderDto
{
  public function __construct(
      #[Positive]
      #[DivisibleBy(100)]
      public readonly int $amount,

      #[DivisibleBy(50, message: 'Weight is specified in steps of 50 grams')]
      public readonly int $weight,
  ) {}
}

Three rules

The attribute targets a parameter. #[Attribute(Attribute::TARGET_PARAMETER)] — a DTO is described by constructor parameters, and the checks live there too. Add Attribute::IS_REPEATABLE if hanging the rule twice makes sense.

Pass null through. An absent value is the business of #[Required] and of the property type, not yours. Every built-in constraint works that way: #[Size(2, 100)] on a nullable field stays silent until a value arrives. Without that check your rule starts demanding a field where it is optional.

The message is returned as a string. It lands in the 422 response under the field name. The message argument for overriding it is a convention every built-in constraint follows, and yours should too. A string in braces is treated by the framework as a translation key — see Localization.

Which to choose

The difference is only in packaging: the contract is the same — (mixed $value, string $field): ?string — and both forms run in the same validation pass.

Next

• Requests — where the object comes from, and how 400 differs from 422
• Error handling — what the client receives on a failure
• Localization — translating messages
• Controllers — where #[Valid] is placed