README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Http Response

Полный набор PSR-7/PSR-17 для HTTP-ответов и запросов в одном пакете: неизменяемые сообщения, URI, потоки и загруженные файлы, шесть фабрик, типизированные ответы (JSON/HTML/текст/XML/редирект/пустой), отправка в SAPI, безопасные cookie и заголовки безопасности. Строгая типизация, fail-loud, 100% покрытие и 100% MSI.

Возможности

PSR-7 сообщения — неизменяемые Response, Request, ServerRequest, Uri, Stream, UploadedFile; заголовки без учёта регистра, потоковое тело.
PSR-17 фабрики — все шесть: ResponseFactory, RequestFactory, ServerRequestFactory, StreamFactory, UriFactory, UploadedFileFactory.
Типизированные ответы — JsonResponse, HtmlResponse, TextResponse, XmlResponse, RedirectResponse, EmptyResponse с готовым Content-Type.
Отправка в SAPI — SapiEmitter с потоковой передачей тела.
Безопасные cookie — Cookie с HttpOnly и SameSite=Lax по умолчанию, принудительным Secure при SameSite=None.
Заголовки безопасности — SecurityHeaders: nosniff, X-Frame-Options, Referrer-Policy, Cross-Origin-Opener-Policy, настраиваемые CSP и HSTS.
Сборка из окружения — ServerRequestFactory::fromGlobals() с явными источниками (полностью тестируемо, без суперглобалов).
Fail-loud потоки — сбой операции с потоком бросает исключение, а не возвращает тихий false.
Безопасность по умолчанию — маскирование учётных данных и значений в сообщениях исключений, отклонение внедрения через CRLF, percent-кодирование.

Установка

composer require cloud-castle/http-response

Требуется PHP 8.1+.

Быстрый старт

<?php

use CloudCastle\Http\Response\Cookie;
use CloudCastle\Http\Response\JsonResponse;
use CloudCastle\Http\Response\SapiEmitter;
use CloudCastle\Http\Response\SecurityHeaders;
use CloudCastle\Http\Response\ServerRequestFactory;

// Серверный запрос из окружения.
$request = (new ServerRequestFactory())->fromGlobals($_SERVER, $_GET, $_POST, $_COOKIE, $_FILES);

// Типизированный JSON-ответ с безопасной cookie и заголовками безопасности.
$response = (new JsonResponse(['user' => $request->getAttribute('id')], 201))
    ->withAddedHeader('Set-Cookie', (string) new Cookie('session', 'token'));

$response = (new SecurityHeaders())
    ->withContentSecurityPolicy("default-src 'self'")
    ->withStrictTransportSecurity(31536000)
    ->apply($response);

// Отправка клиенту.
(new SapiEmitter())->emit($response);

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

Снапшот по функционалу (актуальная авто-таблица — в wiki: Comparison).

Возможность	cloud-castle/http-response	nyholm/psr7	guzzle/psr7	laminas-diactoros	slim/psr7	httpsoft/http-message	🏆 Победитель
PSR-7 сообщения	✅	✅	✅	✅	✅	✅	ничья
PSR-17 фабрики (6)	✅	✅	✅	✅	✅	✅	ничья
Типизированные ответы	✅	❌	❌	✅	❌	✅	ничья
SAPI-эмиттер	✅	❌	❌	✅	❌	✅	ничья
Cookie с безопасными дефолтами	✅	❌	❌	❌	❌	❌	🏆 наш
Заголовки безопасности	✅	❌	❌	❌	❌	❌	🏆 наш
Fail-loud потоки	✅	⚠️	⚠️	⚠️	⚠️	⚠️	🏆 наш
Всё в одном пакете	✅	❌	❌	⚠️	❌	❌	🏆 наш
Покрытие / MSI	100% / 100%	—	—	—	—	—	🏆 наш

Производительность

Микробенчмарк hot-path без Xdebug (нс на операцию, меньше — лучше; воспроизведение — tools/benchmark-messages.php с установленными аналогами):

Операция	cloud-castle	nyholm	guzzle	laminas	slim	httpsoft	🏆 Победитель
`new Response(200)`, нс	184	207	550	857	1174	350	🏆 cloud-castle
Разбор URI, нс	1850	1772	8540	5526	2295	2473	nyholm¹
Response, байт/объект	199	195	195	620	1124	195	nyholm/guzzle/httpsoft
URI, байт/объект	427	427	427	467	459	483	🏆 cloud-castle (=nyholm/guzzle)

¹ nyholm на ~4% быстрее на разборе URI ценой отсутствия валидации схемы; cloud-castle валидирует схему по RFC 3986 и всё равно обгоняет slim, httpsoft, laminas и guzzle. По созданию ответа (самый частый hot-path) cloud-castle — первый.

Плюсы и минусы

Плюсы:

Суперсет функционала: PSR-7 + PSR-17 + типизированные ответы + эмиттер + cookie + заголовки безопасности в одном пакете — не нужно собирать из частей.
Скорость: создание ответа быстрее всех сравниваемых аналогов; разбор URI — второй с валидацией схемы (см. таблицу производительности).
Безопасность по умолчанию: жёсткие дефолты cookie, профиль security-заголовков, маскирование чувствительных данных в исключениях, защита от CRLF-инъекций.
Качество: 100% покрытие строк и 100% Infection MSI, полный статанализ (PHPStan max, Psalm errorLevel 1, PHPMD, Deptrac, Rector, PHP-CS-Fixer, PHPCS).
Минимум зависимостей: PSR-интерфейсы и один инфраструктурный пакет cloud-castle/support; без тяжёлых сторонних зависимостей.

Минусы:

Пакет моложе и менее распространён, чем nyholm/psr7, guzzle/psr7 или laminas-diactoros: меньше звёзд, установок и короче история эксплуатации.

Когда применять

Веб-API и микросервисы — где нужен полный цикл ответа с типизированными результатами и отправкой в SAPI без дополнительных пакетов.
Финтех и приложения с требованиями к безопасности — где важны жёсткие дефолты cookie, заголовки безопасности и отсутствие утечек данных в ошибках.
Проекты на PSR-7/PSR-17 — как совместимая реализация с провайдингом psr/http-factory-implementation и psr/http-message-implementation.

Если уже используется guzzle-экосистема целиком или нужна только клиентская HTTP-часть — специализированные клиентские пакеты могут подойти лучше.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/http-response
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия