Запросы и привязка параметров

Winter сам наполняет аргументы метода данными запроса. Вы объявляете, что нужно — тип и атрибут источника — а фреймворк читает запрос, приводит значение к типу и передаёт его в метод. Никаких $_GET, $_POST и json_decode в коде контроллера.

Что такое привязка параметров и зачем

Привязка параметров (parameter binding) — это автоматическое преобразование сырого HTTP-запроса в готовые, типизированные аргументы метода.

Проблема. Данные из HTTP приходят строками и лежат в разных местах: часть в пути URL, часть в query-строке, часть в теле (JSON, форма или XML), что-то в заголовках. Разбирать их вручную, проверять наличие, приводить "42" к int — это рутина, которая повторяется в каждом методе и легко даёт ошибки. Причём ошибки тихие: забытая проверка на null всплывёт не здесь, а тремя слоями глубже.

Решение. Опишите параметр типом и атрибутом источника — остальное сделает фреймворк: найдёт значение в нужном месте запроса, приведёт к объявленному типу и передаст в метод, а при несоответствии вернёт 400 ещё до входа в ваш код.

Начнём, однако, с того, что лежит под привязкой, — с самого объекта запроса.

Объект запроса

HttpRequest — это весь входящий запрос одним объектом. Чтобы его получить, достаточно объявить аргумент такого типа; никакого атрибута не нужно:

use Flytachi\Winter\Kernel\Http\Contracts\HttpRequest;

#[PostMapping('webhook')]
public function webhook(HttpRequest $request): ResponseEntity
{
  $signature = $request->getHeader('X-Signature');
  $payload   = $request->getRawBody();
  // ...
}

Это интерфейс, а не класс: под ним лежит либо SwooleRequest, либо FpmRequest, в зависимости от того, как приложение запущено. Ваш код разницы не видит — в этом и смысл.

Данные запроса

Заголовки

Кто и откуда пришёл

Эта группа отвечает на вопросы, ответ на которые за обратным прокси не совпадает с тем, что видит сокет. Все методы учитывают заголовки проксирования:

Нужен и объект ответа — объявляется так же, по типу HttpResponse. Он пригождается редко: обычно ответ собирают возвратом значения из метода, см. Контроллеры.

Как работает привязка

Обращаться к HttpRequest напрямую приходится нечасто — почти всё, что из него достают, фреймворк умеет разложить по аргументам сам.

Когда маршрут найден, перед вызовом метода отрабатывает ParameterResolver. Он идёт по параметрам метода и для каждого:

1. читает объявленный тип и атрибут источника;
2. находит значение в нужном месте запроса;
3. проверяет, обязателен ли параметр, если значения нет;
4. приводит к объявленному PHP-типу;
5. подставляет в аргумент.

#[GetMapping('orders/{id:\d+}')]
public function show(
  #[PathVariable]  int    $id,             // из пути
  #[RequestParam]  int    $page = 1,       // из query ?page=
  #[RequestHeader] string $authorization,  // из заголовка
): ResponseEntity {
  // всё уже найдено, проверено и приведено к типам
}

Сравните с тем же кодом на сыром запросе — три обращения, три проверки на отсутствие, два приведения типа и ни одного внятного сообщения об ошибке.

Откуда брать данные

Каждому месту в запросе — свой атрибут. Все живут в Flytachi\Winter\Kernel\Http\Request\Annotation:

Дальше — по одному разделу на источник.

Путь — #[PathVariable]

Берёт динамический сегмент URL. Имя аргумента должно совпадать с именем сегмента в маршруте:

#[GetMapping('users/{id}/posts/{slug}')]
public function post(
  #[PathVariable] int    $id,     // /users/42/... → 42
  #[PathVariable] string $slug,   // .../hello     → "hello"
): ResponseEntity { /* ... */ }

Связь идёт по имени, а не по позиции — порядок аргументов значения не имеет.

Аргументы атрибута

#[GetMapping('posts/{id}')]
public function show(#[PathVariable('id')] int $postId): ResponseEntity { /* ... */ }

Сегмент обязателен: если маршрут совпал, значение есть всегда. Подробнее про сами шаблоны путей и ограничения регулярными выражениями — на странице Маршрутизация.

Query-строка

Для query есть два атрибута, и выбор между ними — это выбор между «несколько отдельных значений» и «один объект фильтра».

Одно значение — #[RequestParam]

#[GetMapping('orders')]
public function list(
  #[RequestParam] int     $page   = 1,      // ?page=2
  #[RequestParam] ?string $search = null,   // ?search=telefon
  #[RequestParam] bool    $active = false,  // ?active=true
  #[RequestParam] array   $ids    = [],     // ?ids[]=1&ids[]=2
): ResponseEntity { /* ... */ }

Имя ищется в трёх написаниях. Аргумент $pageSize поймает ?pageSize=, ?page_size= и ?page-size= — фронтенду не нужно подстраиваться под стиль именования PHP.

Аргументы атрибута

#[RequestParam('per_page')] int $perPage = 20,   // только ?per_page=

Явное имя отключает поиск в трёх написаниях — совпадение проверяется только точное. Это ловушка: при #[RequestParam('page_size')] присланный ?pageSize=25 не подойдёт и молча уйдёт в значение по умолчанию.

Много значений — #[RequestQuery]

Когда параметров фильтра много, вместо десятка аргументов удобнее один объект. Поля заполняются из query по именам и приводятся к типам конструктора — по тем же правилам, что и #[RequestParam]:

class OrderFilter
{
  public function __construct(
      public readonly int     $page   = 1,
      public readonly int     $limit  = 20,
      public readonly ?string $search = null,
  ) {}
}

#[GetMapping('orders')]
public function list(#[RequestQuery] OrderFilter $filter): ResponseEntity
{
  // ?page=2&limit=50&search=nokia → $filter->page === 2 (int, не строка)
}

Атрибут всегда необязателен: пустая query-строка даёт объект со значениями по умолчанию, а не ошибку. Поэтому у полей DTO имеет смысл всегда задавать дефолты.

Кроме своего класса принимает array (тогда придёт вся query как есть) и stdClass. Чтобы поля ещё и проверялись, добавьте #[Valid] — см. Валидацию.

Заголовки — #[RequestHeader]

Имя заголовка выводится из имени аргумента: camelCase и snake_case переводятся в kebab-case, а поиск идёт без учёта регистра.

public function handle(
  #[RequestHeader] string  $authorization,     // Authorization
  #[RequestHeader] ?string $xRequestedWith,    // X-Requested-With
  #[RequestHeader] ?string $accept_language,   // Accept-Language
): ResponseEntity { /* ... */ }

Аргументы атрибута

#[RequestHeader('X-Trace-Id')] string $trace,

Явное имя удобно, когда заголовок не переводится в имя переменной красиво, — но регистр по-прежнему не важен, так что 'x-trace-id' и 'X-Trace-Id' равнозначны.

Для нескольких заголовков сразу или для тех, что нужны условно, проще взять HttpRequest и спросить getHeader() — привязка не обязана покрывать всё.

Тело запроса

Тело — самый нагруженный источник: в нём приходит JSON, форма или XML, а положить его нужно то в объект, то в массив, то целиком в строку. Поэтому атрибутов здесь четыре: один с автоопределением формата и три с явно заданным.

#[RequestBody] — формат по Content-Type

Основной вариант. Формат определяется по заголовку, а во что разобрать — по типу аргумента:

#[PostMapping('orders')]
public function create(#[RequestBody] CreateOrderDto $dto): ResponseEntity
{
  // тело разобрано и разложено по полям DTO
}

Формат определяется по Content-Type:

То есть форма разбирается наравне с JSON — отдельный атрибут для неё нужен только тогда, когда формат надо зафиксировать, не полагаясь на заголовок клиента.

Сырое тело

Аргумент типа string отдаёт тело как есть, ничего не разбирая. Это то, что нужно для вебхуков с подписью: подпись считается по исходным байтам, и любой разбор с пересборкой её ломает.

#[PostMapping('webhook')]
public function webhook(
  #[RequestBody]   string $raw,
  #[RequestHeader] string $xSignature,
): ResponseEntity {
  if (!hash_equals($xSignature, hash_hmac('sha256', $raw, env('WEBHOOK_SECRET')))) {
      throw new RequestException('Bad signature');
  }
  // ...
}

Одно поле — аргумент field

Когда из тела нужно одно значение, необязательно заводить под него класс. Аргумент field достаёт значение по ключу и приводит к типу аргумента:

#[PatchMapping('{id:\d+}/name')]
public function rename(
  #[PathVariable] int $id,
  #[RequestBody(field: 'name')] string $name,
): ResponseEntity { /* {"name": "..."} → $name */ }

Поддерживается точечная нотация для вложенных структур:

#[RequestJson(field: 'user.email')] string $email,      // {"user":{"email":"..."}}
#[RequestBody(field: 'filter.minPrice')] int $min,      // приведёт к int

Значение обязательно по умолчанию, а ограничения на таком аргументе срабатывают сами — #[Valid] для них не нужен:

#[RequestBody(field: 'name'), Size(5, 40)] string $name,

Аргумент field есть у всех четырёх атрибутов тела.

Принудительный формат

Когда клиент присылает неверный Content-Type или формат нужно зафиксировать, берите атрибут с явным форматом вместо автоопределения:

public function a(#[RequestJson] CreateOrderDto $dto): ResponseEntity {}
public function b(#[RequestForm] array $form): ResponseEntity {}
public function c(#[RequestXml]  \stdClass $node): ResponseEntity {}

Правила по типам аргумента и field у них те же, что у #[RequestBody].

Массив объектов

Вариадик-параметр разворачивает JSON-массив в набор DTO — для массовых операций:

#[PostMapping('orders/bulk')]
public function bulk(#[RequestBody, Valid] OrderDto ...$orders): ResponseEntity
{
  // [{"..."}, {"..."}] → $orders[0], $orders[1], ...
}

Тело обязано быть JSON-массивом; объект или что-то иное даст 400 с сообщением Expected JSON array for variadic body. Ошибки нумеруются по индексу элемента, так что видно, какой именно объект в пачке не прошёл.

Ошибки разбора

Поля DTO проверяются на наличие и тип, и все ошибки собираются разом, а не по первой:

POST /orders  {}

400 {"name": ["is required"], "qty": ["is required"]}

Это проверка структуры: поле есть, поле нужного типа. Содержательные правила — длина, диапазон, формат — включаются атрибутом #[Valid] на параметре, см. Валидацию.

Файлы

#[RequestFile] привязывает файл, загруженный через multipart/form-data. Кроме самой привязки атрибут умеет проверять размер и тип — то есть отсеивать негодную загрузку до входа в ваш метод.

Один файл

Аргумент типа array получает данные о файле — те же ключи, что в $_FILES:

#[PostMapping('avatar')]
public function upload(#[RequestFile('avatar')] array $file): ResponseEntity
{
  // ['name' => 'photo.jpg', 'type' => 'image/jpeg',
  //  'tmp_name' => '/tmp/php7Xy', 'size' => 12345, 'error' => 0]

  move_uploaded_file($file['tmp_name'], $target);
}

Если нужно не описание, а содержимое — объявите аргумент string, и файл будет прочитан за вас:

#[PostMapping('import')]
public function import(#[RequestFile('report')] string $csv): ResponseEntity
{
  // $csv — байты файла; временный файл читать самому не нужно
}

Несколько файлов

Поле с <input name="images[]" multiple> разбирается флагом multiple. Приходит список, даже если файл прислали один:

#[PostMapping('gallery')]
public function gallery(#[RequestFile('images', multiple: true)] array $images): ResponseEntity
{
  foreach ($images as $image) { /* каждый — такой же массив данных */ }
}

Без имени поля приходит вся карта загруженных файлов — ключи полей формы, значения описания:

#[RequestFile] array $files,   // ['avatar' => [...], 'images' => [[...], [...]]]

Проверка размера и типа

#[RequestFile('avatar', maxSize: '5MB', accept: ['image/jpeg', 'image/png'])] array $avatar,

maxSize понимает B, KB, MB, GB и дробные значения ('1.5MB'); единицы двоичные, 1KB — это 1024 байта. Голое число считается байтами. При multiple: true предел применяется к каждому файлу отдельно.

accept принимает три формы записи:

Чего ждать при ошибке

Все проверки отвечают 400 и не пускают запрос в контроллер:

Файл можно сделать необязательным обычным способом — значением по умолчанию или типом ?array:

#[RequestFile('avatar')] ?array $avatar = null,   // без файла придёт null

Приведение типов

Из HTTP всё приходит строками. Резолвер приводит значение к типу, объявленному у аргумента, и если привести не получается — отвечает 400 ещё до входа в метод.

Сообщения об ошибке называют и параметр, и ожидание:

?page=abc     → 400  Query parameter 'page' must be an integer, got 'abc'
?status=hz    → 400  Query parameter 'status' must be one of [draft, published], got 'hz'
?from=31-01   → 400  Query parameter 'from' has invalid date '31-01' — expected ISO 8601

Обязательные и опциональные

Параметр из HTTP-источника обязателен по умолчанию. Необязательным его делают двумя способами:

int  $page          // обязателен: нет значения → 400
int  $page = 1      // нет значения → 1
?int $page          // нет значения → null
?int $page = null   // то же самое, но нагляднее

Порядок разрешения при отсутствии значения: есть значение по умолчанию — вернуть его; тип допускает null — вернуть null; иначе — 400.

Правила разрешения

Резолвер проверяет источники в фиксированном порядке и берёт первое совпадение. Знать порядок нужно в одном случае: если на параметре оказалось два атрибута, сработает тот, что выше.

 1. #[PathVariable]     сегмент пути
2. #[RequestParam]     один параметр query
3. #[RequestBody]      тело, формат по Content-Type
4. #[RequestFile]      загруженный файл
5. #[RequestJson]      тело как JSON
6. #[RequestForm]      тело как форма
7. #[RequestXml]       тело как XML
8. #[RequestQuery]     вся query-строка
9. #[RequestHeader]    заголовок
10. тип HttpRequest     объект запроса
11. тип HttpResponse    объект ответа
12. совпадение по имени сегмент пути без атрибута
13. значение по умолчанию
14. тип допускает null  → null

Пункт 12 объясняет, почему #[PathVariable] можно не писать: если имя аргумента совпадает с именем сегмента, значение найдётся и без атрибута. С атрибутом код читается однозначнее, поэтому в примерах он оставлен.

Если не подошло ни одно правило, запрос падает с RuntimeException:

Cannot resolve parameter '$foo' in PostController::create()
— add an annotation or a default value

Это ошибка не клиента, а сигнатуры метода, поэтому ответ будет 500. И проявится она при обращении к эндпоинту, а не при запуске приложения: резолвер работает на каждом запросе. Проверяйте новые обработчики хотя бы одним вызовом.

Один тип на параметр

Объединённые и пересечённые типы на HTTP-параметрах не поддерживаются — резолвер отвергает их до всякого приведения:

// ✗ LogicException: Union/intersection type on '$value' is not supported
public function a(#[RequestParam] int|string $value): void {}

// ✓ один тип
public function b(#[RequestParam] string $value): void {}

Причина простая: у объединения нет одного правила приведения — непонятно, чем должна стать строка "42".

Дальше

• Валидация — #[Valid] и содержательные проверки полей
• Маршрутизация — шаблоны путей для #[PathVariable]
• Ответы — форматы и коды ответа
• Обработка ошибок — во что превращается 400
• Контроллеры — где живут эти сигнатуры