Shipping Sdk Laravel Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dinas/shipping-sdk-laravel
   

   Add to .env:

   DINAS_SHIPPING_TOKEN=your-api-token
   DINAS_SHIPPING_SECRET=your-webhook-secret
   

2. Webhook Setup:

   • Add route:

     Route::dinasShippingWebhooks('dinas-shipping/webhook');
     

   • Exclude from CSRF in app/Providers/AppServiceProvider.php:

     $middleware->validateCsrfTokens(except: ['dinas-shipping/webhook']);
     

   • Run migrations:

     php artisan vendor:publish --tag="shipping-sdk-laravel-migrations"
     php artisan migrate
     

   • Register webhook:

     php artisan webhook:dinas-shipping -i
     

3. First Use Case: Fetch cars with pending status:

   use Dinas\Shipping\Facades\Shipping;
   
   $cars = Shipping::getCars(['status' => \Dinas\ShippingSdk\Model\StockStatus::PENDING]);
   

Implementation Patterns

Core Workflows

1. Data Sync:

   • Fetch & Update: Use getCars() to retrieve data, then syncCars() to update records.
   • Batch Operations: Hold/release cars in bulk:

     Shipping::holdCars(['ABC123', 'DEF456'], ['date' => '2026-03-15']);
     

2. Media Management:

   • Upload Photos/Docs: Use storeCarPhotos() or storeCarDocuments() with URLs/files.
   • Async Callbacks: Attach onResolve to handle API job completion:

     Shipping::storeCarPhotos($photos, onResolve: fn($context) => {
         if ($context->isFailed()) Log::error($context->message);
     });
     

3. Webhook Handling:

   • Event-Driven Logic: Dispatch jobs for webhook events (e.g., shipment status updates).
   • Broadcasting: Enable Pusher for real-time frontend updates:

     Echo.private(`App.Models.User.${userId}`)
         .listen('.shipping.job.resolved', (e) => { ... });
     

4. Voyage Tracking:

   • Filter Voyages: Use getVoyages() with pagination:

     $voyages = Shipping::getVoyages(['per_page' => 25]);
     

Integration Tips

• Dependency Injection: Prefer constructor injection for Shipping facade:

  public function __construct(private Shipping $shipping) {}
  

• Direct API Access: Use Shipping::cars() for granular control over API endpoints.
• Error Handling: Validate StoreResult objects for bulk operations:

  $result = Shipping::storeCarPhotos($photos);
  if (!$result->ok) {
      foreach ($result->validationErrors as $field => $messages) {
          // Handle errors
      }
  }
  

Gotchas and Tips

Pitfalls

1. Webhook Verification:

   • Ensure DINAS_SHIPPING_SECRET matches the API’s registered secret.
   • Debugging: Check webhook_calls table for failed signatures.

2. Async Job Callbacks:

   • Duplicate Triggers: Webhooks may retry; use WebhookJob status tracking to avoid duplicate executions.
   • Serialization: Callbacks must be serializable (avoid closures with non-serializable objects).

3. Rate Limiting:

   • API may throttle requests. Implement exponential backoff for retries:

     Shipping::setHttpClient($client->withOptions(['timeout' => 30]));
     

4. CSRF Exclusion:

   • Forgetting to exclude /dinas-shipping/webhook from CSRF validation will block webhooks.

Debugging

• Logs: Enable debug mode in config/dinas-shipping-sdk.php:

  'debug' => env('APP_DEBUG', false),
  

• Webhook Inspection: Use php artisan webhook:dinas-shipping to list registered webhooks.
• API Responses: Inspect raw responses with:

  $response = Shipping::cars()->getCars(...);
  Log::debug($response->getBody());
  

Extension Points

1. Custom HTTP Client:

   • Override the default client for middleware (e.g., logging):

     Shipping::setHttpClient($client->withMiddleware([new MyMiddleware()]));
     

2. Webhook Events:

   • Extend WebhookCall model to add custom logic:

     class CustomWebhookCall extends \Spatie\WebhookClient\Models\WebhookCall {
         protected static function booted() {
             static::created(fn($call) => {
                 // Custom logic
             });
         }
     }
     

3. Broadcasting:

   • Disable for specific events by filtering in AppServiceProvider:

     Shipping::setBroadcastingEnabled(false);
     

4. Pruning:

   • Adjust delete_after_days in config to control WebhookJob retention:

     'webhook_jobs' => [
         'delete_after_days' => 90, // Extend to 90 days
     ],
     

   • Schedule pruning in routes/console.php:

     Schedule::command('model:prune --model="Dinas\Shipping\Models\WebhookJob"')->weekly();