Saloon Laravel Package

Technical Evaluation

Architecture Fit

• Connector/Request-Driven Design: Aligns perfectly with Laravel’s service-oriented architecture, enabling modular API integrations (e.g., StripeConnector, TwilioRequest). This reduces coupling between business logic and HTTP clients, improving testability and reusability.
• Middleware Pipeline: Complements Laravel’s middleware stack (e.g., RetryMiddleware, LoggingMiddleware), allowing cross-cutting concerns (auth, rate limiting) to be defined once and reused across connectors.
• DTO-Friendly Responses: Integrates seamlessly with Laravel’s Eloquent models or Laravel Collections, enabling type-safe API responses (e.g., PaymentIntent::fromResponse($response->json())).
• Event-Driven Extensibility: Supports Laravel Events (e.g., ApiRequestSent, ApiResponseReceived) via middleware, enabling observability (e.g., logging, monitoring) without polluting business logic.
• API Version as a Connector Contract (new in v4.5.0): The HasApiVersion trait lets a connector declare its target vendor API version once, at the class level, instead of embedding version strings in every request path/header. This fits Laravel’s config-driven architecture: version becomes an explicit, reviewable property of the connector rather than an implicit detail buried in URLs. It also makes concurrent support of two vendor API versions (e.g., during a Stripe/AWS deprecation window) a first-class pattern — two connectors, one trait, no duplicated request classes.

Integration Feasibility

• PSR-18 Compliance: Saloon is a PSR-18 HTTP client, ensuring compatibility with Laravel’s ecosystem (e.g., HttpClient facade, Illuminate\Support\Facades\Http). Existing Laravel HTTP logic (e.g., Http::post()) can be gradually migrated to Saloon’s structured approach.
• Laravel Service Providers: Saloon connectors can be bootstrapped in Laravel’s AppServiceProvider, with connectors bound as singletons or contextual bindings (e.g., app()->bind(StripeConnector::class, fn() => new StripeConnector(config('stripe')))).
• Queueable Requests: Saloon’s async capabilities (via middleware) can integrate with Laravel Queues, enabling background API processing (e.g., webhook handlers, batch imports).
• Caching Layer: Saloon’s response caching can leverage Laravel’s cache drivers (Redis, database), reducing redundant API calls.
• Adoption Cost of Versioning (v4.5.0): Purely additive — adding use HasApiVersion; plus a $apiVersion property to the base connector is a one-file change. No refactor of existing request classes is required, and no breaking change is introduced by the release. Existing connectors continue to behave exactly as before.

Technical Risk

• Learning Curve: Saloon’s connector/request pattern may require team upskilling if developers are accustomed to Laravel’s Http facade or Guzzle. Mitigation: Pair programming and internal documentation (e.g., "Saloon vs. Guzzle" cheat sheet).
• Middleware Complexity: Over-engineering middleware pipelines could lead to performance overhead or debugging challenges. Mitigation: Start simple (e.g., auth + retries) and profile before adding custom middleware.
• Vendor SDK Conflicts: If a vendor provides a PHP SDK (e.g., Stripe’s stripe/stripe-php), duplication of effort may arise. Mitigation: Benchmark Saloon vs. vendor SDKs for maintainability (e.g., mocking, customization) before adoption.
• Security Risks: Saloon v4.0.0 fixed critical CVEs (SSRF, RCE, path traversal). Ensure dependency updates are automated (e.g., Laravel Forge, GitHub Dependabot) to avoid regression. v4.5.0 does not touch the security-sensitive surface.
• Testing Overhead: Saloon’s mocking utilities are powerful but require initial setup (e.g., defining fixtures). Mitigation: Template mocking classes for common APIs (e.g., MockPaymentGateway).
• Version Bump Blast Radius (new consideration): HasApiVersion makes a vendor version change a one-line edit. That is a benefit for maintenance but a governance risk — a trivial-looking PR can silently change every request a connector makes. Mitigation: version lives in config/env, not hardcoded; version bumps require contract tests against recorded fixtures and a changelog review.
• Release Risk Assessment (v4.5.0): Low. Single additive feature, no deprecations, no signature changes. Upgrade is a routine minor-version Composer bump; the only hard requirement is pinning ^4.5 if the team adopts the trait.

Key Questions

1. Adoption Scope:
   • Should Saloon replace all HTTP calls in Laravel (e.g., Http::get()) or only new integrations?
   • How will legacy Guzzle/HTTP facade code migrate to Saloon? (e.g., wrapper classes, incremental refactoring?)
2. Team Alignment:
   • Does the team have experience with HTTP client libraries (e.g., Guzzle, Symfony HTTP Client)?
   • Are developers comfortable with OOP design patterns (e.g., connectors as classes, middleware as traits)?
3. Performance Requirements:
   • Will Saloon’s abstraction layer introduce measurable latency? (Benchmark against raw Guzzle.)
   • Are there high-throughput APIs (e.g., real-time webhooks) where Saloon’s overhead is unacceptable?
4. Vendor SDK Strategy:
   • For APIs with official PHP SDKs (e.g., Stripe, AWS SDK), should Saloon be used as a wrapper or replacement?
   • How will SDK updates (e.g., new API endpoints) be handled in Saloon vs. vendor SDKs?
5. API Versioning Strategy (elevated by v4.5.0):
   • Do our target vendors version via URL path, header, or query string? Does HasApiVersion cover all three, or do we need per-vendor conventions on top of the trait?
   • Which APIs must support two versions concurrently, and for how long? Does the trait give us a clean way to instantiate version-specific connectors from config?
   • Should the version be hardcoded in the connector or read from config/env per environment (recommended), and who approves version bumps?
6. Observability:
   • How will Saloon integrate with Laravel Scout, Sentry, or Prometheus for monitoring?
   • Are there custom metrics needed (e.g., API response times, error rates), and should the active API version be attached as a metric tag/log context for triage?
7. CI/CD Impact:
   • How will mocking affect test speed and reliability? (e.g., unit vs. integration tests.)
   • Should Saloon’s fixtures be version-controlled per API version alongside API contracts, so a version bump fails CI when fixtures don’t exist?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • HTTP Layer: Saloon replaces or augments Laravel’s Http facade, GuzzleHttp, or Symfony HTTP Client.
  • Auth: Integrates with Laravel’s Passport, Sanctum, or custom OAuth via Saloon’s Authenticator classes.
  • Validation: Saloon responses can be validated using Laravel’s Form Requests or Pint (PHP validation library).
  • Events: Saloon middleware can dispatch Laravel events (e.g., ApiRequestFailed) for reactive workflows.
  • Config: API versions follow Laravel config conventions (e.g., config('services.stripe.version')), keeping environment-specific versions out of source control diffs.
• Testing:
  • Pest/PHPUnit: Saloon’s MockClient enables isolated API testing without external calls.
  • Test Databases: Mocked responses can simulate database-like API responses (e.g., paginated results).
  • Version-Aware Fixtures: Fixtures organised per API version (e.g., fixtures/stripe/2024-06-01/) so a version bump surfaces missing coverage immediately.
• Deployment:
  • Docker: Saloon’s environment-aware connectors (e.g., config('api.base_url')) work seamlessly with Laravel Sail.
  • Serverless: Saloon’s stateless design makes it suitable for Laravel Vapor or Bref.

Migration Path

1. Pilot Phase (Low Risk):
   • New Features Only: Use Saloon for non-critical APIs (e.g., marketing tools, analytics).
   • Wrapper Pattern: Create Saloon connectors that wrap existing Guzzle calls (e.g., new SaloonStripeConnector($guzzleClient)).
2. Incremental Replacement:
   • API by API: Migrate one API integration at a time (e.g., start with Stripe, then PayPal).
   • Feature Flags: Use Laravel’s feature() to toggle between old (Guzzle) and new (Saloon) implementations.
   • Parallel Version Support: Where a vendor has announced a deprecation, stand up V2 connectors alongside V1 using HasApiVersion, flip traffic via config, and retire the old connector after the sunset date.
3. Full Adoption:
   • Deprecate Http Facade: Replace all Http::get() calls with Saloon connectors.
   • Custom Middleware: Replace global middleware (e.g., App\Middleware\LogRequests) with Saloon-specific middleware.

Compatibility

• PHP Version: Saloon supports PHP 8.1+, aligning with Laravel’s LTS support (8.2+).
• Laravel Versions:
  • Laravel 10/11: Full compatibility (PSR-18, Symfony HTTP Client under the hood).
  • Laravel 9: Possible but may require backporting or shimming (e.g., for Illuminate\Support\Facades\Http).
• Saloon Version Floor: HasApiVersion requires >= 4.5.0. Pin ^4.5 in composer.json if the trait is adopted; teams on 4.4.x need an explicit minor bump. No transitive dependency changes reported.
• Third-Party Packages:
  • Laravel Horizon: Saloon’s async capabilities can integrate with queues.
  • Laravel Nova: Saloon connectors can power custom Nova tools (e.g., API testing panels).
  • Laravel Scout: Use Saloon to fetch external search results (e.g., Algolia, Meilisearch).

Sequencing

1. Phase 1: Foundation (2-4 weeks)
   • Set up base Saloon connector (e.g., ApiConnector with shared middleware).
   • Decide the versioning convention now — apply HasApiVersion to the base connector and source the version from config; document path vs. header handling per vendor.
   • Define standard middleware (auth, retries, logging).
   • Create mocking templates for common APIs.
2. Phase 2: Pilot (4-6 weeks)
   • Implement 2-3 critical APIs (e.g., payment gateway, CRM).
   • Benchmark performance vs. Guzzle.
   • Train team via workshops and internal docs.
3. Phase 3: Expansion (6-12 weeks)
   • Migrate remaining APIs to Saloon.
   • Replace global HTTP logic (e.g., Http facade) with Saloon.
   • Integrate with Laravel Events and observability tools.
4. Phase 4: Optimization (Ongoing)
   • Refine middleware for performance.
   • Add custom validation (e.g., OpenAPI schema checks).
   • Expand testing coverage (e.g., chaos testing for API failures).
   • Establish a version upgrade runbook (vendor changelog → fixture update → config bump → canary).

Operational Impact

Maintenance

• Pros:
  • Centralized Configuration: API endpoints, auth, timeouts, and now API version are defined once in connectors.
  • Reduced Duplication: Shared middleware and base connector eliminate copy-pasted HTTP logic across integrations.
  • Cheaper Vendor Deprecations: Responding to a vendor version sunset is a config change plus fixture updates, not a discovery-and-rewrite exercise. This is the single biggest long-term maintenance win from v4.5.0.
  • Traceable Change History: Version declarations show up in code review, unlike version strings buried in URL literals.
• Cons:
  • Dependency Cadence: The team now tracks Saloon’s release cycle (currently frequent minor releases). Low cost today, but it is a recurring obligation.
  • Convention Debt: The trait is opt-in with no enforcement — without a lint/review rule, some connectors will declare a version and others won’t. Add it to the PR checklist.
  • Upgrade Testing: Minor releases still require a regression pass on mocked suites before deploy.

Support

• Vendor Documentation: Saloon’s docs are thorough and current; HasApiVersion usage should be captured in the internal "Saloon vs. Guzzle" cheat sheet.
• Community: Active maintainer and contributor base (evidenced by steady PR flow such as #564); GitHub issues are the primary support channel.
• Internal Ownership: Assign a single owning team for the shared base connector and middleware stack; otherwise versioning conventions and middleware sprawl diverge per squad.
• Upgrade Policy: Adopt a documented policy — patch/minor within a sprint, majors with a migration ticket. Security advisories (per the v4.0.0 CVEs) trigger immediate patching.
• Escalation: For vendor-side versioning surprises, the trait makes rollback a config revert rather than a code revert — a material support-desk simplification.

Scaling

• Horizontal: Stateless connectors scale cleanly across Vapor/Bref and container replicas; no shared state to coordinate.
• Throughput: Middleware is the only added per-request cost — keep the pipeline lean (auth, retry, logging) and benchmark before adding tracing/metrics layers.
• Multi-Integration Growth: Costs scale sublinearly — each new integration reuses the base connector, middleware, and versioning convention. The Nth integration is significantly cheaper than the first.
• Multi-Version and Multi-Region: HasApiVersion lets one codebase address multiple vendor versions or regional API surfaces without branching request logic, which keeps the operational surface flat as the integration count grows.
• Queue Backpressure: Async/queued requests must have bounded retries and dead-letter handling; otherwise a degraded vendor endpoint converts into queue saturation.

Failure Modes

• API Version Mismatch / Sunset: The most likely new failure mode. A vendor retires a version and calls begin returning 400/410 en masse. Mitigation: the trait makes the active version explicit; add contract tests, monitor vendor deprecation notices, and alert on version-specific error spikes.
• Silent Response Shape Change: A vendor changes a field within a version. Mitigation: DTO hydration with strict validation so malformed payloads fail loudly, not silently null.
• Auth Token Expiry / Rotation: Expired credentials produce 401 storms. Mitigation: Authenticator classes with refresh logic and alerting on 401 rate.
• Rate Limiting (429): Batch jobs can trip vendor limits. Mitigation: retry middleware with exponential backoff and jitter; queue-level concurrency caps.
• Retry Storms: Retries amplifying an outage. Mitigation: circuit breaker middleware, capped attempt counts, idempotency keys on non-GET requests.
• Middleware Misconfiguration: A missing logging or auth middleware is silent until an incident. Mitigation: base connector sets defaults; connectors opt out explicitly rather than opt in.
• Dependency Regression: A future Saloon release introduces a behavioural change. Mitigation: version pinning in composer.json, automated dependency updates with CI gates, and a mocked regression suite.
• Version Bump Error (operational): Someone bumps $apiVersion in the wrong environment or without fixtures. Mitigation: version sourced from config, environment-scoped, with fixture coverage required for any new version value.

Ramp-up

• Individual Developer: A Laravel developer familiar with Guzzle reaches productivity on connectors and requests in 1–2 days; middleware authoring and mocking patterns take ~1 week.
• Team: Budget 2–3 weeks end-to-end for the pilot squad — workshops, internal docs, base connector conventions, and the first two integrations. The versioning convention adds negligible additional time if decided in Phase 1; retrofitting it later costs materially more.
• Organizational: Non-trivial portion of ramp-up is convention alignment (versioning, middleware ownership, fixture standards), not framework learning. Front-load that in Phase 1 documentation.
• Upgrade Ramp: v4.5.0 itself requires no training — it is opt-in and additive. Adopt it opportunistically when the base connector is next touched, or in Phase 1 if that hasn't shipped yet.