Saloon Laravel Package

Technical Evaluation

Architecture Fit

Saloon is a highly specialized HTTP client abstraction layer designed to replace ad-hoc Guzzle/cURL implementations with a structured, maintainable SDK framework. It aligns well with Laravel’s ecosystem due to:

• PSR-18 Compliance: Leverages Symfony’s HTTP client under the hood, ensuring compatibility with Laravel’s DI container and HTTP stack.
• Laravel-Specific Enhancements: Features like psrResponse header handling (v3.15.0) and macroable traits (v3.15.0) integrate seamlessly with Laravel’s service providers and Facades.
• Modular Design: Encourages domain-specific connectors (e.g., StripeConnector, ShopifyConnector) that can be registered as Laravel services, promoting SOLID principles and testability.
• Middleware Support: Aligns with Laravel’s middleware pipeline (e.g., logging, retries, auth) via handler stacks (v3.15.0), enabling reuse of existing Laravel middleware.

Key Misalignments:

• Overhead for Simple APIs: If your use case involves <3 APIs with minimal auth/retries, Saloon’s abstraction may introduce unnecessary complexity.
• Learning Curve: Requires adoption of Saloon’s DSL (e.g., Request, Connector, Response) and testing patterns (e.g., MockClient), which may slow down teams unfamiliar with the package.

Integration Feasibility

Critical Dependencies:

• PHP 8.1+: Required for modern Saloon features (e.g., attributes, enums).
• Symfony HTTP Client: Core dependency; conflicts unlikely but require version alignment.
• Laravel 9+: For full PSR-18/PSR-7 integration (e.g., psrResponse in v3.15.0).

Technical Risk

Key Questions for the Team:

1. Auth Complexity: Do we need multi-authenticator support (v3.4.0) or custom OAuth flows beyond Saloon’s defaults?
2. Error Handling: Should we extend Saloon’s exceptions (e.g., PaymentRequired in v3.10.0) or layer Laravel’s Handler?
3. Observability: How will we log/monitor Saloon requests? (e.g., middleware for OpenTelemetry or Laravel’s logging).
4. Deprecations: Are we prepared to migrate from deprecated methods (e.g., sendAndRetry in v3.6.4)?
5. Testing Strategy: Will we use Saloon’s fixtures or integrate with Laravel’s Mocker (e.g., for database-backed APIs)?

Integration Approach

Stack Fit

Saloon is optimized for Laravel due to:

• PSR-18/PSR-7 Compliance: Works natively with Laravel’s HTTP client and Symfony’s components.
• Facade/Service Provider Support: Can be exposed as a Saloon Facade or injected via DI.
• Laravel-Specific Features:
  • Config Integration: Endpoints, timeouts, and auth can be managed via config/saloon.php.
  • Cache Integration: Responses can be cached using Laravel’s cache drivers (e.g., Redis).
  • Queue Integration: Long-running requests (e.g., file uploads) can be queued with Laravel Queues.
  • Validation: Response data can be validated using Laravel’s Validator or Form Requests.

Non-Laravel Stacks:

• Symfony: Near-perfect fit due to PSR compliance.
• Lumen: Possible but requires manual setup (no built-in Facade support).
• Non-PSR Frameworks: Higher effort due to missing DI/HTTP client abstractions.

Migration Path

Example Migration:

// Before (Guzzle)
$client = new GuzzleClient();
$response = $client->request('GET', 'https://api.example.com/data', [
    'headers' => ['Authorization' => 'Bearer ' . $token],
]);

// After (Saloon)
class GetDataRequest extends Request {
    protected Method $method = Method::GET;
    protected string $endpoint = 'data';
    protected ?string $authToken = null;

    public function resolveEndpoint(): string {
        return $this->endpoint;
    }

    public function defaultHeaders(): array {
        return ['Authorization' => 'Bearer ' . $this->authToken];
    }
}

$connector = new ExampleConnector();
$response = $connector->send(new GetDataRequest(['authToken' => $token]));

Compatibility