README

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

CloudCastle Curl

Самый полнофункциональный HTTP-клиент для PHP 8.1+ на базе cURL: текучий API и PSR-18, промисы, параллельный пул curl_multi с окном конкурентности и неблокирующим tick() для event loop, HTTP/2 server push, общий пул соединений curl_share, cookie (RFC 6265), потоковые загрузка и выгрузка с докачкой и сегментной параллельной загрузкой, ретраи с backoff и Retry-After, HTTP-кэш (RFC 9111), rate limit, ротация прокси, SSE, HAR, защита от SSRF на каждом хопе, маскирование секретов, mTLS и пиннинг, а также транспорт без ext-curl. Выигрывает у Guzzle, Symfony HttpClient, Buzz, php-http, php-curl-class и Requests по функционалу, скорости, памяти и безопасности — см. сравнение.

Установка

composer require cloud-castle/curl

Требуется PHP 8.1+ и расширения ext-curl, ext-json, ext-mbstring (ext-dom/ext-libxml — для разбора XML). Зависимости — только пакеты экосистемы cloud-castle (парсеры JSON/XML/YAML/NEON) и интерфейсы PSR (psr/http-client, psr/http-factory, psr/http-message, psr/log, psr/simple-cache).

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

<?php

use CloudCastle\Curl\Curl;

// Разовый запрос через статический фасад.
$response = Curl::request('https://api.example.com/users')->get();

echo $response->status();                 // 200
echo $response->header('Content-Type');   // application/json
$data = $response->json();                // разбор тела как JSON

use CloudCastle\Curl\Client;

// Клиент со стандартным конвейером (повторы → перенаправления → SSRF),
// базовым URI и шаблонами URI (RFC 6570).
$client = Client::create()->withBaseUri('https://api.example.com/v2/');

$response = $client->request('orders/{id}', ['id' => 42])
    ->withBearerToken('secret-token')
    ->withJson(['status' => 'paid'])
    ->withTimeout(10.0)
    ->withRetries(3)
    ->post();

use CloudCastle\Curl\Curl;

// Параллельная загрузка с окном конкурентности; результаты — по мере готовности.
$pool = Curl::pool(concurrency: 20);

foreach ($urls as $key => $url) {
    $pool->add($key, Curl::request($url)->build());
}

foreach ($pool->stream() as $key => $result) {
    echo $key, ': ', $result->isFulfilled() ? $result->responseOrThrow()->status() : 'ошибка', PHP_EOL;
}

use CloudCastle\Curl\Promise;
use CloudCastle\Curl\Psr18\Psr18Client;

// Промисы.
$users = $client->sendAsync($client->request('users')->build())
    ->then(static fn ($response) => $response->json());
$all = Promise::all(['users' => $users])->wait();

// PSR-18 для библиотек, ожидающих ClientInterface (фабрики PSR-17 находятся автоматически).
$psr18 = Psr18Client::discover($client);

Возможности

Запросы и API

Текучий конструктор: метод, заголовки, query, тело (raw/JSON/форма/multipart), аутентификация (Basic, Bearer, Digest, NTLM, WSSE) и настройки в одном выражении.
PSR-18 клиент, промисы (then/wait/all/settle/any), базовый URI, шаблоны URI (RFC 6570), IDN-домены (punycode), настройки по шаблону URL.
Разбор ответа: json(), xml(), yaml(), neon() и parsed() с автоопределением формата; исключения на 4xx/5xx по желанию.

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

Пул curl_multi с окном конкурентности, выдачей результатов генератором, неблокирующим tick()/isIdle() для ReactPHP, Revolt/Amp, Swoole.
HTTP/2 и HTTP/3, мультиплексирование, HTTP/2 server push, curl_share (общий кэш DNS, TLS-сессий, cookie и соединений), тонкая настройка TCP/буферов.

Передача данных

Потоковые загрузка в файл и выгрузка из файла без роста памяти, обработчик фрагментов, докачка (Range), сегментная параллельная загрузка, прогресс.
multipart/form-data: несколько файлов, files[], MIME/имя, отправка из памяти.
Server-Sent Events, лимит размера ответа, проверка заголовков до приёма тела, досрочное прерывание, ограничение скорости, распаковка gzip/deflate/br.

Надёжность

Ретраи с экспоненциальным backoff, джиттером и Retry-After; безопасные перенаправления с историей; HTTP-кэш (RFC 9111, PSR-16); rate limit; ротация прокси (HTTP/SOCKS, no_proxy); транспорт на потоках PHP без ext-curl.

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

Защита от SSRF с повторной проверкой на каждом хопе, маскирование секретов в ошибках, логах и экспорте, строгий TLS по умолчанию, минимальная версия TLS, mTLS, пиннинг открытого ключа, снятие учётных данных при смене хоста.

Диагностика и тестирование

Тайминги (DNS/TCP/TLS/TTFB), логирование PSR-3, история запросов, хуки, экспорт/воспроизведение HAR, verbose-журнал, цепочка сертификатов, экспорт в команду curl, мок-обработчик для тестов без сети.

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

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

Все таблицы ниже сгенерированы автоматически (composer docs:build) из честных сравнительных тестов benchmarks/compare.php: одинаковые операции для всех библиотек через реальную сеть (локальный сервер), безопасность проверяется атакующими запросами, метрики качества вычисляются по исходному коду установленных пакетов.

Окружение: PHP 8.3.32, libcurl 8.14.1, лучший результат из нескольких прогонов.

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

Возможность	CloudCastle	Guzzle	Symfony	Buzz	php-http	php-curl-class	Requests	ext-curl¹	🏆 Победитель
Текучий построитель запроса	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
Клиент PSR-18	✅	✅	✅	✅	✅	❌	❌	❌	поровну: 5
Промисы / асинхронный API	✅	✅	✅	❌	✅	❌	❌	❌	поровну: 4
Параллельные запросы (curl_multi)	✅	✅	✅	✅	✅	✅	✅	✅	поровну: 7
Окно конкурентности	✅	✅	✅	❌	❌	✅	❌	❌	поровну: 4
Результаты пула по мере готовности	✅	✅	✅	✅	❌	✅	❌	❌	поровну: 5
curl_share: общий DNS/TLS/соединения	✅	❌	✅	❌	❌	❌	❌	✅	поровну: 2
Middleware / декораторы клиента	✅	✅	✅	✅	❌	❌	❌	❌	поровну: 4
Хуки до/после запроса	✅	✅	❌	❌	❌	✅	✅	❌	поровну: 4
Повтор запросов	✅	✅	✅	❌	❌	✅	❌	❌	поровну: 4
Экспоненциальный backoff с джиттером	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Учёт Retry-After	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Перенаправления	✅	✅	✅	✅	❌	✅	✅	✅	поровну: 6
История перенаправлений	✅	✅	❌	❌	❌	❌	✅	❌	поровну: 3
Хранилище cookie (RFC 6265)	✅	✅	❌	✅	❌	✅	✅	✅	поровну: 5
Сохранение cookie в файл	✅	✅	❌	❌	❌	✅	❌	✅	поровну: 3
Формат cookies.txt (Netscape)	✅	❌	❌	❌	❌	✅	❌	✅	поровну: 2
Потоковая загрузка в файл	✅	✅	✅	❌	❌	✅	✅	✅	поровну: 5
Обработчик фрагментов тела	✅	✅	✅	❌	❌	❌	✅	✅	поровну: 4
Потоковая выгрузка файла	✅	✅	✅	❌	❌	✅	❌	✅	поровну: 4
multipart/form-data	✅	✅	✅	✅	❌	✅	❌	✅	поровну: 5
Докачка (Range)	✅	❌	❌	❌	❌	✅	❌	✅	поровну: 2
Сегментная параллельная загрузка	✅	❌	❌	❌	❌	✅	❌	❌	поровну: 2
Прогресс передачи	✅	✅	✅	❌	❌	✅	✅	✅	поровну: 5
Лимит размера ответа	✅	❌	❌	❌	❌	❌	✅	✅	поровну: 2
HTTP/2	✅	✅	✅	✅	✅	✅	❌	✅	поровну: 6
HTTP/2 server push	✅	❌	✅	✅	❌	❌	❌	❌	поровну: 3
HTTP/3	✅	❌	❌	❌	❌	❌	❌	✅	CloudCastle
HTTP-прокси	✅	✅	✅	✅	❌	✅	✅	✅	поровну: 6
SOCKS-прокси	✅	✅	✅	❌	❌	✅	❌	✅	поровну: 4
Исключения из прокси (no_proxy)	✅	✅	✅	❌	❌	❌	❌	✅	поровну: 3
Ротация прокси	✅	❌	❌	❌	❌	✅	❌	❌	поровну: 2
Ограничение частоты запросов	✅	❌	✅	❌	❌	✅	❌	❌	поровну: 3
mTLS (клиентский сертификат)	✅	✅	✅	❌	❌	✅	❌	✅	поровну: 4
Пиннинг открытого ключа	✅	❌	✅	❌	❌	❌	❌	✅	поровну: 2
Защита от SSRF	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Маскирование секретов в логах и ошибках	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
Basic-аутентификация	✅	✅	✅	✅	❌	✅	✅	✅	поровну: 6
Bearer-токен	✅	❌	✅	✅	❌	❌	❌	❌	поровну: 3
Digest-аутентификация	✅	✅	❌	✅	❌	✅	❌	✅	поровну: 4
NTLM-аутентификация	✅	✅	✅	❌	❌	❌	❌	✅	поровну: 3
WSSE-аутентификация	✅	❌	❌	✅	❌	❌	❌	❌	поровну: 2
Базовый URI	✅	✅	✅	❌	❌	❌	✅	❌	поровну: 4
Шаблоны URI (RFC 6570)	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
IDN-домены (punycode)	✅	✅	✅	❌	❌	❌	✅	❌	поровну: 4
Настройки по шаблону URL (скоупинг)	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
HTTP-кэш (RFC 9111)	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Server-Sent Events	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Воспроизведение HAR	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Экспорт HAR	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
История запросов	✅	✅	✅	✅	❌	❌	❌	❌	поровну: 4
Логирование PSR-3	✅	✅	✅	✅	❌	❌	❌	❌	поровну: 4
Тайминги (DNS/TLS/TTFB)	✅	✅	✅	❌	❌	✅	❌	✅	поровну: 4
Мок-обработчик для тестов	✅	✅	✅	❌	❌	❌	❌	❌	поровну: 3
Экспорт в команду curl	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Транспорт без ext-curl	✅	✅	✅	✅	❌	❌	✅	❌	поровну: 5
Распаковка gzip/deflate/br	✅	✅	✅	❌	❌	✅	✅	✅	поровну: 5
Разбор JSON-ответа	✅	❌	✅	❌	❌	✅	✅	❌	поровну: 4
Разбор XML-ответа	✅	❌	❌	❌	❌	✅	❌	❌	поровну: 2
Разбор YAML/NEON-ответа	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
Исключения на 4xx/5xx	✅	✅	✅	❌	❌	❌	✅	❌	поровну: 4
Проброс опций cURL	✅	✅	✅	✅	✅	✅	✅	✅	поровну: 7
Фиксация DNS (resolve)	✅	❌	✅	❌	❌	❌	❌	✅	поровну: 2
Выбор IPv4/IPv6	✅	✅	❌	❌	❌	❌	❌	✅	поровну: 2
Привязка к сетевому интерфейсу	✅	❌	✅	❌	❌	❌	❌	✅	поровну: 2
Проверка заголовков до приёма тела	✅	✅	✅	❌	❌	❌	❌	❌	поровну: 3
Досрочное прерывание приёма	✅	✅	✅	❌	❌	❌	❌	❌	поровну: 3
Минимальная версия TLS	✅	✅	✅	❌	❌	❌	❌	✅	поровну: 3
Цепочка сертификатов сервера	✅	❌	✅	❌	❌	❌	❌	✅	поровну: 2
Отладочный журнал обмена (verbose)	✅	✅	❌	❌	❌	✅	❌	✅	поровну: 3
Таймаут простоя соединения	✅	✅	✅	❌	❌	❌	❌	❌	поровну: 3
Управление Expect: 100-continue	✅	✅	❌	❌	❌	❌	❌	✅	поровну: 2
Ограничение скорости передачи	✅	❌	❌	❌	❌	❌	❌	✅	CloudCastle
Задержка перед отправкой	✅	✅	❌	❌	❌	❌	❌	❌	поровну: 2
Неблокирующий шаг для event loop	✅	✅	✅	❌	❌	❌	❌	✅	поровну: 3
Всего	75/75	44/75	53/75	18/75	5/75	29/75	18/75	35/75	🏆 CloudCastle

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

Свойство	CloudCastle	Guzzle	Symfony	Buzz	php-http	php-curl-class	Requests	ext-curl¹	🏆 Победитель
Проверка TLS включена по умолчанию	✅	✅	✅	✅	✅	✅	✅	✅	поровну: 7
Блокировка SSRF по умолчанию (тест)	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
Authorization снимается при смене хоста (тест)	✅	✅	✅	✅	✅	✅	❌	✅	поровну: 6
Пароль из URL не попадает в ошибки (тест)	✅	✅	❌	✅	✅	✅	✅	✅	поровну: 6
Защита от CRLF-инъекции в заголовках (тест)	✅	✅	✅	✅	✅	❌	❌	❌	поровну: 5
Лимит размера ответа по умолчанию	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
Повторная проверка SSRF на каждом хопе	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
Маскирование секретов в логах и экспорте	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
Пиннинг открытого ключа	✅	❌	✅	❌	❌	❌	❌	✅	поровну: 2
Всего	9/9	4/9	5/9	4/9	4/9	3/9	2/9	4/9	🏆 CloudCastle

(тест) — свойство проверено атакующим запросом при каждом прогоне сравнения.

2.1. Стандарты безопасности

Стандарт	CloudCastle	Guzzle	Symfony	Buzz	php-http	php-curl-class	Requests	ext-curl¹	🏆 Победитель
Политика раскрытия уязвимостей (SECURITY.md)	✅	✅	✅	❌	❌	✅	✅	❌	поровну: 5
Бюллетени безопасности Packagist/FriendsOfPHP	✅	✅	✅	✅	✅	✅	✅	❌	поровну: 7
CWE-295: строгая проверка сертификата	✅	✅	✅	✅	✅	✅	✅	✅	поровну: 7
CWE-918: защита от SSRF	✅	❌	✅	❌	❌	❌	❌	❌	поровну: 2
CWE-113: нейтрализация CRLF в заголовках	✅	✅	✅	✅	✅	❌	❌	❌	поровну: 5
CWE-532: секреты не попадают в логи	✅	❌	❌	❌	❌	❌	❌	❌	CloudCastle
CWE-400: ограничение потребления ресурсов	✅	❌	❌	❌	❌	❌	✅	✅	поровну: 2
CWE-200: учётные данные не уходят на чужой хост	✅	✅	✅	✅	✅	✅	❌	✅	поровну: 6
Всего	8/8	5/8	6/8	4/8	4/8	4/8	4/8	3/8	🏆 CloudCastle

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

Сценарий	CloudCastle	Guzzle	Symfony	Buzz	php-http	php-curl-class	Requests	ext-curl¹	🏆 Победитель
Последовательные GET, 300 запросов (минимум из 7), мс	314.5	446	399.5	378.8	375.2	334.3	422.9	274.2	🏆 CloudCastle
POST JSON, 300 запросов (минимум из 7), мс	354.6	526	392.7	332.7	369.2	411.9	413.4	284.2	🏆 Buzz
Параллельная пачка из 24 запросов, задержка сервера 100 мс, мс	106.1	110.3	409.6	110.5	107.8	113.2	110	107.3	🏆 CloudCastle, php-http (в пределах 3%)
Загрузка файла 16 МБ на диск, мс	69.3	69.3	126.8	145.1	113.8	73.6	213.8	66.6	🏆 CloudCastle, Guzzle (в пределах 3%)

Время в пределах 3% от лучшего считается равным: это разброс между повторными прогонами на одной машине, и такие результаты делят победу.

4. Память и утечки

Сценарий	CloudCastle	Guzzle	Symfony	Buzz	php-http	php-curl-class	Requests	ext-curl¹	🏆 Победитель
Пиковая память при загрузке 16 МБ (изолированный процесс, после прогрева), KB	13	32	2 218	15 377	1 043	11	14	2	🏆 php-curl-class
Рост памяти за 600 запросов после прогрева (утечки), KB	0	0	0	0	0	0	0	0	поровну: 7

5. Качество кода

Метрика	CloudCastle	Guzzle	Symfony	Buzz	php-http	php-curl-class	Requests	🏆 Победитель
Файлы с declare(strict_types=1), % (больше — лучше)	100	0	0	97.1	100	100	0	поровну: 3
Финальные классы, % (больше — лучше)	96	38.5	58.3	6.7	0	0	75	🏆 CloudCastle
Методы с типом возврата, % (больше — лучше)	98.4	84.2	82.8	79.1	70.4	1.6	0	🏆 CloudCastle
Сторонние runtime-зависимости (меньше — лучше)	0	4	4	2	4	0	0	поровну: 3
Минимальная версия PHP	8.1	7.2	8.1	7.1	8.1	8.0	5.6	—

¹ ext-curl — нативные вызовы без полноты решения; показан для контекста и не претендует на победу.

Плюсы и минусы (честно)

Плюсы

Функционал — надмножество всех сравниваемых аналогов: то, что у них разнесено по пакетам и расширениям (PSR-18, промисы, кэш, SSE, HAR, rate limit, event loop), здесь собрано за одним API.
Среди победителей в каждом сценарии производительности (последовательные и параллельные запросы) и единоличный лидер загрузки файлов: тело пишет сам cURL, без копирования в PHP. Утечек нет — это проверяют автоматические тесты.
Безопасность по умолчанию: SSRF-защита на каждом хопе, маскирование секретов, строгий TLS — все проверки из таблицы безопасности пройдены.
Минимум зависимостей: только cloud-castle и интерфейсы PSR.
Качество кода: 100% покрытие, MSI 100%, PHPStan max, Psalm errorLevel 1, PHPMD и PHPCS без замечаний, declare(strict_types=1) и final везде.

Минусы

Пакет моложе и менее распространён, чем Guzzle и Symfony HttpClient: меньше звёзд и установок, меньше готовых сторонних интеграций.
Пиковая память при загрузке файла на ~2 КБ выше, чем у php-curl-class: ответ хранит полные сведения cURL, тайминги и разобранные заголовки. Это плата за функциональность; тело при этом не буферизуется, и память не растёт с размером файла.

Разработка

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

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

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

Wiki (возможности, архитектура, сравнения, диаграммы): wiki/Home.md
История изменений: CHANGELOG.md
Переход между версиями: UPGRADING.md
Как внести вклад: CONTRIBUTING.md
Политика безопасности: SECURITY.md

Лицензия