Shipping Sdk Php Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require dinas/shipping-sdk-php guzzlehttp/guzzle php-http/guzzle7-adapter
   

2. Configure the API client in your Laravel service provider (e.g., AppServiceProvider):

   public function boot()
   {
       $config = Dinas\ShippingSdk\Configuration::getDefaultConfiguration()
           ->setAccessToken(config('services.dinas.api_token'))
           ->setHost(config('services.dinas.api_host', 'https://shipping.dinas.jp'));
   
       $this->app->singleton(Dinas\ShippingSdk\Api\CarsApi::class, function () use ($config) {
           return new Dinas\ShippingSdk\Api\CarsApi(new GuzzleHttp\Client(), $config);
       });
   }
   

3. Add config to config/services.php:

   'dinas' => [
       'api_token' => env('DINAS_API_TOKEN'),
       'api_host' => env('DINAS_API_HOST', 'https://shipping.dinas.jp'),
   ],
   

First Use Case: Fetching Cars

Inject the API client into a controller or service and fetch cars:

public function index(Dinas\ShippingSdk\Api\CarsApi $carsApi)
{
    $cars = $carsApi->getCars(
        status: 'active',
        per_page: 10
    );

    return view('cars.index', compact('cars'));
}

Implementation Patterns

1. Dependency Injection

Use Laravel’s DI container to inject API clients into controllers/services:

public function __construct(
    private Dinas\ShippingSdk\Api\CarsApi $carsApi,
    private Dinas\ShippingSdk\Api\WebhooksApi $webhooksApi
) {}

2. Pagination Handling

Process paginated responses with Laravel collections:

$cars = collect([]);
$page = 1;
do {
    $response = $carsApi->getCars(per_page: 100, page: $page);
    $cars->push(...$response->getData());
    $page = $response->getMeta()->getCurrentPage() + 1;
} while ($page <= $response->getMeta()->getTotalPages());

3. Error Handling

Centralize API error handling in a middleware or service:

try {
    $carsApi->syncCars($carData);
} catch (Dinas\ShippingSdk\ApiException $e) {
    Log::error('Dinas API Error: ' . $e->getMessage());
    return back()->with('error', 'Failed to sync car');
}

4. Webhook Integration

Register webhooks in Laravel’s boot() method:

public function boot()
{
    $webhook = new \Dinas\ShippingSdk\Model\Webhook(
        name: 'car_arrival',
        url: route('webhooks.car_arrival'),
        events: ['car.arrived']
    );

    $this->webhooksApi->storeWebhook($webhook);
}

5. File Uploads

Upload car photos/documents using Laravel’s Storage facade:

$filePath = storage_path('app/car_photos/photo.jpg');
$file = fopen($filePath, 'r');

$apiInstance->storeCarPhotoFiles(
    new \Dinas\ShippingSdk\Model\AlbumFiles(
        car_id: 123,
        files: [$file]
    )
);

6. Command Bus for Batch Operations

Use Laravel’s Bus facade to queue API calls:

Bus::dispatch(new SyncCarsJob($carData));

Gotchas and Tips

1. Authentication

• Token Management: Store the API token securely (e.g., Laravel’s env() or Vault).
• Token Rotation: Implement a DinasTokenService to handle token refresh if needed.

2. Rate Limiting

• The API may throttle requests. Use Laravel’s throttle middleware:

  Route::middleware(['throttle:10,1'])->group(function () {
      // Dinas API routes
  });
  

3. Model Mapping

• Manual Mapping: The SDK returns raw models (e.g., CarData). Map them to Laravel Eloquent models:

  $car = (new Car)->fill([
      'chassis' => $apiCar->getChassis(),
      'make' => $apiCar->getMake(),
      // ...
  ]);
  

4. Webhook Payloads

• Validation: Validate incoming webhook payloads using Laravel’s ValidateWebhookPayload middleware:

  public function handle(Request $request, Closure $next)
  {
      $request->validate([
          'event' => 'required|in:car.arrived,car.shipped',
          'data' => 'required|array',
      ]);
      return $next($request);
  }
  

5. Debugging

• Enable SDK Debugging: Set the DEBUG constant in Configuration:

  $config->setDebug(true);
  

• Log API Responses: Use Laravel’s tap() to log responses:

  $carsApi->getCars()->tap(function ($response) {
      Log::debug('Dinas API Response:', $response->toArray());
  });
  

6. Common Pitfalls

• File Uploads: Ensure files are in the correct format (e.g., multipart/form-data). Use Laravel’s File facade to handle uploads:

  $file = new File($filePath);
  $apiInstance->storeCarPhotoFiles(new \Dinas\ShippingSdk\Model\AlbumFiles(
      car_id: 123,
      files: [$file]
  ));
  

• Pagination Offsets: The SDK uses page and per_page, not offset. Avoid mixing Laravel’s cursor() with this SDK.
• Webhook Testing: Always test webhooks locally using ngrok or Laravel’s queue:work:

  php artisan webhooks:test car_arrival
  

7. Extension Points

• Custom HTTP Client: Replace Guzzle with Laravel’s Http client for consistency:

  $client = new \Illuminate\Http\Client\PendingRequest();
  $apiInstance = new Dinas\ShippingSdk\Api\CarsApi($client, $config);
  

• API Retries: Use Laravel’s retry helper for transient failures:

  retry(3, function () use ($carsApi) {
      return $carsApi->getCars();
  }, 100);
  

• Caching: Cache API responses with Laravel’s cache() helper:

  return Cache::remember('dinas_cars_active', now()->addHours(1), function () use ($carsApi) {
      return $carsApi->getCars(status: 'active');
  });