Laravel Plugin Laravel Package

Product Decisions This Supports

• API-Centric Architecture: Accelerates development of reusable, contract-driven API clients for third-party services (e.g., payment processors, SaaS platforms, or internal microservices). Aligns with roadmaps prioritizing integration density (e.g., B2B partnerships, webhooks, or real-time data pipelines).
• Technical Debt Reduction: Replaces ad-hoc HTTP clients (e.g., raw Guzzle instances) with maintainable, testable abstractions, reducing long-term costs for API maintenance.
• Build vs. Buy: Justifies not building custom API client libraries when Saloon’s features (contracts, connectors, middleware, and mocking) meet 80% of requirements. Avoids reinventing wheels for:
  • Authentication (OAuth, API keys).
  • Retry/backoff logic.
  • Request/response validation.
  • Observability (Telescope/Laravel Pulse integration).
• Use Cases:
  • B2B Integrations: Standardize interactions with partners (e.g., ERP, CRM, or logistics APIs) using shared contracts and centralized error handling.
  • Legacy Modernization: Refactor monolithic API clients into modular, testable components with minimal risk.
  • Developer Productivity: Reduce onboarding time for engineers by providing CLI scaffolding (saloon:connector, saloon:request) and IDE support (e.g., ide.json for autocompletion).
  • Compliance/Security: Handle sensitive data (e.g., tokens, PII) via Saloon’s built-in masking and middleware (e.g., Nightwatch for request/response inspection).
  • Scalability: Leverage Laravel’s service container to dynamically bind connectors, enabling runtime API configuration (e.g., feature flags for experimental APIs).

When to Consider This Package

• Adopt if:

  • Your Laravel app interacts with 5+ third-party APIs where >30% of code is duplicated (e.g., auth headers, retries, payload validation).
  • You need contract-first development to enforce API specifications (e.g., OpenAPI/Swagger) as PHP interfaces before implementation.
  • Your team prioritizes testability: Saloon’s mocking and contract testing reduce flaky tests tied to external APIs.
  • You’re using Laravel 10+ and want native integration with:
    • Service containers (dependency injection).
    • Queues (async API calls).
    • Events (e.g., webhook listeners).
    • Observability tools (Telescope, Pulse, or custom middleware).
  • You require advanced features:
    • OAuth 2.0/1.0 flows.
    • Rate limiting or circuit breakers.
    • Request/response transformation (e.g., JSON:API, GraphQL).
    • Sensitive data handling (e.g., token masking).
  • Your APIs have non-trivial error handling (e.g., custom retries, fallback logic).

• Look elsewhere if:

  • Your APIs are simple CRUD endpoints with no shared logic (e.g., one-off requests to a single service). Overhead of Saloon’s abstractions may not justify benefits.
  • You’re locked into Laravel <9 or using a non-PHP backend (e.g., Node.js, Go). Saloon is PHP-first.
  • Your team lacks PHP 8.1+ support (minimum requirement for Saloon v3).
  • You need real-time WebSocket support (Saloon focuses on HTTP; consider Laravel Echo or Pusher).
  • Your API interactions are primarily internal (e.g., inter-service calls via Laravel’s HTTP client). Native Laravel features (e.g., HttpClient) may suffice.
  • You require low-level control over HTTP (e.g., raw TCP sockets, custom protocols). Saloon abstracts away low-level details.

How to Pitch It (Stakeholders)

For Executives: "This package lets us build API integrations 3x faster while reducing bugs and maintenance costs. Instead of writing custom HTTP clients for every third-party service (e.g., Stripe, Salesforce, or our partner APIs), we’ll use Saloon’s reusable framework to handle auth, retries, and validation—freeing engineers to focus on business logic. It also integrates seamlessly with our Laravel stack, so we get built-in observability (via Telescope/Pulse) and scalability (async queues, service containers). For example, if we’re adding 5 new B2B integrations this quarter, Saloon could cut development time by 40% while improving reliability."

For Engineering Leaders: *"Saloon’s Laravel plugin gives us:

• Contract-first API development: Define interfaces for APIs before implementing them, catching mismatches early.
• CLI-powered scaffolding: Generate connectors, requests, and auth classes in seconds (saloon:connector, saloon:request).
• Testability: Mock external APIs locally with Saloon::fake(), eliminating flaky tests tied to real services.
• Laravel-native integrations: Works with queues, events, and observability tools (Telescope, Pulse) out of the box.
• Security: Built-in middleware for masking sensitive data (e.g., tokens) and inspecting requests/responses (Nightwatch).

Tradeoff: It’s not for trivial APIs, but for any non-crud or high-churn integration, it’s a net win. Let’s pilot it on our [highest-priority API] to measure the impact."*

For Developers: *"This is like Laravel’s HTTP client on steroids:

• No more copy-pasting Guzzle code for every API. Define a contract once, reuse it everywhere.
• Automatic scaffolding: Run php artisan saloon:connector stripe and get a full OAuth-ready client with tests.
• Debugging made easy: Use Telescope or Nightwatch middleware to inspect every API call in real time.
• Mocking: Test your app’s API interactions without hitting external services (e.g., Saloon::fake()).
• Future-proof: Supports PHP 8.5, Laravel 13, and modern features like sensitive data handling.

Example workflow:

# Generate a new connector
php artisan saloon:connector --oauth github

# Create a request
php artisan saloon:request GetUserRepos --connector=github

# Test locally (no real API calls!)
Saloon::fake([
    GetUserRepos::class => fn() => ['repos' => [...]],
]);
```"*