| name | saloon-development |
| description | Build and work with SaloonPHP API integrations, including connectors, requests, and responses. |
SaloonPHP Development
When to use this skill
Use this skill when working with SaloonPHP features:
- Creating API integrations or SDKs
- Building connectors or requests
- Working with authentication, middleware, or responses
- Implementing pagination, retries, or rate limiting
- Testing API integrations with mocking
Documentation
Use web-search for docs at https://docs.saloon.dev. Check composer.json for version (v2, v3 or v4).
Features
- Artisan Commands: Generate classes with
saloon:connector, saloon:request, saloon:response, saloon:plugin, saloon:auth. Example:
php artisan saloon:connector GitHub GitHubConnector
php artisan saloon:request GitHub GetUserRequest
- Connectors: Define base URL and shared config. Extend
Saloon\Http\Connector. Example:
use Saloon\Http\Connector;
class GitHubConnector extends Connector
{
public function resolveBaseUrl(): string
{
return 'https://api.github.com';
}
}
- Requests: Define endpoints. Extend
Saloon\Http\Request, set $method via Saloon\Enums\Method. Example:
use Saloon\Enums\Method;
use Saloon\Http\Request;
class GetUserRequest extends Request
{
protected Method $method = Method::GET;
public function resolveEndpoint(): string
{
return '/user';
}
}
- Sending Requests: Use connector to send requests. Example:
$response = $connector->send(new GetUserRequest);
$response->json();
$response->successful();
-
Body Types: Implement HasBody + trait (HasJsonBody, HasFormBody, HasMultipartBody, HasXmlBody, HasStringBody, HasStreamBody).
-
Authentication: Use TokenAuthenticator, BasicAuthenticator, QueryAuthenticator, or implement Saloon\Contracts\Authenticator.
-
Plugins: Built-in traits: AcceptsJson, AlwaysThrowOnErrors, HasTimeout, HasRetry, HasRateLimit, WithDebugData, CastsToDto.
-
Middleware: Use middleware()->onRequest() and middleware()->onResponse(), or implement boot() method.
-
DTOs: Implement createDtoFromResponse() in request classes, use $response->dto() or $response->dtoOrFail().
-
Laravel Facade: Mock requests in tests. Example:
Saloon::fake([GetUserRequest::class => MockResponse::make(['name' => 'Sam'])]);
- HTTP Sender: Enable Telescope support via
config/saloon.php:
'default_sender' => \Saloon\Laravel\HttpSender::class,
-
v3 Retry: Set $tries, $retryInterval, $useExponentialBackoff on connectors/requests.
-
v3 Pagination: Requires saloonphp/pagination-plugin.
File Structure
Store classes in app/Http/Integrations/{ServiceName}/ (configurable in config/saloon.php).
Common Pitfalls
- Not using Artisan commands to generate classes
- Forgetting
HasBody interface when sending body data
- Wrong HTTP method enum (use
Saloon\Enums\Method)
- Missing
HttpSender config for Telescope
- v3 or v4: forgetting to install pagination plugin
Available Documentation
Use web-search with these docs for specific topics:
Upgrade
The Basics
- [https://docs.saloon.dev/the-basics/installation] Use these docs for installation instructions, Composer setup, and initial configuration
- [https://docs.saloon.dev/the-basics/connectors] Use these docs for creating connectors, setting base URLs, default headers, and shared configuration
- [https://docs.saloon.dev/the-basics/requests] Use these docs for creating requests, defining endpoints, HTTP methods, query parameters, and request bodies
- [https://docs.saloon.dev/the-basics/authentication] Use these docs for authentication methods including token, basic, OAuth2, and custom authenticators
- [https://docs.saloon.dev/the-basics/request-body-data] Use these docs for sending body data in requests, including JSON, XML, and multipart form data
- [https://docs.saloon.dev/the-basics/sending-requests] Use these docs for sending requests through connectors, handling responses, and request lifecycle
- [https://docs.saloon.dev/the-basics/responses] Use these docs for handling responses, accessing response data, status codes, and headers
- [https://docs.saloon.dev/the-basics/handling-failures] Use these docs for handling failed requests, error responses, and using AlwaysThrowOnErrors trait
- [https://docs.saloon.dev/the-basics/debugging] Use these docs for debugging requests and responses, using the debug() method, and inspecting PSR-7 requests
- [https://docs.saloon.dev/the-basics/testing] Use these docs for testing Saloon integrations, mocking requests, and writing assertions
Digging Deeper
- [https://docs.saloon.dev/digging-deeper/data-transfer-objects] Use these docs for casting API responses into DTOs, creating DTOs from responses, implementing WithResponse interface, and using DTOs in requests
- [https://docs.saloon.dev/digging-deeper/building-sdks] Use these docs for building SDKs with Saloon, creating resource classes, and organizing API integrations
- [https://docs.saloon.dev/digging-deeper/solo-requests] Use these docs for creating standalone requests without connectors using SoloRequest class
- [https://docs.saloon.dev/digging-deeper/retrying-requests] Use these docs for implementing retry logic with exponential backoff and custom retry strategies (v3 includes global retry system at connector level)
- [https://docs.saloon.dev/digging-deeper/delay] Use these docs for adding delays between requests to prevent rate limiting and server overload
- [https://docs.saloon.dev/digging-deeper/concurrency-and-pools] Use these docs for sending concurrent requests using pools, managing multiple API calls efficiently, and asynchronous request handling
- [https://docs.saloon.dev/digging-deeper/oauth2-authentication] Use these docs for OAuth2 authentication flows including Authorization Code Grant, Client Credentials, and token refresh
- [https://docs.saloon.dev/digging-deeper/middleware] Use these docs for creating and using middleware to modify requests and responses, request lifecycle hooks, and boot methods
- [https://docs.saloon.dev/digging-deeper/psr-support] Use these docs for PSR-7 and PSR-17 support, accessing PSR requests and responses, and modifying PSR-7 requests
Installable Plugins
