HTTP-ответ

Response — изменяемый объект Server, не immutable PSR-7 response. Каждый with*() возвращает тот же экземпляр. Создавайте ответ на каждый запрос; не переиспользуйте общий объект между клиентами.

Заголовки и cookie

header()/withHeader(), withHeaders() изменяют карту. getHeader() и withoutHeader() ищут имя без учёта регистра, но запись хранит переданный регистр: не добавляйте одно имя с разным регистром. getHeaders() возвращает карту. При сериализации CR/LF удаляются из имён/значений; это не основание принимать произвольные пользовательские заголовки.

cookie($name, $value, $maxAge, $path, $domain, $secure, $httpOnly, $sameSite) добавляет Set-Cookie, кодируя имя/значение. Параметр времени — Max-Age в секундах, не Unix timestamp. Для auth-cookie задайте подходящие Secure/HttpOnly/SameSite и область; CSRF контролируется приложением.

Файлы и условные запросы

withFile($path, $offset = 0, $length = 0) готовит метаданные; реальную отправку выполняет HTTP codec, а не (string)$response. Не найденный/нечитаемый файл даёт 404. Отрицательные offset/length запрещены. Путь выбирайте из разрешённого хранилища после проверки доступа, не склеивайте с непроверенным URL.

withFileForRequest($request, $path) добавляет обработку GET/HEAD, preconditions (412), validators (304) и одного byte range (416 для невыполнимого). Несколько ranges дают полный ответ; multipart/byteranges не формируется. Успешный диапазон хранится в метаданных для codec. ETag строится из mtime/size, не из хеша содержимого.

Сжатие и поток

withCompressionForRequest($request, $minBytes = 1024, $level = -1) включает gzip только явно: учитывает q-values, Range, no-transform, уже заданное кодирование/stream/file и уменьшение размера. Не смешивайте секреты и отражённый ввод в сжимаемом ответе без оценки утечки по длине.

withChunkedTransfer() удаляет Content-Length и очищает тело. После отправки заголовков отправляйте Chunk и завершайте пустым Chunk; не посылайте новый Response на каждое событие. Рабочий SSE показан в сборнике.

Source.