Saloon Laravel Package

Technical Evaluation

Architecture Fit

Saloon aligns well with Laravel’s dependency injection (DI), service container, and testing-first paradigms. Its connector/request/response pattern mirrors Laravel’s Eloquent/Query Builder abstractions, making it intuitive for PHP developers. The package’s plugin-based middleware system (e.g., retries, auth) integrates seamlessly with Laravel’s middleware pipeline, enabling consistent error handling and logging.

Key Fit Points:

• Framework-Agnostic but Laravel-Optimized: Works standalone but includes Laravel-specific helpers (e.g., SaloonServiceProvider, SaloonFacade).
• DTO-Friendly Responses: Leverages PHP’s typed properties and Spatie’s Data Transfer Objects (if used), reducing boilerplate for API payloads.
• Testing Utilities: Built-in mocking (MockClient) and assertions (assertSent, assertSentInOrder) align with Laravel’s HttpTests and Pest/PHPUnit workflows.

Integration Feasibility

Low to Medium Effort for Laravel projects already using:

• Guzzle/HTTP Client: Saloon wraps Guzzle but abstracts away low-level details (e.g., retries, auth).
• API Clients: Replaces ad-hoc Http::get() calls with structured, reusable connectors.
• Testing: Reduces mocking complexity for API-dependent services.

Challenges:

• Migration from Guzzle: Requires rewriting existing Http clients to Saloon’s Connector/Request pattern.
• Legacy Code: Projects using raw curl or file_get_contents will need significant refactoring.
• Laravel-Specific Features: Some Laravel integrations (e.g., HttpClient) may require wrapper classes for full parity.

Technical Risk

Key Questions for TPM

1. Adoption Scope:
   • Will Saloon replace all Http::* calls, or only new API integrations?
   • Are there legacy systems (e.g., curl) that can’t be migrated?
2. Testing Strategy:
   • How will mocking be integrated into CI/CD? (Saloon’s MockClient vs. Laravel’s Http::fake()?)
   • Will API contracts (e.g., OpenAPI) be used to auto-generate Saloon requests?
3. Error Handling:
   • How will Saloon’s exceptions map to Laravel’s HttpException/Throwable hierarchy?
   • Are custom middleware needed for logging/retries?
4. Performance:
   • Will connectors be instantiated per-request or reused (e.g., via Laravel’s singleton)?
   • Are there plans to cache responses (Saloon supports this via plugins).
5. Security:
   • How will sensitive data (e.g., API keys) be managed? (Laravel’s env() + Saloon’s defaultAuth?)
   • Are there plans to audit the v4.0.0 CVE fixes in production?

Integration Approach

Stack Fit

Saloon is optimized for:

• Laravel 10+ (PHP 8.1+): Leverages Laravel’s service container, facades, and testing tools.
• API-Heavy Applications: Ideal for SaaS, e-commerce, or platforms with 3rd-party integrations (Stripe, PayPal, etc.).
• Test-Driven Development: Mocking and assertions reduce flaky tests in CI.

Compatibility Matrix:

Migration Path

Phase 1: Pilot Integration (2-4 weeks)

1. Start with a Single Connector:
   • Migrate one high-value API (e.g., Stripe) to Saloon.
   • Compare performance vs. existing Http:: calls.
2. Leverage Laravel Helpers:
   • Bind connector to the container:

     $this->app->singleton(StripeConnector::class, fn() => new StripeConnector());
     

   • Use facades for convenience:

     $customer = Saloon::connector(StripeConnector::class)
         ->send(new GetCustomerRequest(['customer_id' => 'cus_123']));
     

3. Test Mocking:
   • Replace Http::fake() with MockClient in unit tests:

     $mock = new MockClient();
     $mock->shouldReceive('send')
         ->once()
         ->andReturn(new Response($mock, 200, [], '{"id": "123"}'));
     

Phase 2: Full Adoption (4-8 weeks)

1. Refactor API Clients:
   • Convert all Http::get()/post() to Saloon Request classes.
   • Use macros (Saloon’s Macroable trait) to add custom methods:

     GetCustomerRequest::macro('withSubscription', fn($subId) => [
         'query' => ['subscription' => $subId]
     ]);
     

2. Add Middleware:
   • Global retries, logging, or rate limiting:

     $connector->addMiddleware(new RetryMiddleware());
     

3. Deprecate Legacy Code:
   • Use Laravel’s deprecate() helper to phase out old Http::* calls.

Phase 3: Optimization (Ongoing)

• Caching: Use Saloon’s CacheMiddleware or Laravel’s cache.
• Plugins: Add rate limiting (e.g., saloonphp/rate-limiter).
• Monitoring: Track API failures with Laravel’s Sentry or Laravel Debugbar.

Sequencing

Rollback Plan:

• Maintain dual Http:: and Saloon code during transition.
• Use feature flags to toggle between implementations.

Operational Impact

Maintenance

Pros:

• Reduced Boilerplate: Saloon’s Request classes encapsulate API logic (e.g., endpoints, auth).
• Centralized Updates: Change base URLs or headers in one place (the Connector).
• Plugin Ecosystem: Retries, pagination, and auth are modular (e.g., swap OAuth2 for JWT).

Cons:

• Learning Curve: Teams must adopt Saloon’s Connector/Request pattern.
• Debugging: Stack traces may be less familiar than Guzzle’s (though Saloon improves with debug() helper).
• Dependency Updates: Saloon v4.0.0 introduced BC changes; monitor for future breaks.

Maintenance Tasks:

Support

Common Issues & Solutions: