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.

• 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").

• 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.

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.
• 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).

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. 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).
• 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. We’ll also audit all API calls via middleware (e.g., log all PII transmissions)."*