Weave Code
Saloon Laravel Package
saloonphp/saloon
Saloon is a PHP HTTP client framework for building clean, reusable API integrations. Create connectors and requests, handle auth, middleware and retries, mock and test easily, and keep endpoints organized with strong typing and a fluent DX.
Build beautiful API integrations and SDKs with Saloon
Frequently asked questions about Saloon
- How does Saloon integrate with Laravel’s HTTP middleware like TrustProxies or CORS?
- Saloon’s middleware pipeline works alongside Laravel’s HTTP middleware, but conflicts can occur if both try to modify the same request/response. Use Saloon’s middleware priority settings or wrap Saloon requests in Laravel’s `HttpClient` for seamless integration. For CORS, configure Saloon’s middleware to mirror Laravel’s `HandleCors` behavior.
- Can I use Saloon with Laravel’s Sanctum or Passport for OAuth2 authentication?
- Yes, Saloon supports OAuth2 via its `OAuth2` authenticator, but you’ll need to bridge it with Laravel’s Sanctum/Passport for user contexts. Store tokens in Laravel’s cache or database, then pass them to Saloon’s requests. Hybrid setups (e.g., Saloon for API tokens, Sanctum for user auth) are common.
- What’s the best way to mock Saloon requests in Laravel’s Pest/PHPUnit tests?
- Saloon provides built-in mocking via `MockConnector` and `MockResponse`. For Pest/PHPUnit, use `Saloon::mock()` to simulate API responses without hitting endpoints. Combine with Laravel’s `Http::fake()` for hybrid testing. Example: `$this->mock(ExampleConnector::class, fn() => MockResponse::make('data'));`
- Does Saloon work with Laravel Queues for async API calls?
- Absolutely. Dispatch Saloon requests as Laravel jobs by wrapping them in a `ShouldQueue` job. Use `Saloon::connect()` inside the job’s `handle()` method. For retries, leverage Laravel’s queue retry mechanisms or Saloon’s built-in retry logic with `sendAndRetry()`.
- How do I handle rate limits or exponential backoff in Saloon?
- Saloon includes retry middleware (`RetryMiddleware`) with configurable backoff strategies. For rate limits, use `RateLimitMiddleware` to track and respect API limits. Combine with Laravel’s cache to persist rate limit states across requests. Example: `$this->withMiddleware([new RetryMiddleware(), new RateLimitMiddleware()]);`
- What Laravel versions and PHP versions does Saloon officially support?
- Saloon supports Laravel 10+ and PHP 8.1+. For older Laravel versions (9.x), use Saloon v3.x. PHP 8.0 is supported but lacks modern features like enums. Check the [Saloon changelog](https://github.com/saloonphp/saloon/blob/main/CHANGELOG.md) for version-specific notes.
- Can I use Saloon with Lumen instead of Laravel?
- Yes, Saloon is framework-agnostic but works well with Lumen. Register connectors via Lumen’s service provider or bootstrappers. For queues, use Lumen’s queue system or Saloon’s standalone retry logic. Avoid Laravel-specific features like `Http::macro()` in Lumen.
- How does Saloon compare to Laravel’s built-in HttpClient for API integrations?
- Saloon offers more structure for complex APIs (e.g., connectors, SDKs, middleware) while Laravel’s `HttpClient` is simpler for one-off requests. Saloon excels in reusable auth, retries, and testing, but `HttpClient` may suffice for basic APIs. Use Saloon for SDKs (e.g., Stripe) and `HttpClient` for lightweight calls.
- Are there performance concerns when using Saloon in high-throughput APIs (e.g., webhooks)?
- Saloon adds minimal overhead compared to Guzzle or Symfony’s `HttpClient`. For webhooks, benchmark Saloon against Laravel’s `HttpClient` or raw Guzzle. Optimize with connection pooling (e.g., `HttpClient` pool) or async processing via Laravel Queues.
- What’s the migration path from Guzzle or Symfony HttpClient to Saloon?
- Start by wrapping legacy calls in Saloon connectors. For Guzzle, use Saloon’s `GuzzleConnector` adapter. Replace one API at a time (e.g., Stripe) to test compatibility. Use Laravel’s `DeprecatorPHP` to flag deprecated HTTP clients. Example: `new SaloonConnector(['client' => new GuzzleConnector()]);`
Weaver
How can I help you explore Laravel packages today?