Colissimo Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/colissimo
   

   Ensure your PHP version is 7.4+ (last release compatibility).

2. First Use Case: Creating a Shipment

   use Ekyna\Colissimo\Client;
   use Ekyna\Colissimo\Shipment;
   
   $client = new Client('your_api_key', 'your_api_secret');
   $shipment = new Shipment($client);
   
   $shipment->setSender([
       'name' => 'John Doe',
       'address' => '123 Rue de Paris',
       'postcode' => '75000',
       'city' => 'Paris',
       'country' => 'FR',
   ]);
   
   $shipment->setRecipient([
       'name' => 'Jane Smith',
       'address' => '456 Avenue des Champs',
       'postcode' => '33000',
       'city' => 'Bordeaux',
       'country' => 'FR',
   ]);
   
   $shipment->setWeight(1.5); // in kg
   $shipment->setDimensions(20, 15, 10); // length, width, height in cm
   
   $response = $shipment->getRates();
   

3. Key Files to Explore

   • src/Client.php (API client logic)
   • src/Shipment.php (shipment builder)
   • src/Exceptions/ (error handling)

Implementation Patterns

Workflow: Full Shipment Process

1. Initialize Client

   $client = new Client(config('services.colissimo.key'), config('services.colissimo.secret'));
   

   Store credentials in .env:

   COLISSIMO_KEY=your_api_key
   COLISSIMO_SECRET=your_api_secret
   

2. Build Shipment Use fluent methods for sender/recipient:

   $shipment->setSender()->setRecipient()->setWeight()->setDimensions();
   

3. Fetch Rates

   $rates = $shipment->getRates(); // Returns array of available rates
   

4. Create Label

   $label = $shipment->createLabel($selectedRateId);
   

5. Track Shipment

   $tracker = new \Ekyna\Colissimo\Tracker($client, 'tracking_number');
   $status = $tracker->getStatus();
   

Integration Tips

• Laravel Service Provider Bind the client in AppServiceProvider:

  $this->app->singleton(Client::class, function ($app) {
      return new Client(config('colissimo.key'), config('colissimo.secret'));
  });
  

• Form Request Validation Validate shipment data in Laravel requests:

  public function rules()
  {
      return [
          'weight' => 'required|numeric|min:0.1',
          'dimensions' => 'required|array|min:3',
      ];
  }
  

• Queue Delayed Tasks Offload label generation to a queue job:

  CreateLabelJob::dispatch($shipment)->delay(now()->addMinutes(5));
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • Colissimo’s API has strict rate limits (e.g., 10 requests/minute).
   • Cache responses aggressively:

     $rates = Cache::remember("colissimo_rates_{$cacheKey}", now()->addMinutes(5), function () use ($shipment) {
         return $shipment->getRates();
     });
     

2. Deprecated Methods

   • Avoid Shipment::calculate() (deprecated in favor of getRates()).
   • Check CHANGELOG.md for breaking changes (last updated in 2021).

3. Error Handling

   • Wrap API calls in try-catch:

     try {
         $response = $shipment->getRates();
     } catch (\Ekyna\Colissimo\Exceptions\ApiException $e) {
         Log::error($e->getMessage());
         abort(500, 'Colissimo API Error');
     }
     

4. Currency/Weight Units

   • Ensure weights are in kilograms (not grams).
   • Rates are returned in EUR by default (verify with Colissimo docs).

Debugging Tips

• Enable Debug Mode

  $client = new Client($key, $secret, ['debug' => true]);
  

  Logs raw API requests/responses to storage/logs/colissimo.log.

• Mock API Responses Use Laravel’s HTTP tests:

  $this->mock(Client::class, function ($mock) {
      $mock->shouldReceive('getRates')->andReturn([...]);
  });
  

Extension Points

1. Custom Rate Filtering Override Shipment::filterRates() to exclude specific services:

   protected function filterRates(array $rates): array
   {
       return array_filter($rates, fn($rate) => $rate['service'] !== 'CHR12');
   }
   

2. Add Tracking Events Extend Tracker to parse custom event data:

   class CustomTracker extends \Ekyna\Colissimo\Tracker
   {
       public function getEvents(): array
       {
           $status = parent::getStatus();
           return $this->parseEvents($status['events'] ?? []);
       }
   }
   

3. Webhook Integration Use Laravel’s HandleIncomingWebhook to process Colissimo webhooks:

   public function handle()
   {
       $payload = $this->payload();
       // Validate signature, then process (e.g., update shipment status).
   }