Colissimo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cleverage/colissimo-bundle
   

   Add to config/bundles.php:

   CleverAge\ColissimoBundle\CleverAgeColissimoBundle::class => ['all' => true],
   

2. Configure: Create config/packages/cleverage_colissimo.yaml with your Colissimo credentials:

   clever_age_colissimo:
     testModeEnabled: true  # Set to false in production
     auth:
       contractNumber: 'YOUR_CONTRACT'
       password: 'YOUR_PASSWORD'
   

3. First Use Case: Inject PickupPointsService in a controller to fetch pickup points:

   use CleverAge\ColissimoBundle\Service\PickupPointsService;
   
   public function getPickupPoints(PickupPointsService $pickupPointsService): Response
   {
       $points = $pickupPointsService->getPickupPoints('75000', 'PARIS');
       return $this->json($points);
   }
   

Implementation Patterns

Common Workflows

1. Shipping Labels: Use ShippingService to generate labels with pre-configured sender details:

   $shippingService = $this->container->get(ShippingService::class);
   $label = $shippingService->createLabel(
       $recipientData,
       $serviceType, // e.g., 'LX' for Colissimo Letter
       $weight
   );
   

2. Tracking Integration: Fetch tracking status via TrackingService:

   $trackingService = $this->container->get(TrackingService::class);
   $status = $trackingService->getTrackingStatus('12345678901234567890');
   

3. Pickup Points for UX: Cache pickup points by postal code (e.g., in a PickupPointRepository):

   $points = $pickupPointsService->getPickupPoints($zipCode, $city);
   $this->cache->set("pickup_points_{$zipCode}", $points, '1 hour');
   

Integration Tips

• Symfony Forms: Bind PickupPoint entities to form fields for user selection:

  $builder->add('pickupPoint', EntityType::class, [
      'class' => PickupPoint::class,
      'choice_label' => 'name',
  ]);
  

• Event Listeners: Trigger actions on label generation (e.g., send email):

  $dispatcher->addListener(ShippingEvents::LABEL_CREATED, function (LabelEvent $event) {
      $this->mailer->send(new LabelGeneratedEmail($event->getLabel()));
  });
  

• Docker: Mock Colissimo API in tests using testModeEnabled: true with hardcoded responses.

Gotchas and Tips

Pitfalls

1. Authentication:

   • Error: 401 Unauthorized if contractNumber/password are incorrect.
   • Fix: Double-check config/packages/cleverage_colissimo.yaml and ensure no typos in credentials.

2. Rate Limits:

   • Colissimo API may throttle requests. Implement exponential backoff in custom services:

     try {
         return $service->getPickupPoints($zipCode);
     } catch (RateLimitException $e) {
         sleep(2 ** $attempt++);
         retry();
     }
     

3. Test Mode:

   • Warning: testModeEnabled: true bypasses real API calls but returns mock data. Disable in production:

     clever_age_colissimo:
       testModeEnabled: false  # Production!
     

4. Deprecated Services:

   • Some Colissimo services (e.g., older tracking versions) may not be supported. Check the API docs for updates.

Debugging

• Enable API Logging: Add to config/packages/cleverage_colissimo.yaml:

  debug: true
  

  Logs will appear in var/log/dev.log.

• HTTP Client Errors: Use HttpClientInterface to inspect raw responses:

  $client = $this->container->get(HttpClientInterface::class);
  $response = $client->send(new Request('GET', 'https://api.colissimo.fr/...'));
  $this->logger->debug($response->getContent());
  

Extension Points

1. Custom Responses: Extend CleverAge\ColissimoBundle\Service\AbstractService to modify API responses:

   class CustomPickupPointsService extends AbstractService {
       protected function transformResponse($response) {
           return array_map(fn($point) => [
               'id' => $point['id'],
               'formatted' => $point['name'] . ' (' . $point['distance'] . 'm)'
           ], parent::transformResponse($response));
       }
   }
   

   Register as a service in services.yaml:

   CleverAge\ColissimoBundle\Service\PickupPointsService: '@custom_pickup_points_service'
   

2. Async Processing: Use Symfony Messenger to queue label generation:

   $this->messageBus->dispatch(new GenerateLabelMessage($data));
   

   Handle in a worker with ColissimoMessageHandler.

3. Webhooks: Listen for Colissimo webhook events (e.g., tracking updates) by extending WebhookService:

   $webhookService->on('tracking_update', function (TrackingEvent $event) {
       $this->notifyUser($event->getTrackingNumber());
   });