Integration Engine Laravel Package

Product Decisions This Supports

Build vs. buy for the integration layer. This package is a "buy the pattern, build the adapters" play. It does not give you integrations — it gives you a mandated shape for them (Action → Mapper → Response, one YAML action map per integration). The decision it unlocks: do we standardize how every third-party API enters our codebase, or keep letting each squad improvise? If the roadmap includes 3+ external APIs over 12 months, a convention is cheaper than coordination meetings.

Integration roadmap sequencing. The make:integration scaffolding command effectively prices a new integration as "one Action + one Mapper + one Response + a YAML entry." That's a defensible unit-cost input for planning: you can commit to "N integrations per quarter" with more confidence than if each one is a fresh design exercise. It also de-risks handing integrations to less senior engineers.

Vendor-swap optionality. The prescribed Anti-Corruption Layer (Gateway) is the real product asset. It means the decision "which CRM / payment provider / KYC vendor do we use" becomes reversible at bounded cost, because exactly one class knows both the vendor DTO and the domain model. That is a roadmap-level hedge, not a code-style preference — it belongs in the same conversation as multi-vendor fallback, regional providers, and pricing renegotiation leverage.

Ship-or-defer on OAuth2-based integrations. Dynamic authorization (token action, cached, injected as static auth, auto-eviction and single retry on 401) removes a recurring prerequisite project — "we need token management infrastructure first." That usually unblocks a whole category of feature work (marketplace connections, customer-authorized data pulls) that would otherwise sit behind platform work.

Bulk and dashboard features. sendMany() gives parallel fan-out with per-key success/failure isolation. That directly supports product surfaces like "sync 500 contacts," "refresh all connected accounts," or admin health dashboards — where one failing record must not fail the batch. Worth noting the constraint: real concurrency requires the REST client or a custom BatchClientInterface — the GraphQL adapter does not batch in parallel.

Reliability and rate-limit posture as a first-class feature. The middleware pipeline (rate limiting, retries, circuit breaking) means "we will not get banned by vendor X" and "we degrade gracefully" can be accepted as product requirements rather than aspirational engineering tickets.

Support-cost attribution when a customer reports slowness (new in v9.4.0). The new ResponseReceived lifecycle event cleanly separates the vendor took 4 seconds from our mapper took 4 seconds: ResponseReceived fires when the client returns a response and before mapping, so ResponseMapped::timestamp − ResponseReceived::timestamp is our own processing time and the rest is resolution + auth + middleware + transport. That turns "integration X is slow" from a two-day investigation into a dashboard query, and it gives you evidence for vendor SLA conversations rather than a hunch. ResponseReceived followed by RequestFailed is also a distinct, diagnosable signal: the vendor answered correctly and our mapping broke — a different owner, a different ticket, and a different fix than a transport failure. This is the kind of instrumentation that decides whether you renew or escalate a vendor, so it's worth capturing as a product requirement on new integrations rather than an afterthought.

Honest friction point: the framing here is Symfony, not Laravel. There is no Laravel service provider or Laravel-shaped config story. If the roadmap runs on Laravel, this package is not a candidate without an adapter layer — that is a hard gate, not a trade-off.

When to Consider This Package

Adopt when most of these hold:

• The stack is Symfony 6.4+ on PHP 8.2+, with the standard bundle/Flex setup.
• You maintain (or expect to maintain) three or more external HTTP integrations, or two plus a strong expectation of growth.
• Integrations are heterogeneous — REST plus GraphQL, or REST plus dynamic OAuth2 — and you want one mental model across them.
• More than one engineer touches integrations, or you rotate people onto them.
• You want the vendor boundary enforced by convention and directory structure, not by code review vigilance.
• Reliability concerns (rate limits, token expiry, partial batch failure) are real enough to justify a middleware pipeline.
• You need per-stage latency attribution — vendor vs. our own mapping — for SLA tracking, support triage, or a "which integration is slow" dashboard. As of v9.4.0 this is built in via the ResponseReceived event; previously you would have had to instrument each adapter yourself.
• You can accept a young, single-maintainer dependency, isolated behind your own facades so it never leaks into controllers or domain code.

Look elsewhere when any of these hold:

• Laravel is your framework. This is a Symfony bundle; there is no meaningful Laravel story.
• You have one integration, or a single vendor SDK already covers it. The abstraction cost outweighs the payoff.
• The work is heavier than request/response: ETL, event-driven pipelines, webhook ingestion at scale, message queues, long-running sync jobs. This package maps a call; it does not orchestrate a data platform.
• You want an SDK generated from OpenAPI/GraphQL schemas. This is hand-authored per action, not generated.
• Procurement or compliance requires an audited, widely-adopted dependency with multiple maintainers. Ten stars and zero dependents is not that.
• You need a mature community — Stack Overflow answers, third-party extensions, battle-tested edge cases. Compare against just using Symfony HttpClient directly with a thin in-house convention, or a longer-established alternative.
• Your team would rather own a ~200-line internal abstraction than adopt a framework with a learning curve and its own vocabulary.

Practical adoption path: pilot on one low-risk, read-only integration. Wrap it behind a facade and a Gateway from day one. That gives you a real cost baseline and a clean exit — the package's own architecture makes it replaceable, which is unusual and worth exploiting.

How to Pitch It (Stakeholders)

To executives — the business case in five lines:

1. Lower cost per integration. A scaffolded, uniform template means new third-party APIs cost roughly the same each time, instead of being re-litigated. Forecastable rather than exploratory.
2. Cheaper vendor changes. The enforced Anti-Corruption Layer means swapping a payment, CRM, or data provider touches one adapter class, not the domain model. That is negotiating leverage and roadmap insurance.
3. Faster unblocking of OAuth2 features. Token handling, caching, and 401 recovery are built in, so customer-authorized integrations ship without a prerequisite platform project.
4. Problems get attributed to the right party. Built-in timing tells us whether a slow integration is the vendor's fault or ours, so support tickets route correctly and SLA escalations come with numbers. Our own mapping failures are visibly ours — the vendor answered — which is exactly what you want when a renewal or a penalty clause is on the table.
5. Bounded risk. MIT-licensed, small surface area, and deliberately isolated behind our own interfaces. If the project stalls, replacing it is a contained engineering task, not a rewrite.

To engineering — why it earns its place:

• One predictable layout per integration; if you know one, you know them all. Onboarding and code review get cheaper.
• Typed request/response DTOs and an explicit mapper — no ad-hoc HTTP scattered through services.
• Middleware pipeline with ordered hooks for rate limiting, retries, circuit breaking, and logging — resilience as configuration rather than copy-paste.
• Lifecycle events now give a real timing breakdown: RequestSent → ResponseReceived (resolution, auth, middleware, transport) → ResponseMapped (mapping). Emitted for send() and for each sendMany() item, so a slow batch key is identifiable.
• sendMany() for parallel fan-out with per-request failure isolation, keyed results.
• Pluggable clients (rest, graphql, custom ClientAdapterInterface) and PathResolvableContextInterface for non-trivial query strings — the abstraction bends rather than breaks.
• Enforced boundary: application code depends on Gateways, never on integration DTOs. A vendor breaking change stops at one class.
• Developer tooling is maintained, not abandoned — debug:integration was just fixed for the v9.3.0 defaults: YAML section, so introspection works on current-format configs.

The caveats to state plainly, not bury:

• This is Symfony-only. If any part of the estate is Laravel, that part is out of scope.
• Maturity is early: ~10 stars, no dependents, one maintainer, pre-widespread adoption. Treat it as a well-designed pattern library you are adopting deliberately, not an ecosystem standard.
• The event API is still settling. v7 had HttpResponseReceived; the v8 rework dropped it; v9.4.0 has restored the same capability as ResponseReceived. That is healthy maintenance, but it is also a signal: anything asserting an exact event sequence — custom listeners, dashboards, alerting rules — can shift between minor releases. Test against event presence, not event order, and re-read the changelog before bumping.
• Budget a contingency: pin the version, read the source before upgrading, and be prepared to vendor or fork the core if maintenance stalls. Keep the Gateway boundary strict so that contingency stays cheap.
• Do not let the abstraction leak. The moment a controller imports an integration DTO, the exit cost and the vendor-swap benefit both evaporate.

Recommendation: approve as a piloted standard — one integration, one quarter, measured against a control integration built without it. Success criteria: time-to-first-working-integration, lines of glue code, whether a deliberate API change stays inside one class, and — now that the tooling supports it — whether a "this integration is slow" question can be answered from telemetry without a code investigation.