Shipping Sdk Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Microservice/API Integration: The package is a two-way bridge between Laravel and the Dinas Shipping API, making it ideal for applications requiring real-time synchronization of shipping data (e.g., inventory, documents, status updates).
• Event-Driven Workflow: Leverages webhooks for asynchronous updates (e.g., shipment status changes), aligning with modern Laravel patterns (jobs, queues, broadcasting).
• Domain-Specific Abstraction: Encapsulates Dinas API complexity behind a facade (Shipping) and domain-specific methods (e.g., syncCars, storeCarPhotos), reducing boilerplate for common operations.
• Extensibility: Supports direct API access for custom use cases while providing high-level helpers for 80% of needs.

Integration Feasibility

• Laravel Native: Built for Laravel (facades, service providers, migrations, Artisan commands), requiring minimal adaptation.
• Webhook Infrastructure: Relies on spatie/webhook-client, a mature package for handling signed payloads, retries, and logging.
• Async Processing: Uses Laravel’s queue system for job resolution callbacks, ensuring scalability.
• Broadcasting: Optional Pusher integration for real-time frontend updates (opt-out via config).

Technical Risk

Key Questions

1. API Contract: Does the Dinas Shipping API have a public changelog or deprecation policy? If not, how will the package handle breaking changes?
2. Webhook Volume: What is the expected rate of webhook events (e.g., 100/day vs. 10,000/day)? Does spatie/webhook-client need tuning (e.g., queue workers, retry delays)?
3. Async Job Lifecycle: How long should WebhookJob records be retained? The default 30-day pruning may need adjustment for compliance or debugging.
4. Error Handling: Are there SLA requirements for failed async jobs (e.g., document uploads)? Custom retry logic may be needed.
5. Multi-Tenancy: If the app supports multiple shipping accounts, how will DINAS_SHIPPING_TOKEN/SECRET be scoped per tenant?
6. Testing: Does the package include integration tests against the Dinas API? If not, how will the team validate end-to-end workflows?
7. Broadcasting: If using Pusher, is the user-specific channel (App.Models.User.${userId}) compatible with the app’s auth system?

Integration Approach

Stack Fit

1. spatie/webhook-client (for webhook calls).
2. Package-specific (for webhook_jobs table). Run with php artisan vendor:publish --tag=shipping-sdk-laravel-migrations and php artisan migrate. | | Artisan Commands | Provides CLI tools for:

• Registering webhooks (php artisan webhook:dinas-shipping -i).
• Listing webhooks (php artisan webhook:dinas-shipping).
• Deregistering (php artisan webhook:dinas-shipping -r). | | Configuration | Publishes config/dinas-shipping-sdk.php for:
• API token/secret.
• Webhook endpoint.
• Broadcasting settings.
• Job pruning (e.g., delete_after_days). | | Facades/Dependency Injection | Exposes Shipping facade or injectable class for direct API access. |

Migration Path

1. Pre-Installation:

   • Review Dinas API documentation for rate limits, auth requirements, and data models.
   • Ensure Laravel version compatibility (package targets Laravel 9+).
   • Allocate a dedicated queue worker for async job processing (e.g., php artisan queue:work --queue=high).

2. Installation:

   composer require dinas/shipping-sdk-laravel
   php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="webhook-client-migrations"
   php artisan vendor:publish --tag="shipping-sdk-laravel-migrations"
   php artisan vendor:publish --tag="shipping-sdk-laravel-config"
   php artisan migrate
   

3. Configuration:

   • Set .env:

     DINAS_SHIPPING_TOKEN=your_api_token
     DINAS_SHIPPING_SECRET=your_webhook_secret
     

   • Configure CSRF exemption in app/Providers/AppServiceProvider.php.
   • Tune config/dinas-shipping-sdk.php (e.g., chunk size, pruning).

4. Webhook Setup:

   • Add route:

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

   • Register webhook with Dinas API:

     php artisan webhook:dinas-shipping -i
     

5. Testing:

   • Unit Tests: Mock the Dinas API to test facade methods (e.g., Shipping::getCars).
   • Webhook Tests: Simulate payloads using spatie/webhook-client test helpers.
   • End-to-End: Validate async workflows (e.g., photo upload → webhook → job resolution).

6. Go-Live:

   • Monitor queue backlogs and webhook failures.
   • Set up alerts for WebhookCall failures (via spatie/webhook-client events).

Compatibility

• Laravel: Tested on 9.x/10.x. May require adjustments for 8.x or 11.x.
• PHP: Requires PHP 8.1+. Check for strict_types compatibility.
• Dependencies:
  • guzzlehttp/guzzle (for API calls).
  • spatie/webhook-client (for webhooks).
  • spatie/laravel-webhook-server (optional, for local testing).
• Database: Supports MySQL, PostgreSQL, SQLite (via Laravel migrations).

Sequencing

1. Phase 1: Core Integration (2–4 weeks):

   • Install, configure, and test read operations (e.g., getCars, getVoyages).
   • Implement write operations (e.g., syncCars, storeCarPhotos) in a non-critical workflow.
   • Validate webhook receipt and job processing.

2. Phase 2: Async Workflows (1–2 weeks):

   • Test async operations (e.g., document uploads) with callback handlers.
   • Configure broadcasting if real-time updates are needed.
   • Optimize queue workers