Weave Code
Saloon Laravel Package
saloonphp/saloon
Saloon is a PHP HTTP client framework for building API integrations. Define connectors and requests, handle authentication, retries, and responses, and test easily with fakes and mocking. Works great in Laravel or any PHP app.
🤠 Build beautiful API integrations and SDKs with Saloon
Frequently asked questions about Saloon
- How does Saloon compare to Guzzle or Laravel HTTP Client for API integrations?
- Saloon is a higher-level framework built on Guzzle, offering structured connectors (e.g., OAuth2, BasicAuth) and domain-driven request/response classes. Unlike Laravel’s HTTP Client, it enforces validation, mocking, and retries out of the box, making it ideal for complex SDKs. For simple requests, Laravel’s HTTP Client may suffice, but Saloon shines for maintainable, testable integrations.
- Can I use Saloon with Laravel’s Sanctum or Passport for authentication?
- Yes. Saloon supports Laravel’s token-based auth via its `BearerTokenAuthenticator`. Pair it with Sanctum/Passport by injecting the token from `auth()->user()->createToken()` into your Saloon connector. This keeps authentication logic consistent with Laravel’s ecosystem.
- What’s the best way to handle API rate limits or retries in Saloon?
- Saloon includes built-in retry logic with exponential backoff. Configure it via `withRetryConfig()` on your connector or request class. For rate limits, use `withRateLimit()` to enforce delays. Combine with Laravel’s queue system to offload retries to background jobs if needed.
- How do I mock Saloon requests in Laravel tests? Does it work with Pest or PHPUnit?
- Use Saloon’s `MockClient` alongside Laravel’s `Http::fake()`. For Pest/PHPUnit, set up mocks in your test setup: `$this->mock(Saloon::class)->shouldReceive('send')->andReturn($mockResponse)`. This works seamlessly with Laravel’s testing helpers for hybrid mocking.
- Is Saloon compatible with Laravel 10/11, and what about PHP 8.4?
- Saloon officially supports Laravel 10/11 and PHP 8.1+. For PHP 8.4, ensure your dependencies (e.g., Guzzle) are updated. Run `composer require saloonphp/saloon:^4.0` and check `composer.json` for runtime compatibility constraints.
- How can I cache API responses in Saloon with Laravel’s cache system?
- Use Saloon’s `CachedResponse` decorator to store responses in Laravel’s cache. Configure the TTL via `cache()->forever()` or `cache()->remember()`. For Redis, ensure your Laravel cache driver is set to `redis` in `.env`. This reduces redundant API calls.
- What’s the performance impact of using Saloon vs. raw Guzzle in Laravel?
- Saloon adds ~10–20ms per request due to its validation and middleware layers. For production, benchmark critical paths. Use `MockClient` in development to avoid overhead. If performance is critical, consider lazy-loading connectors or batching requests.
- Can I use Saloon for GraphQL or WebSocket APIs, or is it REST-only?
- Saloon is REST-focused but extensible. For GraphQL, wrap it in a Saloon `Request` class with raw JSON payloads. WebSockets require custom `Endpoint` classes. The core framework prioritizes REST, but its architecture supports adaptations for other protocols.
- How do I integrate Saloon with Laravel’s queue system for async API calls?
- Wrap Saloon requests in a Laravel job (e.g., `ProcessPaymentJob`). Dispatch it via `dispatch(new ProcessPaymentJob($request))`. The job can use Saloon’s `send()` method. This is ideal for long-running or rate-limited APIs.
- What are the security risks of using Saloon, and how do I mitigate them?
- Key risks include SSRF (mitigated in v4.0+) and credential leaks. Always validate URLs in custom `Endpoint` classes and avoid hardcoding secrets. Use Laravel’s `.env` for API keys and Saloon’s `Authenticator` interfaces to abstract auth logic. Run `composer audit` regularly.
Weaver
How can I help you explore Laravel packages today?