Saloon Sdk Generator Laravel Package

Getting Started

The Saloon SDK Generator is a CLI tool that turns OpenAPI specs into ready-to-use Saloon connectors, requests, and DTOs. Install it globally, then generate your first SDK from a spec:

composer global require crescat-io/saloon-sdk-generator
saloon-sdk-generator generate --spec=openapi.yaml --output=app/Services/MyApi

Start by reading the generated Connector class and the package’s config file (publish with vendor:publish --tag=saloon-sdk-generator-config). Your first use case should be a read-only API call: generate an SDK, inject the connector into a controller or artisan command, and call a generated request. This validates the spec, namespace, and auth wiring before you invest in customization.

Implementation Patterns

• Spec-first workflow: Keep your OpenAPI spec in the repo, regenerate the SDK in CI or via a Composer script, and treat generated code as read-only. Commit generated output so diffs are reviewable.
• Auth wiring: For single-authenticator connectors, set the authenticator in the connector constructor or via config. For multi-authenticator connectors, define defaultAuth() in your connector; v1.6.0 now consistently uses defaultAuth() instead of getAuthenticator(), so custom authenticators should override defaultAuth().
• Laravel integration: Bind the generated connector in a service provider if you need a singleton with configured base URL/token. Use Saloon’s Laravel plugin for Laravel HTTP client integration, testing fakes, and recording.
• Customization: Publish and edit the generator’s templates for naming conventions, base classes, or traits. Prefer extending generated classes (e.g., a custom connector that extends the generated one) over editing generated files directly.
• Testing: Use Saloon’s MockClient / RecordedResponse in feature tests. Generate SDKs into a tests/Fixtures namespace when you need to assert generated behaviour without polluting app code.
• Multi-tenant / multi-auth: Generate one SDK per API, not per tenant. Inject credentials via constructor or a custom authenticator, and rely on defaultAuth() for the default path.

Gotchas and Tips

• Saloon v4 is a security upgrade: v1.6.0 upgrades to saloonphp/saloon ^4.0 and saloonphp/laravel-plugin ^4.0. Generated SDKs accept ^3.0|^4.0, but you should upgrade your app to Saloon v4 to pick up the CVE fixes. Check your composer.lock for transitive constraints.
• Multi-authenticator change: If you previously relied on getAuthenticator() in a multi-auth connector, verify your custom connector defines defaultAuth(). Behaviour is now consistent with single-authenticator connectors.
• Global install vs project dependency: A global install can drift from your project’s PHP/Saloon versions. Pin the generator in require-dev and run it via vendor/bin/saloon-sdk-generator for reproducible generation.
• Regeneration overwrites files: Generated code is replaced on each run. Keep custom logic in subclasses, traits, or a separate namespace that the generator does not touch.
• Namespace and autoload: After generating into a new namespace, run composer dump-autoload. If generated classes are not found, check composer.json PSR-4 mappings and the generator’s --namespace option.
• Debugging generated requests: Use Saloon’s Debugger or --debug flag in the generated connector, and inspect the generated request’s resolveEndpoint() and defaultBody() methods. Most spec-to-SDK issues surface there.
• Extension points: Templates, config (saloon-sdk-generator.php), and post-generation hooks are the safest places to customize. Avoid patching vendor files; the global install will be replaced on upgrade.