PHPackages waffle-commons/http-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. waffle-commons/http-client ActiveLibrary[HTTP & Networking](/categories/http) waffle-commons/http-client ========================== HTTP Client component for Waffle framework. 0.1.0-beta5(2w ago)128[3 PRs](https://github.com/waffle-commons/http-client/pulls)1MITPHPPHP ^8.5CI passing Since May 25Pushed 2w agoCompare [ Source](https://github.com/waffle-commons/http-client)[ Packagist](https://packagist.org/packages/waffle-commons/http-client)[ RSS](/packages/waffle-commons-http-client/feed)WikiDiscussions main Synced 1w ago READMEChangelog (6)Dependencies (34)Versions (16)Used By (1) [![Discord](https://camo.githubusercontent.com/b30f41baece56d71f7f496f7e39fd33a2a096221c66c648b350dd4fe14276c2e/68747470733a2f2f696d672e736869656c64732e696f2f646973636f72642f3735353238383030313539323033333339313f6c6f676f3d646973636f7264)](https://discord.gg/eKgywnfXr2)[![PHP Version Require](https://camo.githubusercontent.com/4daab6837a55b9e47af74038bf828828669bbc302f53e2b9e26001b45bcb5517/687474703a2f2f706f7365722e707567782e6f72672f776166666c652d636f6d6d6f6e732f687474702d636c69656e742f726571756972652f706870)](https://packagist.org/packages/waffle-commons/http-client)[![PHP CI](https://github.com/waffle-commons/http-client/actions/workflows/main.yml/badge.svg)](https://github.com/waffle-commons/http-client/actions/workflows/main.yml)[![codecov](https://camo.githubusercontent.com/201eae80c155fb3954cde2781173c4b3b63824d561c661192e03304ecf255458/68747470733a2f2f636f6465636f762e696f2f67682f776166666c652d636f6d6d6f6e732f687474702d636c69656e742f67726170682f62616467652e737667)](https://codecov.io/gh/waffle-commons/http-client)[![Latest Stable Version](https://camo.githubusercontent.com/ff8978dad5328d02b562ee2e7e04ffc3720151e136796b2065b5bf76ebc36bc8/687474703a2f2f706f7365722e707567782e6f72672f776166666c652d636f6d6d6f6e732f687474702d636c69656e742f76)](https://packagist.org/packages/waffle-commons/http-client)[![Latest Unstable Version](https://camo.githubusercontent.com/3fbba68457b6d5325fc732723ccdbdb9f01525dd804802f7c39213b2c855a37b/687474703a2f2f706f7365722e707567782e6f72672f776166666c652d636f6d6d6f6e732f687474702d636c69656e742f762f756e737461626c65)](https://packagist.org/packages/waffle-commons/http-client)[![Total Downloads](https://camo.githubusercontent.com/534ed2763dba5fec5613dcc98aef634e3daac8f64783ea56ad238202e0b0cfcb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f776166666c652d636f6d6d6f6e732f687474702d636c69656e742e737667)](https://packagist.org/packages/waffle-commons/http-client)[![Packagist License](https://camo.githubusercontent.com/8cadae340e85b8af39117064652cb978b69cdb3944d67f3a9402d0c248c852a0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f776166666c652d636f6d6d6f6e732f687474702d636c69656e74)](https://github.com/waffle-commons/http-client/blob/main/LICENSE.md) Waffle HTTP Client Component ============================ [](#waffle-http-client-component) > **Release:** `0.1.0-beta5` | [`CHANGELOG.md`](./CHANGELOG.md)**PSR Compliance:** PSR-18 (`Psr\Http\Client\ClientInterface`), PSR-7 messages, PSR-17 factories A high-performance PSR-18 HTTP client tuned for FrankenPHP resident-worker proxying. Holds a single persistent `\CurlHandle` **plus** a `\CurlMultiHandle`, reused via `curl_reset()` across every `sendRequest()` so libcurl's DNS cache and keep-alive pool stay warm. The transfer is driven through the multi interface, so the worker parks on `curl_multi_select()` (a socket-level wait) instead of blocking inside `curl_exec()`. Bodies stream in 8 KiB chunks **in both directions** โ€” request bodies are *pulled* from the PSR-7 request stream and response bodies are *pushed* into a PSR-7 stream โ€” so neither side is ever materialised whole in worker memory. Beta-2 status ------------- [](#beta-2-status) No behavioural changes since Beta-1 โ€” lockstep version bump only. The client surface, security defaults, and streaming guarantees remain as described below. ๐Ÿ†• Beta-1 foundations (still current) ------------------------------------ [](#-beta-1-foundations-still-current) - **Persistent socket reuse.** A single `\CurlHandle` and a single `\CurlMultiHandle` live for the worker's lifetime; `curl_reset()` between requests keeps the connection pool, DNS cache, and TLS session cache warm. Source: `Client.php` (`// Holds a single persistent CurlHandle plus a CurlMultiHandle that are reused via curl_reset() ...`). - **Non-blocking transfer.** The transfer runs through the persistent `\CurlMultiHandle` (`curl_multi_exec` + `curl_multi_select`) rather than the blocking `curl_exec()`. The worker never busy-spins, and a slow legacy backend can no longer pin it on a blocking syscall beyond the hard timeout ceiling. The multi handle is also the building block for future concurrent fan-out. - **Bidirectional bounded streaming (8 KiB chunks).** Request bodies are streamed via `CURLOPT_READFUNCTION` + `CURLOPT_UPLOAD` (pulling `CHUNK_SIZE = 8 * 1024` bytes at a time from the PSR-7 request stream) instead of buffering the whole payload with `CURLOPT_POSTFIELDS`. Known lengths are advertised with `CURLOPT_INFILESIZE`; unknown lengths fall back to `Transfer-Encoding: chunked`. Response bodies stream via `CURLOPT_WRITEFUNCTION`. A multi-gigabyte multipart upload is proxied without a RAM spike. - **SEC-03 SSRF allowlist.** `Client::applyRequest()` sets both `CURLOPT_PROTOCOLS` and `CURLOPT_REDIR_PROTOCOLS` to `CURLPROTO_HTTP | CURLPROTO_HTTPS` (verbatim, `Client.php:178-179`), blocking SSRF pivots via `file://`, `gopher://`, `dict://`, `ldap://`, etc. โ€” even when a caller-supplied URL or a server-supplied `Location` header tries to switch protocols mid-flight. ๐Ÿ“ฆ Installation -------------- [](#-installation) ``` composer require waffle-commons/http-client ``` You also need PSR-17 factory implementations for `ResponseFactoryInterface` and `StreamFactoryInterface`. The framework defaults to `waffle-commons/http`; `nyholm/psr7` works equally well. ๐Ÿงฑ Surface --------- [](#-surface) ClassRole`Waffle\Commons\HttpClient\Client``final readonly` PSR-18 client. Persistent cURL easy + multi handles, non-blocking transfer, hardcoded 1s connect / 10s total timeouts, request **and** response bodies streamed in 8 KiB chunks.`Waffle\Commons\HttpClient\Exception\HttpClientException`Base class for client errors (e.g. handle init failure). Implements `Psr\Http\Client\ClientExceptionInterface`.`Waffle\Commons\HttpClient\Exception\NetworkException`Transport-layer failures (DNS, connect/read timeout, TLS, reset). Implements `Psr\Http\Client\NetworkExceptionInterface`.`Waffle\Commons\HttpClient\Exception\RequestException`Protocol-level failures or empty responses. Implements `Psr\Http\Client\RequestExceptionInterface`.๐Ÿš€ Usage ------- [](#-usage) ``` use Nyholm\Psr7\Factory\Psr17Factory; use Waffle\Commons\HttpClient\Client; $psr17 = new Psr17Factory(); $client = new Client( responseFactory: $psr17, streamFactory: $psr17, ); $request = $psr17->createRequest('GET', 'https://api.example.com/users'); $response = $client->sendRequest($request); echo $response->getStatusCode(); // 200 echo (string) $response->getBody(); // streamed body ``` ๐Ÿ›ก๏ธ Security defaults -------------------- [](#๏ธ-security-defaults) The client enforces a minimum security baseline that callers cannot lower: OptionValueWhy`CURLOPT_PROTOCOLS``CURLPROTO_HTTP | CURLPROTO_HTTPS`SEC-03 SSRF allowlist on the request URL.`CURLOPT_REDIR_PROTOCOLS``CURLPROTO_HTTP | CURLPROTO_HTTPS`SEC-03 SSRF allowlist on any redirect target.`CURLOPT_SSL_VERIFYPEER``true`Forces full certificate validation.`CURLOPT_SSL_VERIFYHOST``2`Forces hostname match against the certificate.`CURLOPT_FOLLOWLOCATION``false`The client never silently follows redirects โ€” callers must handle them explicitly.`CURLOPT_CONNECTTIMEOUT_MS``1_000`Hard 1-second ceiling. Cannot be raised.`CURLOPT_TIMEOUT_MS``10_000`Hard 10-second ceiling. Cannot be raised. A hung legacy backend must never lock a worker thread.๐Ÿ˜ PHP 8.5 features used ----------------------- [](#-php-85-features-used) - **`final readonly class Client`** with promoted constructor properties. - **Typed integer constants** for every timeout/chunk-size value (`CONNECT_TIMEOUT_MS`, `TIMEOUT_MS`, `CHUNK_SIZE`). - **`#[\Override]`** on the PSR-18 implementation method. - **`match`** expression for HTTP-version negotiation. ๐Ÿงญ Architectural boundary (`mago guard`) --------------------------------------- [](#-architectural-boundary-mago-guard) An active dependency **perimeter** is enforced on every CI run by `vendor/bin/mago guard` (bundled into `composer mago`; zero baselines). The rules live in [`mago.toml`](./mago.toml) under `[guard.perimeter]` โ€” a forbidden `use` statement fails the build, not a reviewer. Production code under `Waffle\Commons\HttpClient` may depend **only** on: - `Waffle\Commons\HttpClient\**` โ€” itself - `Waffle\Commons\Contracts\**` โ€” the shared contracts package, the **only** Waffle dependency permitted - `Psr\**` โ€” PSR interfaces (PSR-7 / PSR-17 / PSR-18) - `@global` + `Psl\**` โ€” PHP core (including `ext-curl`) and the PHP Standard Library Test code under `WaffleTests\Commons\HttpClient` is unrestricted (`@all`); the `tests/src/ClientTest.php` `php-mock` fixture is listed in `[guard].excludes` because it re-declares the production namespace to stub libcurl. Structural rules are guarded too: interfaces must be named `*Interface`, `Exception\**` classes must end in `*Exception`, and any `Enum\**` namespace may hold only `enum` declarations. Contract-first, component-agnostic by construction: components compose through `waffle-commons/contracts`, never directly through one another. ๐Ÿงช Testing --------- [](#-testing) ``` docker exec -w /waffle-commons/http-client waffle-dev composer tests ``` The test suite uses `php-mock/php-mock-phpunit` to stub libcurl entry points (`curl_init`, `curl_setopt_array`, `curl_multi_exec`, `curl_multi_info_read`, โ€ฆ), so PHPUnit runs hermetically without network I/O. Dedicated tests assert the SEC-03 protocol allowlist, the chunked request-body upload, and the non-blocking multi-handle transfer. ๐Ÿ“„ License --------- [](#-license) MIT โ€” see [LICENSE.md](./LICENSE.md). ### Health Score 43 โ€” FairBetter than 89% of packages Maintenance97 Actively maintained with recent releases Popularity11 Limited adoption so far Community10 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~9 days Total 6 Last Release 16d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/34a7557a3fb23aaf788ca3892b9b7efdf96e753264bafd0599153c9e8a921316?d=identicon)[LesliePetrimaux](/maintainers/LesliePetrimaux) --- Top Contributors [![supa-chayajin](https://avatars.githubusercontent.com/u/695448?v=4)](https://github.com/supa-chayajin "supa-chayajin (37 commits)") ### Code Quality TestsPHPUnit Static AnalysisPsalm Type Coverage Yes ### Embed Badge ![Health badge](/badges/waffle-commons-http-client/health.svg) ``` [![Health](https://phpackages.com/badges/waffle-commons-http-client/health.svg)](https://phpackages.com/packages/waffle-commons-http-client) ``` ### Alternatives [guzzlehttp/psr7 PSR-7 message implementation that also provides common utility methods 7.9k1.1B4.1k](/packages/guzzlehttp-psr7)[tempest/framework The PHP framework that gets out of your way. 2.2k34.4k16](/packages/tempest-framework)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 85036.3k](/packages/flow-php-flow)[telnyx/telnyx-php Official Telnyx PHP SDK โ€” APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 36789.4k2](/packages/telnyx-telnyx-php)[laudis/neo4j-php-client Neo4j-PHP-Client is the most advanced PHP Client for Neo4j 185702.8k44](/packages/laudis-neo4j-php-client)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)