- How do I integrate this SDK into a Laravel application?
- Install via Composer (`composer require dinas/shipping-sdk-php`), configure the API token in `config/services.php`, and bind the `Configuration` class to Laravel’s IoC container. Use Laravel’s `Http` facade (Guzzle) as the PSR-18 client for seamless integration.
- Does this SDK support Laravel’s HTTP middleware (e.g., rate limiting, auth)?
- Yes. Wrap SDK calls with Laravel middleware like `ThrottleRequests` or `Authenticate` by injecting the SDK client into a custom service class. For example, use `Http::withOptions()` to apply middleware globally.
- Can I use this SDK with Laravel queues for async operations?
- Absolutely. Offload long-running tasks like `syncCars()` to Laravel queues (e.g., Redis or database). Trigger queue jobs from your service layer after initializing the SDK client.
- How do I handle webhooks from Dinas in Laravel?
- Define a Laravel route (e.g., `Route::post('/dinas-webhook', [WebhookController::class, 'handle'])`) to validate HMAC signatures, then dispatch queued jobs or broadcast events (e.g., `VoyageUpdated`) using Laravel’s event system.
- What Laravel versions does this SDK support?
- The SDK requires PHP 8.1+, which aligns with Laravel 9+ (LTS). For Laravel 8.x, ensure your PHP version meets the SDK’s requirements. Test thoroughly with your Laravel version’s HTTP client (Guzzle 7+).
- How do I sync Dinas car data with a Laravel Eloquent model?
- Use the `syncCars()` endpoint to fetch data, then map responses to Eloquent models (e.g., `Car`). Handle conflicts via observers or jobs—e.g., update existing records or create new ones based on API responses.
- Is there a way to mock the SDK for unit testing in Laravel?
- Yes. The SDK’s `CarsApi`, `VoyagesApi`, etc., can be mocked using Laravel’s `Mockery` or PHPUnit’s `createMock()`. Inject the mocked client into your service layer for isolated testing.
- How should I handle API errors or rate limits in production?
- Use Laravel’s `try-catch` blocks or `Http::withOptions()` to standardize error responses. Implement Guzzle’s retry middleware or Laravel’s `ThrottleRequests` middleware to handle rate limits gracefully.
- What if the Dinas API changes (e.g., breaking updates)?
- Monitor Dinas’s API changelog for deprecations. The SDK is auto-generated from OpenAPI, so updates may require a Composer update. Test thoroughly in a staging environment before deploying to production.
- Are there alternatives to this SDK for Laravel?
- For Dinas-specific integrations, this SDK is the official client. For broader shipping APIs, consider `spatie/laravel-shipping` or custom Guzzle-based solutions. However, this SDK offers webhook support and domain-specific logic tailored to Dinas.