matraux / http-requests
A PHP 8.4+ library for creating and batching HTTP requests with type‑safe wrappers, event hooks, and ergonomic collections, powered by Guzzle and PSR‑7.
Requires
- php: ^8.4
- guzzlehttp/guzzle: ^7.10
Requires (Dev)
- contributte/qa: ^0.3.2
- nette/neon: ^3.4
- nette/tester: ^2.5
- nette/utils: ^4.0
- phpstan/phpstan: ^2.1
- symfony/process: ^7.3
- tracy/tracy: ^2.10
This package is auto-updated.
Last update: 2025-09-19 13:09:45 UTC
README
Introduction
A PHP 8.4+ library for working with HTTP requests and responses in a structured, type‑safe way. Provides easy creation of single or batch HTTP requests, ergonomic collections, and seamless integration with PSR‑7 and Guzzle. Includes built‑in event hooks (onBefore, onAfter, onSuccess, onFail) for logging, debugging, authentication, or custom processing at each stage of the request lifecycle. Errors from the transport layer are normalized into PSR‑7 responses (no exceptions are thrown from send()/sendBatch()), making the flow predictable in both single and parallel/batch scenarios.
Features
- Object‑oriented HTTP request/response wrappers (PSR‑7 compatible); Response also keeps the original Request
- Type‑safe API: Method enum or string, Stringable URI, strict containers for headers, config, and collections
- Ergonomic collections: RequestCollection (mutable) and ResponseCollection (read‑only)
- Easy batching and parallel execution via Guzzle promises (sendAsync) and Utils::settle()
- Built‑in events: onBefore, onAfter, onSuccess(ResponseInterface), onFail(GuzzleException) for hooks, logging, authentication, and custom logic
- Default headers merging: headers set on Requester are applied to every Request right before sending
- Unified error handling: exceptions are mapped to a PSR‑7 Response; when no response is available, a synthetic 500 is created with the exception message
- Simple API for reading status, headers, and body (getStatusCode(), getHeaderLine(), getBody())
- Lazy Guzzle client configured through a typed Config container
- Designed for easy testing and debugging; event handler failures are isolated
Installation
composer require matraux/http-requests
Requirements
version | PHP | Note |
---|---|---|
1.0.0 | 8.4+ | Initial release |
Examples
Single request
use Matraux\HttpRequests\Requester; use Matraux\HttpRequests\Request\Method; use Matraux\HttpRequests\Request\Request; $requester = Requester::create(); $request = Request::create(Method::Get, 'https://www.example.com'); $response = $requester->send($request); echo $response->getStatusCode(); // e.g. 200, 404, 500, ... echo $response->getBody()->getContents(); // Response body echo $response->getHeaderLine('Content-Type'); // e.g. text/html, application/json
Batch requests (collections)
use Matraux\HttpRequests\Requester; use Matraux\HttpRequests\Request\Method; use Matraux\HttpRequests\Request\Request; use Matraux\HttpRequests\Request\RequestCollection; $requester = Requester::create(); $requests = RequestCollection::create(); $requests[] = Request::create(Method::Get, 'https://www.example.com/?page=1'); $requests[] = Request::create(Method::Get, 'https://www.example.com/?page=10'); $requests['custom'] = Request::create(Method::Get, 'https://www.example.com/?page=100'); $responses = $requester->sendBatch($requests); foreach ($responses as $index => $response) { echo "$index: " . $response->getStatusCode() . "\n"; } echo $responses['custom']->getBody()->getContents();
Using events
use Matraux\HttpRequests\Requester; use Matraux\HttpRequests\Request\Method; use Matraux\HttpRequests\Request\Request; use Psr\Http\Message\ResponseInterface $requester = Requester::create(); $requester->onBefore[] = function() { echo "Sending request...\n"; }; $request = Request::create(Method::Get, 'https://www.example.com'); $request->onBefore[] = function() use ($request) { echo "Requesting URL: " . $request->uri . "\n"; }; $request->onSuccess[] = function(ResponseInterface $psrResponse): void { echo "Success response: " . $psrResponse->getStatusCode() . "\n"; }; $response = $requester->send($request);
Development
See Development for debug, test instructions, static analysis, and coding standards.
Support
For bug reports and feature requests, please use the issue tracker.