Saloon Laravel Package

Product Decisions This Supports

• Unified API Integration Layer: Replace ad-hoc HTTP clients (e.g., Guzzle instances scattered across services) with a standardized, typed SDK framework for all external APIs. Saloon’s connector/request architecture enforces consistency in auth, retries, and validation, reducing technical debt in microservices or monoliths.

• API Versioning and Migration Strategy (new in v4.5.0): The new HasApiVersion trait lets us declare the API version once on a connector rather than hardcoding version strings across every request class. Product implications:

  • Cheaper vendor version upgrades: When a vendor (Stripe, HubSpot, internal platform) ships a new API version, we change it in one place and stage the rollout per-connector instead of auditing dozens of call sites.
  • Parallel version support during migrations: We can run v2 and v3 connectors side-by-side during a deprecation window, derisking cutovers and giving us a clean rollback path.
  • Tighter roadmap sequencing: Version bumps become a small, schedulable task rather than an unbounded refactor — useful input when negotiating vendor deprecation timelines.

• Accelerated Feature Delivery:

  • Multi-API Features: Build cross-API workflows (e.g., "sync customer data across HubSpot, Salesforce, and Zendesk") with shared middleware (e.g., rate limiting, logging) and composable requests.
  • Rapid Prototyping: Use mocking to develop against APIs before contracts are finalized (e.g., testing a new payment processor before go-live).
  • Legacy System Modernization: Gradually replace spaghetti HTTP calls in legacy PHP apps with Saloon’s structured requests, improving maintainability.

• Observability and Debugging:

  • Centralized Error Handling: Standardize API error responses (e.g., map vendor-specific errors to domain exceptions) via response middleware.
  • Request Tracing: Instrument Saloon’s debug helpers and mock assertions to correlate API calls with business events (e.g., "Failed Stripe charge → trigger refund workflow").
  • Version-Aware Diagnostics: With versioning centralized, logs and traces can attribute failures to a specific API version, shortening incident triage during vendor-side rollouts.

• Cost Optimization:

  • Avoid Vendor SDK Bloat: Replace bloated vendor SDKs (e.g., Shopify, Twilio) with lightweight Saloon wrappers when only 20% of SDK features are used.
  • Internal API Standardization: Use Saloon to expose internal APIs (e.g., microservices) with the same rigor as external ones, reducing duplication.

• Security and Compliance:

  • Auth Centralization: Manage OAuth, API keys, and tokens via Saloon’s authenticator stack, reducing credential leakage risks.
  • CVE Mitigation: Leverage Saloon’s v4 security patches (e.g., SSRF fixes, deserialization safeguards) to inherit security updates without manual audits.
  • Reduced Version-Drift Risk: Centralized version declarations make it harder to leave stale, unsupported API versions in production — a common compliance finding.

When to Consider This Package

Adopt Saloon if:

• Your team maintains >5 external API integrations and suffers from inconsistent HTTP clients (e.g., mixed Guzzle/HTTP_Client usage).
• You need mocking for CI/CD (e.g., testing webhooks or async APIs without hitting live endpoints).
• Your APIs require custom middleware (e.g., retry logic, request/response transformation) not supported by vendor SDKs.
• Vendors version their APIs on a schedule and you need a low-cost way to pin, stage, and roll forward versions (HasApiVersion, v4.5.0+).
• You’re building internal tools or SDKs for other teams (e.g., a "Payments SDK" used by frontend and backend services).
• Your stack is PHP-centric (Laravel, Symfony, or custom PHP), and you want to avoid JavaScript/Go SDKs for backend integrations.

Look elsewhere if:

• You’re heavily invested in a vendor SDK (e.g., Stripe PHP SDK) and its features (e.g., Webhook signing) are critical.
• Your APIs are graph-heavy (e.g., GraphQL) or require WebSocket support (Saloon focuses on REST).
• Your team lacks PHP expertise—Saloon’s type safety and macros require familiarity with modern PHP (8.1+).
• You need low-level control (e.g., raw TCP sockets) or non-HTTP protocols (e.g., gRPC).
• You need header-level, per-request version negotiation across many versions simultaneously in the same connector — the trait is a connector-level convenience, not a full version-negotiation framework. Verify it fits before committing.

How to Pitch It (Stakeholders)

For Executives: *"Saloon lets us build API integrations faster and more reliably—like a ‘Laravel for HTTP clients.’ Instead of reinventing the wheel for every API (e.g., Stripe, Twilio, internal services), we’ll use a single, standardized framework to:

• Cut dev time by 30% for new API features (e.g., unified checkout).
• Reduce bugs with built-in mocking and validation.
• Save costs by avoiding vendor SDK licenses where possible.
• Absorb vendor API version changes cheaply—v4.5.0’s versioning support means a version bump is a one-line change, not a project. It’s like using PostgreSQL for databases—one tool, consistent across the company."*

For Engineers: *"Saloon gives us:

• Clean, typed API clients (no more magic Guzzle calls in controllers).
• Middleware pipelines for retries, logging, and auth (reusable across projects).
• First-class mocking to test APIs in isolation (critical for webhooks/CI).
• Declarative API versioning via the new HasApiVersion trait (v4.5.0) — set the version on the connector, not in every request.
• PHP 8.5+ support and modern tooling (PHPStan, PSR-18 compliance). Example: Instead of this:

$response = Http::withToken($apiKey)->post('https://api.example.com/orders', $data);

We’ll use:

$order = (new CreateOrderRequest())->send();

With automatic auth, validation, and retries—and 100% test coverage via mocks."*

For Security/Compliance: *"Saloon’s v4 security patches (e.g., SSRF fixes, deserialization protection) and centralized auth management reduce risks from:

• Hardcoded API keys in legacy code.
• Inconsistent error handling exposing sensitive data.
• Vendor SDK vulnerabilities we can’t patch ourselves.
• Stale, unsupported API versions lingering in production — v4.5.0 centralizes version declarations so drift is visible and auditable. We’ll also audit all API calls via middleware (e.g., log all PII transmissions)."*