Saloon Laravel Package

Product Decisions This Supports

• Standardized API Integration Framework: Enables the creation of a unified, maintainable SDK layer for all third-party APIs (e.g., payment gateways, CRM systems, logistics providers). This reduces technical debt by consolidating scattered HTTP clients (Guzzle, cURL, or vendor SDKs) into a single, cohesive abstraction. Aligns with initiatives to improve integration reliability and reduce bugs from inconsistent implementations.
• Accelerated Time-to-Market for API-Dependent Features: Supports roadmap items requiring rapid API integration (e.g., new payment methods, CRM syncs, or data pipelines) by eliminating boilerplate code for authentication, retries, and error handling. For example, a feature like "global checkout" could leverage Saloon’s OAuth2/PSR-18 support to integrate with Stripe, PayPal, and Adyen in parallel, reducing development time by 30–50%.
• Build vs. Buy Decision: Justifies in-house SDK development over vendor-provided SDKs when:
  • Vendor SDKs lack customization (e.g., need to override timeouts, inject middleware for logging/metrics, or handle edge cases like exponential backoff).
  • APIs require cross-cutting concerns (e.g., unified error handling, request deduplication, or multi-authenticator support) not addressed by vendor tools.
  • Testing and mocking are critical (e.g., for CI/CD pipelines or local development), and Saloon’s built-in MockClient reduces flakiness.
• Use Cases:
  • B2B/API Marketplaces: Build a white-labeled API client for partners (e.g., resellers, affiliates) to interact with your backend via Saloon-powered endpoints, with consistent authentication and rate-limiting.
  • Data Pipelines: Orchestrate ETL workflows (e.g., syncing Shopify orders to ERP systems) with Saloon’s retry logic, response validation, and middleware support for observability.
  • Legacy Modernization: Replace SOAP/XML-RPC integrations with REST/GraphQL clients while reusing existing PHP codebases, leveraging Saloon’s backward-compatible design.
  • Internal Developer Tools: Embed Saloon in admin dashboards or CLI tools (e.g., bulk user imports, audit log exports) to interact with APIs with minimal setup.
  • Microservices Communication: Use Saloon as a lightweight HTTP client for internal service-to-service communication, especially in Laravel-based architectures.

When to Consider This Package

Adopt Saloon if:

• Your team manages 5+ third-party APIs with repetitive patterns (e.g., OAuth2, pagination, rate limiting, or custom headers) and is tired of rewriting HTTP clients from scratch.
• You prioritize developer productivity for API work, as Saloon reduces boilerplate for:
  • Authentication (OAuth2, API keys, basic auth, or custom schemes).
  • Retry logic (exponential backoff, jitter, or custom conditions).
  • Response validation (PSR-7 responses, JSON/XML parsing, or custom assertions).
  • Mocking/testing (built-in MockClient for unit/integration tests).
• You need type safety and IDE support (PHP 8.1+ attributes, return type hints, and PSR-18 compliance) to catch errors early.
• Your stack is Laravel-centric or PHP-based, and you want to avoid context-switching to JavaScript/Node.js for API integrations.
• You require fine-grained control over requests (e.g., middleware for logging, metrics, or request/response transformation) without vendor lock-in.

Look elsewhere if:

• You’re using non-PHP languages (e.g., Python, JavaScript, Go) and prefer language-native solutions (e.g., requests for Python, axios for JS).
• Your APIs are extremely simple (e.g., 1–2 endpoints with no auth) and don’t justify the abstraction layer.
• You need real-time WebSocket support (Saloon focuses on HTTP/REST).
• Your team lacks PHP/Laravel expertise, as Saloon’s full potential requires familiarity with PSR standards and Laravel’s ecosystem.
• You’re bound by vendor SDKs with mandatory features (e.g., proprietary SDKs for niche hardware/embedded systems).
• You prioritize low-level control over HTTP (e.g., raw TCP sockets, custom protocols) and want to bypass Saloon’s abstractions.

How to Pitch It (Stakeholders)

For Executives: *"Saloon is a PHP-first API integration framework that lets us build and maintain third-party API connections faster, more reliably, and with less technical debt. Think of it as our ‘internal Postman’—but for developers. Instead of spending weeks writing custom HTTP clients for Stripe, Shopify, or Twilio (and then rewriting them when APIs change), Saloon gives us a standardized, reusable SDK layer. This directly impacts:

• Faster feature launches: Cut API integration time by 30–50% for new projects (e.g., multi-currency payouts, CRM syncs).
• Lower risk: Reduce bugs from inconsistent implementations with built-in retries, validation, and mocking.
• Cost savings: Avoid vendor lock-in by controlling our API clients in-house, while still supporting OAuth2, rate limiting, and custom auth.
• Scalability: Easily add new APIs (e.g., for partnerships or data pipelines) without hiring specialized backend engineers. For example, if we’re expanding to Europe, Saloon lets us integrate with local payment gateways like Klarna or Adyen in days, not weeks. It’s a force multiplier for our API-heavy roadmap."*

For Engineering Leaders: *"Saloon solves three critical pain points in our API ecosystem:

1. Boilerplate Hell: No more copying/pasting Guzzle clients or vendor SDKs. Saloon’s declarative syntax (PHP attributes, connectors, and requests) lets us define APIs in 10–20 lines what would take 100+ lines with raw Guzzle.
2. Testing Nightmares: Built-in MockClient means we can unit test API calls without hitting real endpoints, speeding up CI/CD and reducing flaky tests. Plus, its assertion methods (e.g., assertSent(), assertResponse()) catch integration issues early.
3. Maintenance Overhead: Centralized error handling, retries, and middleware (e.g., logging, metrics) mean one change fixes it across all APIs. For example, if we need to add request deduplication, we do it once in Saloon, not per API. Key differentiators vs. alternatives:

• More PHP-native than Guzzle: Designed for Laravel/PHP, with PSR-18 compliance and Laravel-specific features (e.g., service provider integration).
• Better for testing: Mocking is first-class, unlike Guzzle or HTTP clients that require external libraries.
• Future-proof: Actively maintained (v4.0.0 released in 2026), with support for PHP 8.5 and modern features like macroable traits for customization. Recommendation: Pilot Saloon for 2–3 high-priority APIs (e.g., Stripe, Shopify) to validate the productivity gains. If successful, we can migrate all third-party integrations to Saloon within 3–6 months, saving engineering time and reducing tech debt."*

For Developers: *"Saloon is like Laravel’s answer to Retrofit (Android) or OpenAPI generators—but for PHP. Here’s why it’s a game-changer:

• Write Less, Do More: Define an API in one class with type hints, attributes, and methods. Example:

  #[OAuth2('stripe_auth')]
  class CreateCustomerRequest extends Request {
      public function resolveEndpoint(): string {
          return '/v1/customers';
      }
  
      public function method(): string {
          return 'POST';
      }
  
      public function data(): array {
          return ['name' => $this->name, 'email' => $this->email];
      }
  }
  

  No more manually building URLs, headers, or JSON payloads.
• Built-in Superpowers:
  • Mocking: Test API calls without hitting real endpoints (critical for CI/CD).
  • Middleware: Add logging, metrics, or request transformations globally (e.g., Saloon\Traits\HasMiddleware).
  • Auth Made Easy: Support for OAuth2, API keys, basic auth, and custom authenticators.
  • Retries & Timeouts: Exponential backoff, jitter, and circuit breakers out of the box.
• Laravel Love: Works seamlessly with Laravel’s service container, config, and events. Example: Use Saloon in a command or queue job like this:

  public function handle() {
      $response = app(CreateCustomerRequest::class)
          ->name('John Doe')
          ->email('john@example.com')
          ->send();
  
      $customer = $response->json();