Dhl Shipment Tracking Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dreipunktnull/dhl-shipment-tracking
   

   Ensure your composer.json includes "minimum-stability": "dev" if the package isn’t on Packagist.

2. First Use Case: Track a Single Shipment

   use Dreipunktnull\DhlTracking\DhlTracking;
   
   $tracker = new DhlTracking('YOUR_DHL_TRACKING_ID', 'YOUR_DHL_TRACKING_PASSWORD');
   $trackingResult = $tracker->track('12345678901234567890');
   
   if ($trackingResult->isSuccess()) {
       dd($trackingResult->getTrackingData());
   } else {
       dd($trackingResult->getErrors());
   }
   

3. Where to Look First

   • API Docs: Check the DHL Tracking API documentation for endpoint specifics.
   • Package Source: Review src/Dreipunktnull/DhlTracking/DhlTracking.php for core methods (track(), getTrackingData()).
   • Tests: If available, inspect tests/ for real-world usage examples.

Implementation Patterns

Workflows

1. Batch Tracking Use trackMultiple() for bulk shipments:

   $results = $tracker->trackMultiple(['12345678901234567890', '98765432109876543210']);
   foreach ($results as $result) {
       if ($result->isSuccess()) {
           // Process successful tracking
       }
   }
   

2. Caching Responses Cache API responses to reduce calls (e.g., using Laravel’s Cache facade):

   $cacheKey = 'dhl_tracking_' . $trackingNumber;
   $trackingData = Cache::remember($cacheKey, now()->addHours(1), function () use ($tracker, $trackingNumber) {
       return $tracker->track($trackingNumber)->getTrackingData();
   });
   

3. Error Handling Wrap API calls in a try-catch to handle exceptions (e.g., network issues, invalid credentials):

   try {
       $tracker->track($trackingNumber);
   } catch (\Exception $e) {
       Log::error("DHL Tracking failed: " . $e->getMessage());
       // Fallback logic (e.g., notify admin)
   }
   

Integration Tips

• Laravel Service Provider Bind the tracker to the container for dependency injection:

  $this->app->singleton(DhlTracking::class, function ($app) {
      return new DhlTracking(config('services.dhl.tracking_id'), config('services.dhl.password'));
  });
  

  Then inject DhlTracking into controllers/services.

• Queue Delayed Tasks Offload tracking to a queue (e.g., trackShipmentJob) to avoid blocking requests:

  TrackShipmentJob::dispatch($trackingNumber)->delay(now()->addMinutes(5));
  

• Webhook Integration Use the package to poll tracking updates and trigger webhooks (e.g., via laravel-webhooks) when status changes.

Gotchas and Tips

Pitfalls

1. Deprecated/Archived Package

   • The package is archived and may lack updates for DHL API changes. Verify compatibility with the DHL Tracking API v1 or later.
   • Mitigation: Fork the repo and extend it if needed, or use a maintained alternative like spatie/dhl-api.

2. Rate Limiting DHL’s API enforces rate limits (e.g., 100 requests/minute). Implement exponential backoff:

   use Symfony\Component\Cache\Adapter\AdapterInterface;
   
   $cache = new AdapterInterface();
   if (!$cache->get('dhl_rate_limit', function () use ($tracker) {
       return $tracker->track($number);
   })) {
       // Rate limit exceeded
   }
   

3. Tracking Number Format DHL tracking numbers vary by service (e.g., 123456789012 for Express, 1Z999AA10123456789 for DHL eCommerce). Validate input:

   if (!preg_match('/^(?:1Z|123456789012)\d{10,14}$/', $trackingNumber)) {
       throw new \InvalidArgumentException("Invalid DHL tracking number");
   }
   

4. HTTPS/SSL Issues If using self-signed certificates or proxies, configure Guzzle’s client:

   $tracker = new DhlTracking($id, $password, [
       'http_errors' => false,
       'verify' => false, // Disable only for testing!
   ]);
   

Debugging

• Enable Guzzle Logging Add middleware to log requests/responses:

  $tracker->getClient()->getEmitter()->attach(
      new \GuzzleHttp\Middleware::tap(function ($request) {
          Log::debug('DHL Request:', ['url' => (string) $request->getUri()]);
      })
  );
  

• Check Response Codes DHL returns HTTP 200 even for errors. Inspect $trackingResult->getErrors() for API-specific messages.

Extension Points

1. Custom Response Parsing Override parseResponse() in a subclass to handle non-standard DHL API responses:

   class CustomDhlTracker extends DhlTracking {
       protected function parseResponse($response) {
           // Custom logic for DHL’s JSON structure
       }
   }
   

2. Add Webhook Support Extend the package to emit events (e.g., TrackingUpdated) when status changes:

   event(new TrackingUpdated($trackingNumber, $newStatus));
   

3. Support for DHL API v2 Fork and update the package to use DHL’s GraphQL API or REST v2 endpoints.