Http Batch Contract Laravel Package

Product Decisions This Supports

• Roadmap / upgrade sequencing: v3.0.0 is a major, breaking release. Any product surface depending on ResponseBatchInterface gets a forced migration item. Decide now whether to (a) pin v2 and schedule the bump into a known sprint, or (b) adopt v3 before building new fan-out features on top of the old contract.
• Build vs buy on request batching: the package now hands you raw ResponseInterface[] and ClientExceptionInterface[] instead of wrapper objects. That is a real "buy" signal — you no longer need an internal adapter layer to translate batch items into PSR-7 responses and PSR-18 exceptions before your domain code sees them.
• Feature design for partial-failure UX: getResponses() / getExceptions() map cleanly onto the failure reporting your product actually shows ("14 of 20 price feeds refreshed"). This makes it cheaper to ship dashboards, import/enrichment screens, and webhook fan-out with per-item status.
• Fluent pipelines over result sets: filter() returning static means product rules like "only retry these", "only surface these to the user", "split by provider" compose without intermediate variables or custom collection plumbing. Lower cost to iterate on filtering rules post-launch.
• Risk decision to make explicitly: dropping BatchItemInterface removes the wrapper that typically carried per-request context (request key, labels, custom metadata). If any planned feature depends on mapping a result back to the originating item by index/key rather than order, that association logic is now our code. Price that in before committing to v3.
• Reduced defect surface: specific return types (ResponseInterface[], ClientExceptionInterface[]) mean static analysis catches contract misuse at CI time instead of at runtime in production — a quality decision, not just a style one.

When to Consider This Package

Adopt when:

• You have genuine fan-out HTTP work: aggregation across providers, bulk enrichment, multi-endpoint webhooks, import/sync jobs.
• Your stack is PSR-18/PSR-7 native, so ResponseInterface and ClientExceptionInterface slot straight into existing handlers and exception mapping.
• You want per-item error isolation — one failing provider should not fail the whole operation, and the caller should receive successes and exceptions separately.
• You are starting fresh or already on v3 — no migration cost, and you get the typed, fluent API from day one.

Look elsewhere or defer when:

• You are on v2 with meaningful surface area. Renamed methods plus changed return types mean this is a coordinated upgrade: composer constraint bump, call-site rewrite, updated tests, and re-verification of anything that consumed BatchItemInterface. Do the audit before you commit.
• You need durable, queue-backed execution with retries, backoff, and dead-lettering. This is an in-process concurrency primitive; durability belongs to Laravel's queue layer. Use both, but don't mistake this for a job system.
• You make one or two outbound calls per request. The interface overhead isn't repaid.
• Provider-side rate limits dominate your traffic. Batching makes it trivially easy to exceed quotas; you need a throttling strategy regardless of which client you pick.
• You are mid-freeze or mid-launch and the migration cannot be tested properly. Pin v2, isolate the blast radius, revisit.

Also worth confirming: this release's notes carry an automated-generation attribution. Not disqualifying, but for a major version, verify the maintainer's migration guide is complete and that a patch release follows promptly — budget for a v3.0.1.

How to Pitch It (Stakeholders)

For executives: This is a library upgrade with a modest, well-documented breaking change, and it buys us a cleaner foundation for every feature that talks to multiple external services at once. Concretely: better compiler/static-analysis guarantees (fewer production surprises), simpler code for showing users which parts of an operation succeeded, and less in-house glue code we have to maintain. Cost is a bounded migration — the release ships a before/after guide — not a rewrite. Recommendation: schedule the bump in the next planning cycle rather than carrying a pinned old major.

For engineering: v3.0.0 breaks ResponseBatchInterface. getSuccessfulResults() → getResponses() returning ResponseInterface[]; getFailedResults() → getExceptions() returning ClientExceptionInterface[]; filter() now returns static for chaining instead of array. Upside is typed, semantic, fluent results and no wrapper indirection. The one thing to watch: we lose BatchItemInterface, so any code that stashed request keys or per-item metadata alongside results needs its own correlation logic — that's the main estimation risk. Plan the work as: constraint bump → call-site rewrite → re-verify correlation and error mapping in tests. Do not bundle it into a release freeze.

For the broader business, one line: we are upgrading a dependency to a cleaner major version on a planned schedule so that multi-service features stay cheap and reliable to build — no user-facing change expected.