README

WireHTTP

An Enterprise-Grade, Dependency-Free Asynchronous HTTP Client for PHP 8.1+

Developed by Anant

WireHTTP brings true non-blocking concurrency, intelligent fault tolerance, and beautiful object hydration to modern PHP applications. It is engineered from the ground up to handle massive workloads without dragging a single external dependency into your vendor folder.

📊 Feature Matrix

🏛️ Architecture & Data Flow

WireHTTP's core is an ultra-fast, array-based MiddlewareStack. Requests flow symmetrically through Interceptors, hitting the Transport layer, and returning as beautifully decorated objects.

graph TD
    %% Styling
    classDef facade fill:#2D3748,stroke:#4A5568,stroke-width:2px,color:#fff,rx:10,ry:10;
    classDef middleware fill:#3182CE,stroke:#2B6CB0,stroke-width:2px,color:#fff,rx:10,ry:10;
    classDef network fill:#38A169,stroke:#2F855A,stroke-width:2px,color:#fff,rx:10,ry:10;
    classDef target fill:#E53E3E,stroke:#C53030,stroke-width:2px,color:#fff,rx:10,ry:10;

    subgraph Application Space
        A[Developer API<br/><code>Wire::get()</code>]:::facade
    end

    subgraph WireHTTP Pipeline
        B[Middleware Stack<br/>(Rate Limit, Retry, Circuit Breaker)]:::middleware
        C[Transport Layer<br/><code>ext-curl</code> / Fibers]:::network
        D[Response Decorator<br/>JSON / XML / DTO Hydration]:::middleware
    end

    subgraph External
        E((Remote API)):::target
    end

    A ==>|Build Request| B
    B ==>|Apply Interceptors| C
    C ==>|Execute Asynchronously| E
    E -.->|Raw HTTP Response| C
    C -.->|Reverse Interceptors| D
    D ==>|Hydrated Object| A

💻 Developer Experience (DX)

use WireHttp\Wire;

$response = Wire::post('https://api.example.com/billing')
    ->withBearer('secret_token')
    ->withHeader('X-Client', 'MobileApp')
    ->withJson(['plan' => 'enterprise', 'users' => 500])
    ->timeout(5.0) // Request-specific timeout override
    ->send();

if ($response->isClientError()) {
    throw new Exception($response->json()['message']);
}

use WireHttp\Wire;
use WireHttp\Async\Future;

// Dispatch 3 non-blocking network requests
$users   = Wire::get('https://api.example.com/users')->sendAsync();
$stats   = Wire::get('https://api.example.com/stats')->sendAsync();
$reports = Wire::get('https://api.example.com/reports')->sendAsync();

// Block the current Fiber until ALL requests settle
[$resUsers, $resStats, $resReports] = Future::all(...[$users, $stats, $reports]);

echo $resUsers->status(); // 200

use WireHttp\Response\Hydrator\Attributes\JsonProperty;

class ProfileDto {
    public int $id;
    
    // Map mismatched JSON keys seamlessly
    #[JsonProperty('avatar_url')]
    public string $avatarUrl;
}

// Automatically decodes JSON, validates types, and returns the DTO!
$profile = Wire::get('https://api.example.com/me')->send()->into(ProfileDto::class);

echo $profile->avatarUrl;

use WireHttp\Wire;
use WireHttp\Configuration\ClientConfig;
use WireHttp\Middleware\Core\CookieJar;

$client = Wire::with(
    ClientConfig::create()
        ->withFollowRedirects(true, maxRedirects: 5)
        ->withCookies(true, new CookieJar())
);

// 1. Logs in and receives a Set-Cookie header
$client->post('/login')->withForm(['user' => 'admin'])->send();

// 2. Automatically injects the Cookie into subsequent requests!
$dashboard = $client->get('/dashboard')->send()->body();

🧪 Zero-Network Mocking Engine

Testing external APIs shouldn't require an internet connection or fragile mock objects. WireHTTP includes a powerful global mock interceptor.

use WireHttp\Wire;
use WireHttp\Transport\Mock\MockResponseQueue;
use WireHttp\Http\Response;
use WireHttp\Http\Stream;

$queue = new MockResponseQueue();
$queue->push(new Response(201, [], Stream::fromString('{"status": "created"}')));

// Hijack the transport layer globally
Wire::fake($queue);

// This executes instantly and returns the mock response!
$response = Wire::post('https://api.example.com/charge')->send();

assert($response->json()['status'] === 'created');

WireHTTP - Engineered for Resilience, Built for Speed.

Released under the MIT License.