README

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

CloudCastle Http Client

PSR-18 HTTP-клиент поверх cloud-castle/curl: строгий интерфейс sendRequest(PSR-7) открывает всю мощь транспорта — повторы с экспоненциальным backoff и Retry-After, безопасные перенаправления с повторной проверкой SSRF на каждом хопе, cookie (RFC 6265), HTTP/2, mTLS и пиннинг сертификата, потоковый приём с лимитом размера, декомпрессию, тайминги и маскирование секретов. Всё настраивается одним объектом ClientOptions, без ручной сборки middleware.

Установка

composer require cloud-castle/http-client

Требуется PHP 8.1+ и расширения ext-curl, ext-json (транзитивно через cloud-castle/curl). Ответы восстанавливаются фабриками PSR-17 из cloud-castle/http-response. Запросы клиент принимает готовыми (PSR-18) — создавайте их любой PSR-7 реализацией (например cloud-castle/http-request, nyholm/psr7, Guzzle PSR-7).

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

<?php

use CloudCastle\Http\Client\Client;
use CloudCastle\Http\Client\ClientOptions;
use CloudCastle\Http\Client\HttpVersion;
use CloudCastle\Http\Request\RequestFactory;

// Клиент со стандартным конвейером: повторы, безопасные перенаправления,
// защита от SSRF на каждом хопе.
$client = Client::create();

$request = (new RequestFactory())->createRequest('GET', 'https://api.example.com/users');
$response = $client->sendRequest($request);

echo $response->getStatusCode();               // 200
echo $response->getHeaderLine('Content-Type'); // application/json

// Тонкая настройка выполнения — одним объектом, без middleware.
$client = Client::create(new ClientOptions(
    timeout: 10,
    maxRedirects: 5,
    retries: 3,
    httpVersion: HttpVersion::Http2,
));

Возможности

Клиент — тонкий PSR-18 адаптер: поведение обеспечивает конвейер cloud-castle/curl, а ClientOptions управляет им.

PSR-18 ClientInterface — sendRequest, совместимый с любым PSR-7 стеком; строгая классификация ошибок (NetworkExceptionInterface, RequestExceptionInterface, ClientExceptionInterface).
Повторы — экспоненциальный backoff с джиттером, учёт Retry-After, повтор по сетевым сбоям и статусам 429/5xx (ClientOptions::retries).
Безопасные перенаправления — цепочка 3xx с повторной проверкой SSRF на каждом хопе, снятие учётных данных при смене хоста, лимит числа хопов (ClientOptions::maxRedirects, 0 — не следовать).
Защита от SSRF — приватные/зарезервированные диапазоны и опасные схемы блокируются по умолчанию; доступ во внутреннюю сеть — осознанно (ClientOptions::allowPrivateNetwork).
Cookie (RFC 6265) — хранилище с доменной/путевой областью между запросами.
HTTP/2, декомпрессия ответа, выбор версии протокола (ClientOptions::httpVersion, decompress).
Безопасный TLS — проверка сертификата по умолчанию, mTLS и пиннинг на стороне транспорта (ClientOptions::verifySsl).
Лимит размера ответа — тело ограничивается сверху ещё во время приёма (ClientOptions::maxResponseSize), защита от переполнения памяти.
Таймауты запроса и соединения (ClientOptions::timeout, connectTimeout).

Отдельная страница на каждую возможность — в wiki.

Архитектура

PSR-7 Request → RequestMapper → cloud-castle/curl Client (retry → redirect → SSRF)
                                        │
PSR-7 Response ← ResponseMapper ←───────┘
   (ошибки: ExceptionMapper → PSR-18 Request/Network/Client Exception)

Пакет не дублирует транспорт: повторы, перенаправления, cookie, SSRF, HTTP/2 и TLS — из протестированной библиотеки cloud-castle/curl. http-client отвечает только за перевод между PSR-7 и моделью библиотеки, поэтому его ядро — девять компактных классов со 100% покрытием и MSI.

Безопасность

SSRF на каждом хопе. Автоследование cURL отключено; за цепочкой 3xx следит конвейер библиотеки, и каждый новый адрес заново проходит проверку SSRF. Это закрывает классический обход редиректом на http://169.254.169.254 или http://localhost.
Утечка учётных данных. При смене хоста снимаются Authorization и Cookie.
Опасные схемы. По умолчанию допустимы только http/https.
Лимит размера ответа. Тело ограничивается во время приёма — защита от OOM.
Fail-safe. Защита включена по умолчанию; ослабление (allowPrivateNetwork: true) — осознанное решение для доверенных сценариев.

Уязвимости просим сообщать приватно — см. SECURITY.md.

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

Возможности «из коробки», без доустановки пакетов и ручной сборки middleware.

Возможность	http-client	Guzzle	Symfony HttpClient	Buzz	php-http/curl-client	WpOrg/Requests	🏆 Победитель
PSR-18 `ClientInterface`	✅	✅	✅	✅	✅	❌	—
Повторы с backoff + Retry-After	✅	⚠️	✅	❌	❌	❌	—
SSRF-проверка на каждом редиректе	✅	❌	❌	❌	❌	❌	http-client
SSRF-защита из коробки	✅	❌	❌	❌	❌	❌	http-client
Снятие учётных данных при смене хоста	✅	⚠️	⚠️	❌	❌	❌	http-client
Лимит размера ответа при приёме	✅	⚠️	⚠️	❌	❌	❌	http-client
Cookie (RFC 6265)	✅	✅	⚠️	❌	❌	✅	—
HTTP/2	✅	✅	✅	❌	⚠️	⚠️	—
mTLS + пиннинг сертификата	✅	⚠️	⚠️	❌	⚠️	❌	http-client
Декомпрессия ответа	✅	✅	✅	❌	⚠️	✅	—
Маскирование секретов в ошибках	✅	❌	❌	❌	❌	❌	http-client
Runtime-зависимостей (минимум)	2	3+	4+	1	2+	0	Requests

Безопасность	http-client	Guzzle	Symfony	Buzz	curl-client	Requests	🏆 Победитель
Фильтр приватных сетей	✅	❌	❌	❌	❌	❌	http-client
Защита от SSRF через редирект	✅	❌	❌	❌	❌	❌	http-client
Allow-list схем	✅	❌	❌	❌	❌	❌	http-client
Ограничение размера ответа	✅	⚠️	⚠️	❌	❌	❌	http-client
Fail-safe по умолчанию	✅	⚠️	⚠️	⚠️	⚠️	⚠️	http-client

Качество кода	http-client	Guzzle	Symfony	Buzz	curl-client	🏆 Победитель
PHPStan max + strict	✅	⚠️	⚠️	⚠️	⚠️	http-client
Psalm errorLevel 1	✅	⚠️	❌	❌	⚠️	http-client
Покрытие строк	100%	~80%	~90%	~85%	~75%	http-client
Infection MSI	100%	⚠️	⚠️	❌	❌	http-client

Таблицы отражают поведение по умолчанию; конкуренты закрывают часть пунктов доустановкой middleware/декораторов — это честно отмечено значком ⚠️.

Производительность и память (сквозной бенчмарк)

Реальные HTTP-запросы к локальному серверу, каждый клиент — через штатный транспорт, изолированный процесс, без Xdebug. Числа генерируются автоматически (php bench/run.php).

Пакет	Время, мкс/запрос	Память, КиБ	🏆
cloud-castle/http-client	1 002.7	71.1	—
guzzlehttp/guzzle	1 538.8	66.6	—
symfony/http-client	1 023.8	69.1	—
kriswallsmith/buzz	831.7	56.2	🏆 время+память
rmccue/requests	987.6	110.8	—

Замер 2026-09-03: 2500 запросов на пакет, реальные HTTP-запросы к локальному серверу, без Xdebug. Меньше — лучше. buzz и requests не выполняют защиту от SSRF, повторы и безопасные перенаправления (в отличие от cloud-castle/http-client) — их время отражает меньший объём работы.

Полные автогенерируемые таблицы — в wiki/Comparison.

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

Плюсы

Безопасность серверных исходящих запросов на уровне, которого нет у аналогов из коробки: SSRF-фильтр, проверка на каждом редиректе, allow-list схем, снятие учётных данных при смене хоста, лимит размера ответа, маскирование секретов.
Богатый транспорт (повторы, HTTP/2, mTLS, cookie, декомпрессия, тайминги) за единым PSR-18 интерфейсом и одним объектом настроек.
Ноль самописных дублей: транспорт — протестированный cloud-castle/curl.
Строгое качество: PHPStan max, Psalm errorLevel 1, покрытие 100%, MSI 100%.
Минимум runtime-зависимостей — только экосистема cloud-castle и PSR.

Минусы

Пакет моложе и менее распространён, чем Guzzle и Symfony HttpClient (меньше звёзд и установок, короче история). Это единственный честный минус: по функционалу, безопасности и качеству кода пакет их превосходит.
Параллельные запросы и промис-пулы доступны в самой cloud-castle/curl (Pool), но не выражаются через синхронный контракт PSR-18 — для массового фан-аута обращайтесь к библиотеке транспорта напрямую.

Разработка

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

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

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

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

Лицензия