Http Laravel Package

Getting Started

Before writing any code, understand what you're consuming. netflex/http is a read-only subtree split of netflex/framework — it exists so the HTTP component can be required independently, not as a standalone project you contribute to.

1. Decide your entry point. For most apps you should depend on netflex/framework (or your Netflex platform install) rather than this split. Require netflex/http directly only when you need the HTTP layer in isolation and you're prepared to keep its version locked in step with the rest of the framework.
2. Read composer.json first. It tells you the autoload namespace, PHP constraint, and — critically — which PSR interfaces or HTTP backends (PSR-7, PSR-18, PSR-15, Guzzle, Symfony HttpFoundation) the component builds on. That single file defines most of your integration surface.
3. Then src/ in dependency order. Typical layout: request abstraction → response abstraction → client/transport → middleware or handlers. Read the tests directory alongside each class; in split repos the tests are the most reliable usage documentation you'll get.
4. Check CHANGELOG.md / tags. Because versions are mirrored from the monorepo, the tag you see here should match a framework version. Note it.
5. First use case: issue one request through the component's client and inspect the response object end-to-end (status, headers, body, any decoded payload). Then wrap it in a thin service class of your own and bind that in Laravel's container. That's the smallest path from "installed" to "usable in a controller."

If the repo has zero dependents and zero stars, treat every assumption as unverified — confirm the API by reading source, not by searching for blog posts.

Implementation Patterns

Wrap, don't scatter. Bind the component's client/factory as a singleton in a service provider and inject a small application-level service. This keeps the component swappable and gives you one place to add headers, timeouts, and logging.

// Illustrative — confirm actual class names under src/ before use.
$this->app->singleton(\Netflex\Http\Client::class, function ($app) {
    return new \Netflex\Http\Client(
        baseUrl: config('services.netflex.base_url'),
        timeout: config('services.netflex.timeout', 10),
    );
});

Request/response as DTOs. If the component ships request and response value objects, use them as typed boundaries: build a request in your service, hand back a response DTO to your controller, and map to your own resource classes. Never leak raw transport objects into views or jobs.

Middleware/handler stacking is the natural extension point for cross-cutting concerns: auth token injection, correlation IDs, retry policies, and logging. Keep the stack shallow and ordered deliberately — outer middleware sees the request first and the response last.

Testing pattern. Because this is a transport layer, test it in two layers:

• Unit: fake or mock the underlying transport (or a PSR-18 client) and assert your service builds the right request and handles each response shape.
• Contract: a small suite that hits a recorded fixture/sandbox to catch upstream drift. Tag it so it doesn't run on every commit.

Interop over replacement. If the component implements PSR-7/PSR-18/PSR-15, decorate it rather than fork it. A decorator that adds a header or logs latency survives framework upgrades; a modified copy does not.

Pick one HTTP path per feature. In a Laravel app you likely also have Illuminate\Support\Facades\Http. Choose per integration — framework component for Netflex APIs, Http facade for third-party APIs — and document the choice. Mixing both for the same upstream leads to two different retry/timeout behaviors.

Gotchas and Tips

• This repo is read-only. Pull requests and issues belong in netflex/framework. Anything merged here is overwritten by the next split. Fork the monorepo, not this.
• Version skew is the #1 failure mode. If netflex/framework and netflex/http are installed at mismatched versions you get missing classes, autoload conflicts, or duplicated symbols. Pin them together in composer.json and upgrade in lockstep.
• Don't require both the framework and this split unless the framework's own dependency graph already pulls it. Double-installing the same namespace across two packages usually ends in a "class not found" that looks like a cache problem.
• Config lives elsewhere. A split package typically has no publishable config of its own; base URLs, credentials, and timeouts come from the host framework's config or environment. Grep the source for config(/env( to find what it actually reads.
• Error semantics are ambiguous. Determine early whether failures arrive as exceptions, response status codes, or both. Handle the transport failure (timeout, DNS, connection reset) separately from an HTTP error status — they need different retry logic.
• Timeouts default silently. Set explicit connect and total timeouts in your binding. The default is often "wait forever," which surfaces as hung queue workers, not as an error.
• Debugging: log the raw request (method, URL, headers with secrets redacted) and the raw response before any decoding. Middleware ordering bugs show up as headers applied on the wrong hop or retries that re-authenticate incorrectly.
• Stale split risk. With zero stars and zero dependents there's no community to catch breakage. Pin an exact version, run your own contract tests, and treat upgrades as deliberate change windows.
• Extension points to prefer: custom middleware/handlers, a client factory override, or subclassing the base client. Avoid editing vendor code, and avoid reaching into private properties — the split's internal structure is not part of the contract.