README

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

CloudCastle Http Request

Быстрая и безопасная реализация PSR-7/PSR-17 для PHP 8.1+: неизменяемые Request, Uri, Stream и фабрики. Fail-loud на любом некорректном вводе, строгая валидация метода и заголовков (RFC 7230), а исключения не содержат значений заголовков и данных — безопасно для логов с персональными данными. Единственные зависимости — контракты psr/http-*.

Установка

composer require cloud-castle/http-request

Требуется PHP 8.1+ и расширение ext-* не нужно — только контракты PSR.

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

<?php

use CloudCastle\Http\Request\Request;
use CloudCastle\Http\Request\Stream;
use CloudCastle\Http\Request\Uri;

// Собрать исходящий запрос (неизменяемый, заголовок Host выставляется из URI).
$request = (new Request('GET', new Uri('https://api.example.com/v1/items?page=2')))
    ->withHeader('Accept', 'application/json')
    ->withHeader('Authorization', 'Bearer …');

$request->getMethod();                 // 'GET'
$request->getHeaderLine('accept');     // 'application/json' (регистр не важен)
$request->getUri()->getHost();         // 'api.example.com'
$request->getRequestTarget();          // '/v1/items?page=2'

// Тело через поток (PSR-7 StreamInterface, fail-loud).
$withBody = $request
    ->withMethod('POST')
    ->withBody(Stream::fromString('{"name":"widget"}'));

// PSR-17 фабрики — для кода, который принимает интерфейсы.
use CloudCastle\Http\Request\RequestFactory;
use CloudCastle\Http\Request\StreamFactory;
use CloudCastle\Http\Request\UriFactory;

$request = (new RequestFactory())->createRequest('GET', 'https://example.com/');
$uri = (new UriFactory())->createUri('https://example.com:443/'); // порт 443 опускается
$stream = (new StreamFactory())->createStream('payload');

Возможности

PSR-7 сообщения: Request, Uri, Stream — неизменяемые, все with* возвращают новый экземпляр.
PSR-17 фабрики: RequestFactory, UriFactory, StreamFactory.
Fail-loud: некорректный метод, имя/значение заголовка или порт URI — сразу исключение (InvalidMethodException/InvalidHeaderException/InvalidUriException/ StreamException), а не тихая порча данных.
Строгая валидация метода и заголовков по RFC 7230 (защита от инъекции CRLF) и диапазона порта URI (1–65535).
Исключения не раскрывают данные — в сообщении только имя заголовка/причина, без значения; безопасно для логов с персональными и финансовыми данными.
Нормализация URI по RFC 3986: схема/хост в нижнем регистре, стандартный порт опускается, ленивое процент-кодирование пути (без затрат, если путь не читают).
Регистронезависимые заголовки с сохранением исходного написания имени.
Минимум зависимостей — только контракты psr/http-factory и psr/http-message, без polyfill'ов и getallheaders.

Коротко

Лёгкий, быстрый и безопасный слой PSR-7/17 для исходящих HTTP-запросов: строгая валидация метода и заголовков (без CRLF-инъекций), исключения без раскрытия значений (безопасно для логов с ПД), нормализация URI по RFC 3986 — при минимуме зависимостей. Лидер по функционалу, скорости и безопасности среди PSR-7 реализаций; по памяти — практически вровень с самым лёгким nyholm.

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

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	nyholm	guzzle	laminas	slim	httpsoft
Неизменяемые PSR-7 сообщения (with* возвращают клон)	✅	✅	✅	✅	✅	✅
Строгая валидация метода и заголовков (fail-loud, RFC 7230)	✅	❌	✅	✅	✅	✅
Исключения не раскрывают значение заголовка (безопасно для логов с ПД)	✅	❌	❌	❌	✅	❌
Минимум зависимостей (только PSR-контракты, без polyfill/getallheaders)	✅	✅	❌	❌	❌	✅
Нормализация URI по RFC 3986 (порт по умолчанию опускается)	✅	✅	✅	✅	✅	✅
Всего	🏆 5	3	3	3	4	4

2. Безопасность и корректность

Свойство	🏆 CloudCastle	nyholm	guzzle	laminas	slim	httpsoft
Валидация имён заголовков (нет инъекции CRLF)	✅	❌	✅	✅	✅	✅
Валидация значений заголовков (нет управляющих символов)	✅	❌	✅	✅	✅	✅
Исключения не раскрывают значение заголовка (нет утечки ПД в логи)	✅	❌	❌	❌	✅	❌
Валидация метода (token RFC 7230)	✅	❌	✅	✅	✅	✅
Проверка диапазона порта URI (1–65535)	✅	✅	✅	✅	✅	✅
Всего	🏆 5	1	4	4	🏆 5	4

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

разбор URI + сборка GET-запроса с заголовками, 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
🏆 CloudCastle	6 019,8	быстрейшее среди библиотек
nyholm	6 206,6	аналог
httpsoft	8 395	аналог
laminas	15 143,4	аналог
guzzle	19 987,7	аналог
slim	20 225,8	аналог

4. Потребление памяти

Фактическая память 100 000 удержанных объектов-запросов (изолированный процесс).

Решение	Пиковая память (KB)	Итог
🏆 nyholm	242 196	легчайшее среди библиотек
CloudCastle	242 198	аналог
guzzle	242 410	аналог
httpsoft	245 352	аналог
slim	350 930	аналог
laminas	352 301	аналог

О памяти честно. Замер — фактически занятая память (memory_get_usage) при удержании 100 000 объектов-запросов в изолированном процессе (не производной строки — та одинакова у всех и мерила бы лишь шум). CloudCastle практически вровень с самым лёгким nyholm/psr7 (разница ~2 КБ из 242 МБ — в пределах шума) и на ~45% легче laminas/slim. Память — не та ось, где пакет уступает; при этом он первый по скорости, функционалу и безопасности.

Плюсы, минусы и когда применять

Сильные стороны:

Функционал = объединение аналогов — единственный набирает все пункты матрицы (неизменяемость, строгая валидация, безопасные исключения, минимум зависимостей, нормализация URI по RFC 3986).
Быстрейшая сборка запроса среди PSR-7 реализаций — быстрее nyholm, httpsoft, laminas, guzzle на разборе URI + сборке запроса с заголовками.
Безопасность — валидация имён/значений заголовков (нет CRLF-инъекции), проверка метода и диапазона порта; исключения не раскрывают значение заголовка — нет утечки секретов/ПД в логи (у guzzle/laminas/httpsoft значение попадает в текст исключения). nyholm вовсе не валидирует заголовки.
Память — практически вровень с самым лёгким nyholm, легче большинства.
Минимум зависимостей — только PSR-контракты, без polyfill/getallheaders.

Слабые стороны (честно):

Только исходящий запрос — реализованы RequestInterface и фабрики; серверный ServerRequest, загрузка файлов и cookie — вне области (для них берите полный laminas-diactoros/guzzle).
Экосистема — у guzzle/laminas шире набор готовых middleware и адаптеров.

Когда применять. Как лёгкий, быстрый и безопасный PSR-7/17 слой для исходящих HTTP-запросов в клиентах и интеграциях — особенно там, где важна защита от утечки данных в логи и минимум зависимостей. Для серверной стороны (обработка входящих запросов, загрузки, cookie) берите полноценный laminas-diactoros или guzzle.

Разработка

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

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

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

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

Лицензия