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

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.