Gls Uni Box Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require ekyna/gls-uni-box
   

   Register the service provider in config/app.php:

   'providers' => [
       // ...
       Ekyna\GlsUniBox\GlsUniBoxServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Ekyna\GlsUniBox\GlsUniBoxServiceProvider"
   

   Update .env with your GLS credentials:

   GLS_UNIBOX_USERNAME=your_username
   GLS_UNIBOX_PASSWORD=your_password
   GLS_UNIBOX_ACCOUNT_NUMBER=your_account_number
   

3. First Use Case: Creating a Shipment Inject the Ekyna\GlsUniBox\GlsUniBox facade or service into a controller:

   use Ekyna\GlsUniBox\Facades\GlsUniBox;
   
   public function createShipment(Request $request) {
       $shipment = GlsUniBox::createShipment([
           'sender' => [
               'name' => 'Sender Name',
               'address' => 'Sender Street',
               'postcode' => '1234AB',
               'city' => 'Sender City',
               'country' => 'NL',
           ],
           'recipient' => [
               'name' => 'Recipient Name',
               'address' => 'Recipient Street',
               'postcode' => '5678CD',
               'city' => 'Recipient City',
               'country' => 'NL',
           ],
           'parcels' => [
               [
                   'weight' => 1.5,
                   'description' => 'Sample package',
               ],
           ],
           'service' => 'GLS_EXPRESS', // or 'GLS_STANDARD'
       ]);
   
       return response()->json($shipment);
   }
   

Implementation Patterns

Core Workflows

1. Shipment Management

   • Create Shipments: Use GlsUniBox::createShipment() with sender/recipient/parcel details.
   • Track Shipments: Fetch tracking data via:

     $tracking = GlsUniBox::getTrackingInfo('TRACKING_NUMBER');
     

   • Label Generation: Generate PDF labels:

     $label = GlsUniBox::generateLabel('SHIPMENT_ID');
     Storage::put('public/gls_labels/' . $label['filename'], $label['content']);
     

2. Batch Processing Loop through orders and generate shipments in bulk:

   foreach ($orders as $order) {
       GlsUniBox::createShipment($this->formatShipmentData($order));
   }
   

3. Event-Driven Integration Listen for shipment events (e.g., after creation) using Laravel events:

   // In a service class
   event(new ShipmentCreated($shipmentData));
   

4. API Wrapper Abstraction Extend the base client for custom logic:

   class CustomGlsClient extends \Ekyna\GlsUniBox\GlsUniBox {
       public function customShipmentFlow($data) {
           $shipment = $this->createShipment($data);
           // Add custom post-processing
           return $this->updateOrderStatus($shipment['id']);
       }
   }
   

Integration Tips

• Queue Delayed Tasks: Offload GLS API calls to queues to avoid timeouts:

  ShipmentJob::dispatch($shipmentData)->delay(now()->addMinutes(5));
  

• Retry Logic: Implement retry logic for failed API calls using Laravel’s retry helper or a package like spatie/laravel-retryable.
• Logging: Log API responses for debugging:

  \Log::debug('GLS API Response', ['data' => $response]);
  

• Caching: Cache tracking info if frequent checks are needed:

  $tracking = Cache::remember("gls_tracking_{$trackingNumber}", now()->addHours(1), function () use ($trackingNumber) {
      return GlsUniBox::getTrackingInfo($trackingNumber);
  });
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • GLS may throttle requests. Monitor response times and implement exponential backoff.
   • Fix: Use GuzzleHttp\Client with retry middleware or a dedicated queue worker.

2. Data Validation

   • The library may not validate all GLS API constraints (e.g., postcode formats, weight limits).
   • Fix: Add validation before calling the API:

     $validated = $request->validate([
         'weight' => 'required|numeric|min:0.1|max:30',
         'postcode' => 'required|string|max:10',
     ]);
     

3. Label Generation Issues

   • Labels may fail to generate due to unsupported parcel types or dimensions.
   • Fix: Check GLS’s API documentation for supported formats and add pre-flight checks.

4. Environment-Specific Config

   • Hardcoding credentials in .env can lead to leaks. Use Laravel’s env() or a secrets manager.
   • Fix: Restrict .env to the server and use Laravel Forge/Vault for production.

5. Deprecation Risks

   • The package has low adoption (0 stars/dependents). GLS’s API may change without updates.
   • Fix: Subscribe to GLS’s developer updates and wrap API calls in a feature flag:

     if (config('gls.use_new_api')) {
         $this->useNewApiClient();
     }
     

Debugging

• Enable Debug Mode: Set GLS_UNIBOX_DEBUG=true in .env to log raw API requests/responses.
• Mock API Calls: Use Laravel’s HTTP tests to mock GLS responses:

  $response = new Response('<xml>...</xml>');
  Http::fake($response);
  
  $shipment = GlsUniBox::createShipment($data);
  

• Check HTTP Status Codes: GLS may return non-200 codes for validations (e.g., 400 for invalid postcodes).

Extension Points

1. Custom API Endpoints Extend the client to support non-standard endpoints:

   class ExtendedGlsClient extends GlsUniBox {
       public function getCustomReport($params) {
           return $this->request('GET', '/custom/report', $params);
       }
   }
   

2. Webhook Listeners Implement a webhook endpoint to handle GLS status updates:

   Route::post('/gls/webhook', function (Request $request) {
       $payload = $request->xml();
       // Parse and process GLS webhook data
   });
   

3. Database Sync Sync GLS shipments to a local database table:

   $shipment = GlsUniBox::createShipment($data);
   \App\Models\Shipment::create([
       'gls_id' => $shipment['id'],
       'tracking_number' => $shipment['tracking_number'],
       // ...
   ]);
   

4. Multi-Account Support Dynamically switch accounts based on context:

   GlsUniBox::setAccount('account_2');
   $shipment = GlsUniBox::createShipment($data);