Mistral Laravel Package

Getting Started

• Install the package with Composer: composer require vendor/package (this release requires Saloon v4; ensure your app meets its PHP/Laravel constraints).
• Publish any package config (e.g., php artisan vendor:publish --tag=package-config) and add required credentials to .env (API key, base URL, timeout).
• Look first at the package's config/ file and README for available connectors/resources. Then skim the Saloon v4 upgrade guide for core HTTP client patterns.
• Quick first use case: inject the package connector into a controller or artisan command, then send a basic request:

  $response = $connector->send(new GetSomethingRequest());
  $data = $response->json();
  

• For tests, use MockResponse::fixture('chat/create') — note the new slash separator (v3.0.0 breaking change). Store fixtures under tests/Fixtures/Saloon/.

Implementation Patterns

• Connector-first architecture: Extend Saloon's Connector for each API. Define resolveBaseUrl(), defaultHeaders(), defaultAuth(), and middleware() in the connector. Inject connectors via Laravel's container.
• Resource grouping: Create resource classes (e.g., ChatResource) that return configured requests for each endpoint. Inject the connector into the resource constructor.
• Authentication: Use Saloon's WithTokenAuth or a custom authenticator reading from config('package.api_key'). Keep secrets in .env.
• Error handling: Check $response->failed() and use $response->throw() for automatic exceptions. Map Saloon exceptions to Laravel's handler for consistent API error responses.
• Testing pattern (v3.0.0+): Use MockResponse::fixture('path/with/slashes') — rename old dot-based fixtures like chat.create → chat/create. For global fakes, use Saloon::fake([...]) in test setup.
• Queues: Wrap connector usage in Laravel jobs. Saloon requests are synchronous by default; dispatch jobs for long-running or rate-limited calls.
• Middleware: Register Saloon middleware for logging, retries, and rate limiting in the connector's middleware() method. Use Laravel's logger or a custom middleware to log request/response bodies.
• Caching: Cache expensive API responses using Laravel's Cache facade around the connector call, or implement a Saloon middleware that caches by request signature.
• Integration tips: Keep connectors thin (auth, base URL, headers) and resources focused on endpoint logic. Use Laravel's Http client for non-Saloon APIs to avoid mixing HTTP layers.

Gotchas and Tips

• Breaking change in v3.0.0: Saloon v4 forbids dots in fixture names. Rename all MockResponse::fixture('foo.bar') calls to MockResponse::fixture('foo/bar'). Update fixture file paths accordingly (tests/Fixtures/Saloon/foo/bar.json). Run the full test suite immediately after upgrading — fixture naming errors often surface only at runtime.
• Saloon v4 API changes: Review the Saloon upgrade guide for method signature changes (e.g., send() return types, middleware interfaces). Adjust custom connectors, authenticators, and middleware as needed.
• Debugging: Use $response->debug() or Saloon's built-in logger. For failing tests, inspect the fixture path and filename casing. Use php artisan test --filter=YourTest to isolate issues.
• Config quirks: Ensure base URLs end with a trailing slash where required. Set per-connector timeouts and retries in config/package.php or directly in the connector. Clear Laravel's config cache after changing .env values (php artisan config:clear).
• Extension points: Most packages expose base connector/resource classes you can extend. Override resolveBaseUrl() or defaultHeaders() for multi-tenant setups. Register custom middleware globally via a service provider if the package doesn't expose a hook.
• Pitfall: If the package uses a facade or alias, confirm it's registered in config/app.php (Laravel 11+ auto-discovery usually handles it). If you see "class not found," run composer dump-autoload.
• Tip: After upgrading to v3.0.0, search your codebase for MockResponse::fixture( and any dot-separated strings. Use grep -r "fixture('.*\..*'" to catch leftovers.
• Tip: Store test fixtures with descriptive slash-based paths (e.g., chat/create, users/list) to match endpoint URLs and avoid future naming friction.