Http Laravel Package

Getting Started

hoa/http is a small, low-level HTTP message library from the Hoa project: request/response abstractions, URL handling, cookies, and a client built on Hoa’s stream stack. It is archived, last released in 2017, has 10 stars and 0 dependents. Treat it as legacy infrastructure, not a foundation for new Laravel work.

Minimal evaluation steps:

composer require hoa/http
# or, if Composer refuses on your PHP version:
composer require hoa/http --ignore-platform-reqs

Then look first at:

• vendor/hoa/http/Request.php — request construction, method, URL, headers, body
• vendor/hoa/http/Response.php — status, headers, body
• vendor/hoa/http/Url.php — URL parsing and query manipulation
• vendor/hoa/http/Client.php — transport wrapper, if present in your installed version
• vendor/hoa/http/composer.json — Hoa\Stream, Hoa\Protocol, Hoa\Event, Hoa\Consistency dependencies
• vendor/hoa/http/Test/Unit — the most reliable API documentation for an archived package

Do not assume PSR-7 or PSR-18 method names. The API is Hoa-specific and small enough to read directly before writing code.

The most realistic first use case for a Laravel developer is not replacing Illuminate\Support\Facades\Http. It is either:

1. Maintaining an existing integration that already returns Hoa\Http\Request/Response objects, or
2. Using Hoa\Http\Url as a quick URL parser in a legacy script.

For anything greenfield, the first use case should be: “wrap this behind an adapter so it can be removed later.”

use Hoa\Http\Url;

$url = new Url('https://api.example.com/v1/users?page=2');
// Inspect available getters in Url.php before relying on them.

Implementation Patterns

Adapter around the client. Never inject Hoa\Http\Client, Request, or Response directly into controllers, jobs, or domain services. Create one boundary class that owns all Hoa types and exposes Laravel-friendly arrays or DTOs.

namespace App\Support\Http;

final class LegacyHoaGateway
{
    public function get(string $path, array $query = []): array
    {
        // Build Hoa request, send, and normalize response here.
        // Return ['status' => ..., 'headers' => ..., 'body' => ...].
    }
}

Bind this class in a service provider and let the rest of the application depend on your interface, not on Hoa.

Centralize request construction. Put base URL, auth headers, user agent, timeouts, and default query parameters in one builder. Hoa gives you message objects, not a full HTTP client policy layer, so retries, backoff, logging, and header defaults are your responsibility.

Normalize responses immediately. Convert Hoa responses to Laravel response() objects, arrays, or typed DTOs at the boundary. Do not return Hoa response objects from controllers; they are not compatible with Laravel’s response pipeline, testing helpers, or middleware.

Use it for URL/value-object work only where safe. If you only need URL parsing or query manipulation, isolate Hoa\Http\Url usage. If you need transport, be aware that Hoa’s client is stream-based and does not provide Guzzle-style middleware, retries, connection pooling, or PSR-18 interoperability.

Testing pattern. Because Laravel’s Http::fake() will not intercept Hoa calls, your adapter should be fakeable at your own boundary. In unit tests, construct Hoa Response objects with fixed status/headers/body and feed them to the adapter, or bind a fake gateway implementation. Do not let tests make real outbound calls.

Migration workflow. If you inherit a codebase using hoa/http, inventory every usage, move it behind an adapter, then replace the adapter internals with Laravel’s HTTP client or Guzzle. Keep Hoa only for parsing if absolutely necessary, and mark it as a temporary dependency.

Integration tip: avoid mixing stacks. Do not use hoa/http alongside Guzzle or Laravel’s HTTP client for the same endpoint set. Different redirect, cookie, TLS, timeout, and error semantics will create inconsistent behaviour that is hard to debug.

Gotchas and Tips

• Archived and unmaintained. There are no security patches, no PHP 8 compatibility commitments, and no upstream support. Composer will warn that the package is abandoned. Pin the exact version if you are forced to keep it.
• PHP compatibility is the first blocker. Hoa packages from this era often fail on modern PHP due to old syntax, dependency constraints, and Hoa’s internal consistency layer. Test installation on your target PHP version before planning around it; --ignore-platform-reqs may install it but does not make it safe.
• Not PSR-7, not PSR-18, not Laravel-native. You cannot pass these objects to PSR-7 middleware, Laravel’s HTTP fake, or most modern HTTP tooling without conversion.
• Body streams can be consumed once. Hoa’s message bodies are stream-oriented. If you read the body for logging, rewind or cache it before reading again. Double-reading is a common source of empty responses.
• Header semantics differ. Header lookup may be case-sensitive or normalize differently from PSR-7. Multi-value headers need explicit handling. Inspect getHeaders() output rather than assuming a shape.
• URL encoding quirks. Build query strings with http_build_query() and test array parameters, nested parameters, and already-encoded values. Do not assume Guzzle-compatible URL encoding.
• Error handling is Hoa-specific. Exceptions live under the Hoa namespace and will not be caught by typical Laravel HTTP exception handling. Catch at your adapter boundary and translate to your application’s exception types.
• Transport policy is missing. Retries, redirects, TLS verification, timeouts, proxy configuration, and connection reuse are not delivered in the way Laravel developers expect. Configure and test each explicitly.
• Cookie handling is minimal. Do not assume a cookie jar that matches browser or Guzzle behaviour. For session-sensitive integrations, prefer a maintained client.
• Autoload and namespace collisions. Multiple Hoa packages can pull different versions of shared Hoa dependencies. Check composer why hoa/http and avoid mixing Hoa versions across the application.
• Debugging tip. Dump the request method, URL, headers, and body before sending; dump status, headers, and the full body after receiving. Because there is little documentation, the unit tests and class source are the source of truth.
• Extension points are limited and risky. Subclassing Request/Response or wrapping the client is possible, but you are extending an abandoned API. Keep extensions inside your adapter and avoid spreading Hoa types through the codebase.
• Bottom line for Laravel teams. Use Illuminate\Support\Facades\Http or Guzzle for new work. If hoa/http already exists, isolate it, test it hard, and schedule removal; its low adoption and archived status make it a liability rather than a day-to-day productivity tool.