Ответы

Контроллер возвращает ответ, а не пишет в поток руками. Чаще всего это ResponseEntity — данные вместе с HTTP-кодом. Фреймворк сам подберёт формат, выставит заголовки и отправит всё одинаково под любым рантаймом.

Что такое ответ и зачем

Ответ — это то, что уходит клиенту: код состояния, заголовки и тело.

Проблема. Собирать его вручную — значит в каждом обработчике выставить статус, сериализовать данные, не забыть Content-Type и Content-Length, закрыть соединение. Кода немного, но он транспортный: к задаче эндпоинта отношения не имеет, повторяется везде и под Swoole с PHP-FPM пишется по-разному. Забытый заголовок при этом проявится не ошибкой, а странным поведением у клиента.

Решение. Верните из метода объект ответа. Он знает, каким кодом отвечать, как сериализовать тело и какие заголовки нужны, а отправкой занимается фреймворк — одинаково при любом способе запуска.

Что можно вернуть

return ResponseEntity::ok($data);       // объект ответа — обычный путь
return $this->service->all();          // просто данные — обернутся в 200
throw new ResponseException(...);      // ошибка — станет ответом сама

Первый вариант нужен, когда важны код или заголовки; второй — когда это обычная успешная выдача. Третий разобран в Обработке ошибок.

ResponseEntity — данные

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

Готовые коды

Тело у всех необязательно: ResponseEntity::notFound() вернёт код без тела.

Любой код и заголовки

use Flytachi\Winter\Base\HttpCode;

return ResponseEntity::status(HttpCode::IM_A_TEAPOT)->body($data);

return ResponseEntity::ok($data)
  ->header('X-Request-Id', $requestId)
  ->header('X-Total-Count', (string) $total);

HttpCode — перечисление всех кодов, так что подсказка редактора избавляет от магических чисел. Вызовы body() и header() цепляются.

Чтение уже собранного ответа

Пригождается в after() у middleware — например, чтобы завернуть тело в общий конверт, не трогая обработчики. См. Middleware.

Согласование формата

Как сериализовать тело, решает тип тела, а для структур — ещё и заголовок Accept клиента.

То есть return ResponseEntity::ok('pong') отдаст текст, а не JSON-строку — на это стоит обратить внимание, если клиент разбирает ответ как JSON безусловно.

Объект, у которого есть метод toArray(), перед сериализацией проходит через него — сущности и DTO отдаются как есть, разворачивать их вручную не нужно.

ResponseFile — файлы и выгрузки

Собирает файл в памяти и отдаёт клиенту. Подходит для того, что вы только что сформировали: отчёта, выгрузки, сгенерированного документа.

Имя файла обязательно у всех, кроме file().

#[GetMapping('report')]
public function report(): ResponseFile
{
  return ResponseFile::csv($this->service->rows(), 'report.csv');
}

Настройка отдачи

return ResponseFile::csv($rows, 'export.csv')
  ->attachment()                    // диалог сохранения
  ->inline()                        // показать в браузере
  ->maxAge(3600)                    // Cache-Control: public, max-age=3600
  ->header('X-Source', 'generated');

По умолчанию binary и csv уходят как вложение, остальные — на просмотр.

Каждый ответ этого типа выставляет Content-Length и отключает сжатие (Content-Encoding: identity): иначе объявленная длина разойдётся с фактической, и клиент получит обрезанный файл.

ResponseStreamFile — большие файлы

ResponseFile::file() читает файл в память целиком, а значит упирается в лимит памяти воркера — общий на все одновременные запросы. Для видео, архивов и дампов берите потоковую отдачу: файл уходит с диска напрямую, минуя кучу PHP.

return ResponseStreamFile::open('/var/media/video.mp4');                  // просмотр
return ResponseStreamFile::open('/var/export/dump.sql')->attachment();   // скачивание

Это не просто «отдать файл» — ответ ведёт себя как полноценный файловый сервер:

Отключить частичную отдачу — ->acceptRanges(false): сервер объявит Accept-Ranges: none и проигнорирует Range. Нужно там, где важна атомарность выдачи: подсчёт скачиваний, одноразовые ссылки.

Что выбрать

HTML — ResponseView

Серверный рендеринг шаблонов с макетами и данными — отдельная тема, разобранная на странице Представления.

return ResponseView::render('layouts/main', 'users/index', ['users' => $users]);

Запросы HEAD

На HEAD фреймворк отдаёт те же статус и заголовки, что отдал бы на GET, включая Content-Length, но без тела — подавление происходит централизованно, каждому типу ответа заботиться об этом не нужно.

Свои ответы — Sendable

Все типы ответа объединяет один интерфейс. Реализуйте его, если нужен формат, которого нет из коробки:

<?php

namespace Main;

use Flytachi\Winter\Kernel\Http\Contracts\HttpRequest;
use Flytachi\Winter\Kernel\Http\Contracts\HttpResponse;
use Flytachi\Winter\Kernel\Http\Response\Sendable;

class IcsResponse implements Sendable
{
  public function __construct(private string $calendar, private string $fileName) {}

  public function send(HttpResponse $response, HttpRequest $request): void
  {
      $response->status(200);
      $response->header('Content-Type', 'text/calendar; charset=utf-8');
      $response->header('Content-Disposition', "attachment; filename=\"{$this->fileName}\"");
      $response->end($this->calendar);
  }
}

Вернули такой объект из метода — фреймворк вызовет send() и больше ни во что не вмешается.

Метод получает и запрос тоже — чтобы можно было посмотреть на Accept, обработать Range или ответить 304. Не нужен — просто не используйте аргумент.

Через HttpResponse доступны четыре операции: status(), header(), end() и sendfile(). За этим интерфейсом стоит либо Swoole, либо PHP-FPM, поэтому ваш ответ работает при любом способе запуска без единой правки.

Встроенные реализации: ResponseEntity, ResponseFile, ResponseStreamFile, ResponseView.

Дальше

• Обработка ошибок — ответы, которые получаются из исключений
• Представления — серверный HTML через ResponseView
• Контроллеры — где эти объекты возвращаются
• Запросы и привязка параметров — входная сторона цикла