Laravel Transporter Laravel Package

Product Decisions This Supports

• Build vs. buy for the integration layer. The alternative to laravel-transporter is an internal HTTP wrapper: base client, auth/header handling, retry and timeout policy, response hydration, and test fakes. That is a multi-week build plus indefinite ownership of plumbing nobody wants to maintain. This package is an MIT-licensed Composer dependency that supplies the same structure on top of Laravel's HTTP client. For a Laravel shop it's a clean "buy" candidate — with the caveat that "buy" here means "adopt a small open-source library," which carries a different risk profile than a vendor contract.

• Turning integrations into estimable units of roadmap. One Transporter per vendor, one Request per endpoint, one typed Response per payload. That converts "add vendor X" from an open-ended estimate into a repeatable shape, so integration work across payments, shipping, CRM, KYC, tax, and comms becomes comparable quarter over quarter. PM value: integrations stop being the line item that always slips.

• Integration velocity as a roadmap lever. Roadmaps that depend on adding vendors faster — more payment methods, more carriers, regional providers — get cheaper per integration and much cheaper to hand off. Onboarding an engineer onto an integration becomes reading four short classes instead of tracing Http:: calls scattered across controllers, jobs, and Artisan commands.

• How we represent vendor contracts is a product-risk decision, not a style preference. Arrays are fast to write and break silently; typed DTOs are slower to write and break loudly in CI. A vendor silently renaming a field is a checkout incident in one world and a red test in the other. This package lets us take the typed position without building the machinery ourselves.

• Latency-dependent features without a platform bet. Pool supports fanning out independent calls concurrently (dashboard aggregations, checkout pre-flight checks). Release 4.0.1 makes the Pool parameter nullable in ensureRequest, which reads as "pooling is optional per call site." Product implication: ship the synchronous version of a feature now, turn concurrency on per-transporter later as a tuning dial — not an architecture commitment.

• Test strategy and vendor-sandbox spend. Because it delegates to Laravel's HTTP client, Http::fake() and existing assertions work unchanged. That is a direct input into two budget decisions: whether we pay for premium vendor sandbox tiers, and whether integration tests can run deterministically in CI without network access.

• Dependency posture and exit cost. 479 stars, 0 dependents, MIT, one primary maintainer. That is "adopt behind a thin wrapper with a pinned constraint," not "make it a platform pillar." The product consequence is a design rule we can state in review: don't build features that can't be ported off it. Keep Transporters thin so replacing the library is a sprint, not a quarter.

• Scoping realism for heavy-auth vendors. OAuth refresh orchestration, mTLS, request signing, and multi-tenant token rotation are not what this package sells. Discovering that mid-project is a schedule surprise; discovering it in a spike is a planning input.

When to Consider This Package

Consider it when:

• The service is Laravel-first and the team already accepts framework-coupled abstractions (Eloquent, queues, facades).
• You call three or more third-party HTTP APIs, or expect to within a couple of quarters.
• Integration code is scattered — raw Http:: calls in controllers, jobs, and commands, each with its own auth and error handling.
• Vendor payload drift is a live risk and you want typed responses as the seam between HTTP and domain logic.
• You want deterministic integration tests without hitting vendor sandboxes.
• You need independent-request fan-out (Pool) but not a full async/queue architecture.
• You can pin ^4.0, confirm the Laravel/PHP support matrix in composer.json, and absorb a small-maintainer release cadence.

Look elsewhere when:

• You need spec-driven, generated clients (OpenAPI/Swagger). This is hand-written typed clients, not a schema authority — use a generator.
• The codebase is polyglot or framework-agnostic. A Laravel-specific transport layer is a one-way door; a PSR-18 client plus a thin wrapper travels better.
• The integration is revenue-critical and un-portable. Single maintainer, no SLA, no LTS — that belongs in the dependency risk register, not the happy path.
• You only have one or two trivial endpoints. The abstraction earns its keep at volume; below that, Laravel's HTTP client alone is simpler.
• Your auth story is heavy — OAuth refresh orchestration, mTLS, request signing, token rotation across tenants. You may end up building most of it around the Transporter anyway; scope that before counting the savings.
• You need webhook ingestion, event streaming, or heavy declarative validation/mapping. Different problem, different tool.
• 0 dependents is a signal. Low ecosystem validation and low blast radius. Treat it as unproven at scale: pilot, don't assume.

Sequencing guidance for the PM: if the team is on 3.x, do not conflate the major upgrade with adoption. Finish the 4.0.0 review first. Then adopt 4.0.1 as a routine composer update within ^4.0, and run the spike on two endpoints — one simple read, one with non-trivial auth and error handling — before mandating the pattern.

How to Pitch It (Stakeholders)

For executives (one paragraph): We're evaluating a small, MIT-licensed open-source Laravel library that gives every third-party API integration the same structure — one client per vendor, one class per endpoint, typed responses instead of raw arrays. The business value is threefold: new integrations become predictable, estimable pieces of work rather than open-ended projects; vendor payload changes fail loudly in our test suite instead of silently in checkout; and engineers stop rebuilding the same HTTP plumbing for the fifth time. It's cheap to trial and reversible — pin the version, keep our usage thin, pilot two integrations, and measure defect rate and time-to-add-an-endpoint before standardizing. The main caveat is bus factor: modest adoption (~479 stars), no downstream dependents, one primary maintainer — so we deliberately keep the integration surface small enough to replace.

For engineering (summary): juststeveking/laravel-transporter wraps Laravel's HTTP client in Transporter / Request / Response classes: base URL, headers, and auth live on the Transporter; endpoint, method, and payload live on the Request; the Response hydrates a typed DTO so callers never touch arrays. Pool supports concurrent independent requests. Because it delegates to the framework client, existing Http::fake() patterns and assertions apply unchanged. Latest release 4.0.1 is a semver patch — it makes the Pool parameter nullable in ensureRequest, a type-widening change with no break for callers already passing a Pool; upgrade is a routine composer update within ^4.0, no config or migration steps. Recommended next step: verify the Laravel/PHP constraints in composer.json, confirm what ensureRequest actually does on the null path (default pool vs. no pooling — this has throughput implications), then spike two integrations — one simple read, one with non-trivial auth and error handling — and compare against hand-rolled Http:: calls on lines of code, test determinism, and effort to add endpoint number five. Pin ^4.0, keep Transporters thin so the dependency stays replaceable, and log the single-maintainer risk in the dependency register.