Saloon Laravel Package

Technical Evaluation

Architecture fit

Saloon is a class-based HTTP client abstraction for Laravel/PHP (Guzzle-backed, PSR-18 compatible) that wraps third-party APIs into testable Connector/Request/Response objects. It sits in the service-integration layer of a typical Laravel application, replacing ad-hoc Http:: calls with encapsulated, mockable classes. v4.5.0 adds a HasApiVersion trait for API versioning — an additive, opt-in capability that formalises something teams currently handle by hand (version strings embedded in base URLs, paths, headers, or query params). Architecturally this is a good fit: it lets version be declared as connector/request configuration rather than scattered through request-building logic, which improves consistency and makes version pinning auditable.

Integration feasibility

Low effort. This is a semver-minor release within the v4 line, so existing consumers can bump the constraint (e.g. ^4.4 → ^4.5) and take it with no code changes. The trait is opt-in and does not alter existing Connector or Request behaviour. The main integration work is not adoption of the dependency but adoption of a convention — deciding where and how version is expressed per upstream API.

Technical risk

Low-to-moderate, and almost entirely organisational rather than technical:

• Additive trait, no breaking changes, no deprecations announced in this release.
• Risk of inconsistent usage: some connectors versioned via trait, others hardcoded, creating drift.
• The trait's API surface is new and unproven at scale; it may be reshaped in v5, so treat it as a soft commitment and avoid deep coupling in long-lived shared packages.
• Upstream version deprecation/sunset handling is still a manual concern — the trait expresses which version, not when it expires.
• The release notes are extremely terse (single PR, no docs link, no migration note). Behavioural details must be confirmed from source/tests before standardising on it.

Key questions

1. Does HasApiVersion support version placement in path vs. header vs. query, or is one style assumed?
2. Can version be overridden per-request, or is it fixed at the connector level only?
3. Does it compose cleanly with existing Saloon traits (auth, caching, retries, rate limiting)?
4. What is the minimum supported PHP/Laravel version for v4.5.0, and does it match our runtime matrix?
5. Is there first-party documentation for the trait, and is it covered by tests?
6. Should we standardise on this now, or wait one or two minor releases for the API to settle?
7. How do we detect upstream version sunset so the trait's value doesn't become stale configuration?

Integration Approach

Stack fit

Fits standard Laravel projects using Saloon for outbound integrations. No new runtime dependency, no service, no infrastructure change — it is a library-level concern contained within application code.

Migration path

• Existing v4 users: update the Composer constraint to ^4.5, run the test suite, ship. No source changes required.
• Teams on v3: this release is not a reason to migrate; a v3→v4 upgrade is a separate, larger effort and should be scoped independently.
• Adoption of the trait is incremental and per-connector; there is no all-or-nothing cutover.

Compatibility

Additive and backward compatible. Existing connectors, request classes, mocking/recording, and PSR-18/Guzzle interop are unaffected. The only compatibility question is forward-looking: pin the constraint to ^4.5 (not >=4.5) so a future v5 trait redesign surfaces as an explicit upgrade decision rather than a surprise.

Sequencing

1. Bump Composer constraint, run full test suite, confirm green in CI.
2. Read the trait source and tests; write a one-page internal usage note.
3. Pilot on a single connector that talks to a versioned upstream API.
4. Define the team convention: where version lives, how it is named, how deprecations are tracked.
5. Roll out to remaining versioned connectors behind normal PR review.
6. Add a test assertion or lint rule that every versioned connector declares a version.
7. Update internal integration docs and the onboarding checklist.

Operational Impact

Maintenance

Low. The dependency is widely used and actively maintained; the release cadence is steady but the v4 line appears stable. Ongoing cost is governance, not code: the version constants introduced via the trait become configuration that must be reviewed as upstream APIs evolve. Assign clear ownership so version bumps don't rot.

Support

Minimal. Developers already comfortable with Saloon need only a short brief on the trait and the team convention. The support burden shifts slightly toward "why is this connector calling v2 when v3 exists?" — a process question answerable with the convention document, not a code problem.

Scaling

Negligible runtime cost — this is configuration, not a hot path. It scales well organisationally: as the number of versioned integrations grows, declarative version handling is more auditable than scattered string literals. It does not, by itself, solve multi-version coexistence (calling v2 and v3 of the same API simultaneously), which should be verified as a supported pattern before relying on it.

Failure modes

• Silent drift: connector declares an old version, upstream sunsets it, integration breaks at an unpredictable time. Mitigate with scheduled review of declared versions.
• Convention divergence: trait used in some connectors, hardcoded versions in others, causing confusion during incidents.
• Wrong placement: version asserted in the wrong location (header vs. path) resulting in requests hitting an unintended endpoint.
• Trait churn: relying heavily on the trait's internals, then absorbing rework at the next major.
• Terse release note: misunderstanding of behaviour because the changelog lacks detail — mitigated by reading source and tests before rollout.

Ramp-up

Roughly half a day for a developer already fluent in Saloon to adopt the trait on one connector. One to two days of team time to agree the convention, document it, and add the accompanying tests and review checklist. No prior Saloon experience means a longer ramp on the library itself (Connector/Request/Response modelling, mocking, auth), which is unchanged by this release.