README

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

CloudCastle Curl

Полнофункциональная объектная обёртка cURL для PHP 8.1+. Текучий API, параллельный пул на curl_multi с окном конкурентности, общий пул соединений curl_share, cookie (RFC 6265), потоковая загрузка/выгрузка с докачкой и прогрессом, ретраи с экспоненциальным backoff и Retry-After, безопасные перенаправления с повторной проверкой SSRF на каждом хопе, HTTP/2, mTLS и пиннинг сертификата, маскирование секретов, тайминги, мок-обработчик и экспорт запроса в команду curl, разбор ответа в JSON/XML/YAML/NEON. Сетевой слой требует только ext-curl.

Установка

composer require cloud-castle/curl

Требуется PHP 8.1+ и расширения ext-curl, ext-json (а также ext-dom/ ext-libxml для разбора XML). Из внешних runtime-зависимостей — парсеры экосистемы cloud-castle (parser-json/xml/yaml/neon), они ставятся автоматически.

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

<?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).
$client = Client::create();

$response = $client->request('https://api.example.com/orders')
    ->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->send() as $key => $result) {
    if ($result->isFulfilled()) {
        echo $key, ': ', $result->responseOrThrow()->status(), PHP_EOL;
    }
}

Возможности

Текучий конструктор запроса — метод, заголовки, query, тело (raw/JSON/форма/multipart), аутентификация, настройки в одном выражении.
Параллельный пул на curl_multi с окном конкурентности и независимыми результатами (сбой одного запроса не рушит остальные).
curl_share — общий кэш DNS, TLS-сессий, cookie и соединений между запросами.
Cookie (RFC 6265) — хранилище с доменной и путевой областью, Max-Age/ Expires, Secure/HttpOnly, сохранение в файл.
Потоковые загрузка и выгрузка — запись ответа в файл или обработчик чанков (память не растёт), докачка с Range, обратный вызов прогресса.
Загрузка файлов — multipart/form-data с полями и файлами: несколько файлов, несколько файлов в одном поле (files[]), управление MIME-типом и именем, отправка из памяти без временного файла.
Разбор ответа — тело как строка (Stringable) или разбор в структуру: json(), xml(), yaml(), neon() и parsed() с автоопределением формата по Content-Type и содержимому (парсеры экосистемы cloud-castle).
Ретраи — экспоненциальный backoff с джиттером, учёт Retry-After, повтор по кодам и по сетевым сбоям/таймаутам.
Безопасные перенаправления — 301/302/303 → GET, снятие учётных данных при смене хоста, повторная проверка SSRF на каждом хопе.
Безопасность — защита от SSRF (allow-list схем, блокировка приватных диапазонов), маскирование секретов в ошибках и экспорте, безопасный TLS по умолчанию, mTLS и пиннинг сертификата, лимит размера ответа.
Диагностика — тайминги (curl_getinfo), экспорт запроса в команду curl, мок-обработчик для тестов без сети.

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

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

Полные автогенерируемые таблицы (функционал, производительность, память, безопасность, качество кода) с графой 🏆 Победитель — в wiki/Comparison. Сравниваются Guzzle, Symfony HttpClient, Buzz, PHP-HTTP cURL client, а также прямое использование расширения cURL.

CloudCastle Curl — суперсет их возможностей в одном пакете без тяжёлых зависимостей: пул + share + cookie + докачка + SSRF-защита + экспорт команды — из коробки и за единым текучим API.

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

Плюсы

Богатейший функционал в классе: то, что у аналогов разнесено по пакетам и расширениям, здесь собрано за одним API.
Безопасность по умолчанию: SSRF-защита на каждом хопе, маскирование секретов, строгий TLS.
Лёгкое ядро: из внешних runtime-зависимостей — только парсеры экосистемы cloud-castle (parser-json/xml/yaml/neon) для разбора тела ответа; сетевой слой опирается лишь на ext-curl.
Низкое потребление памяти: потоковые загрузка/выгрузка не буферизуют тело целиком; размер ответа ограничен сверху ещё во время приёма.
100% покрытие строк, MSI 100%, полный статический анализ (PHPStan max, Psalm errorLevel 1).

Минусы

Пакет моложе и менее распространён, чем Guzzle и Symfony HttpClient (меньше звёзд/установок и меньше готовых сторонних интеграций). Это единственный честный минус: по функционалу, производительности, безопасности и качеству кода пакет их превосходит.
Не реализует PSR-18 напрямую (это объектная обёртка над cURL со своим API); если нужен строгий PSR-18 поверх PSR-7, используйте cloud-castle/http-client.

Разработка

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

Лицензия

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

cloud-castle / curl

Maintainers

Package info

Statistics

Security