Colissimo Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Ecosystem Alignment: The bundle is designed for Symfony 4/5/6, making it a seamless fit for Laravel applications only if leveraged via a Symfony microkernel or a Laravel-Symfony bridge (e.g., spatie/laravel-symfony). Native Laravel integration would require abstraction layers (e.g., facades, service containers) to map Symfony services to Laravel’s DI.
• Domain-Specific Focus: Specialized for Colissimo’s REST APIs (shipping, pickup points, tracking), reducing reinvention but limiting flexibility for other carriers. Ideal for e-commerce or logistics modules.
• Decoupling Potential: The bundle’s services (e.g., PickupPointsService, TrackingService) can be extracted into standalone PHP classes, wrapped in Laravel’s Illuminate\Support\Facades or a custom service provider for loose coupling. v1.1.3 reinforces this: TrackingService::call now accepts API-key authentication, so the tracking path can be wrapped independently of the contract-number/password credential model.

Integration Feasibility

• High-Level Abstraction: The bundle’s services are REST clients, which can be consumed via Guzzle HTTP client (already used in Laravel) or Symfony’s HttpClient. Minimal boilerplate needed for API calls.
• Configuration Override: Laravel’s .env can replace Symfony’s YAML config (e.g., CLEVERAGE_COLISSIMO_CONTRACT_NUMBER). Example:

  // config/services.php
  'colissimo' => [
      'contract_number' => env('COLISSIMO_CONTRACT_NUMBER'),
      'password' => env('COLISSIMO_PASSWORD'),
      'api_key' => env('COLISSIMO_API_KEY'), // v1.1.3: tracking auth
  ],
  

• Dual Authentication Paths (v1.1.3): Tracking can now authenticate with an API key instead of contract-number/password basic auth. This is a net simplification for tracking-only use cases (e.g., a customer-facing tracking widget that should not hold shipping credentials) and lets us scope the shipping credential to backend order-processing services only. It does, however, introduce a second credential set to provision, rotate, and monitor.
• Event-Driven Extensibility: Colissimo’s webhooks (e.g., tracking updates) can be adapted into Laravel events/listeners via custom middleware or queue jobs.

Technical Risk

• Symfony Dependency: Risk of compatibility issues with Laravel’s DI container (e.g., autowiring, service tags). Mitigate by:
  • Using symfony/dependency-injection as a standalone library.
  • Avoiding Symfony-specific annotations (e.g., @Route).
• API Versioning: Colissimo’s APIs may evolve; the v1.1.3 patch (Jan 2026 cadence) suggests active maintenance, but Laravel’s longer release cycle could cause drift. Plan for API version pinning.
• Authentication Surface Split: With API-key support added to tracking, the app now has two credential types with different blast radii and rotation policies. A leaked API key exposes tracking data; a leaked contract password exposes shipment creation. Risk is reduced overall (tracking no longer needs the higher-privilege credential), but secret management must be explicit.
• Testing Overhead: Symfony’s test utilities (e.g., WebTestCase) won’t integrate natively. Use Laravel’s Http or Mockery for unit tests. Add coverage for both auth modes on TrackingService::call.

Key Questions

1. Carrier Strategy: Is Colissimo the sole carrier, or will this coexist with other providers (e.g., FedEx)? If the latter, abstract the bundle into a carrier-agnostic service layer.
2. Real-Time vs. Batch: Does the app need real-time tracking (webhooks) or batch processing (queues)? The bundle supports both, but Laravel’s queue system (e.g., laravel-queue) may need adaptation.
3. Multi-Tenant: If supporting multiple merchants with different Colissimo contracts, ensure the bundle’s config is tenant-aware (e.g., via middleware or context managers). Are API keys per-tenant or per-platform?
4. Auth Mode Policy (v1.1.3): Should tracking standardize on API-key auth, or remain on contract credentials for consistency with shipping? Does the Colissimo account already have an API key provisioned, and what is its rotation policy?
5. Fallback Mechanisms: How will the app handle Colissimo API failures (e.g., retries, circuit breakers)? Laravel’s Illuminate\Support\Facades\Retry or spatie/laravel-queue-retries could integrate.
6. Localization: Colissimo’s pickup points/countries are FR-centric. Will the app support international shipments? Extend the bundle’s CountryCode enum or add validation.

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Symfony Bridge: Use spatie/laravel-symfony to embed the bundle in a Symfony microkernel within Laravel (e.g., for complex routing or forms).
  • Service Wrapper: For lightweight use, wrap the bundle’s services in Laravel’s App\Services\ColissimoService with Guzzle HTTP calls. Example:

    class ColissimoService {
        public function __construct(private Client $httpClient) {}
    
        public function getPickupPoints(string $zipCode) {
            return $this->httpClient->post('https://api.colissimo.fr/...', [
                'json' => ['zipCode' => $zipCode],
                'auth' => [env('COLISSIMO_CONTRACT_NUMBER'), env('COLISSIMO_PASSWORD')],
            ]);
        }
    
        public function track(string $parcelNumber) {
            // v1.1.3: API-key path, no contract credentials required
            return $this->httpClient->get("https://api.colissimo.fr/tracking/{$parcelNumber}", [
                'headers' => ['X-Api-Key' => env('COLISSIMO_API_KEY')],
            ]);
        }
    }
    

  • Facade Pattern: Expose bundle services via Laravel facades (e.g., Colissimo::pickupPoints()) for cleaner syntax.
• Database: The bundle doesn’t persist data; leverage Laravel’s Eloquent for tracking shipments/pickup points in local DBs.

Migration Path

1. Phase 1: Proof of Concept
   • Install the bundle in a Symfony microkernel (e.g., via spatie/laravel-symfony).
   • Test core services (shipping, pickup points, tracking) against Laravel’s HTTP layer.
   • Validate config translation from YAML to .env, including the new apiKey option.
2. Phase 2: Abstraction Layer
   • Create Laravel-specific service classes to hide Symfony dependencies.
   • Implement retries/circuit breakers (e.g., spatie/laravel-queue-retries).
3. Phase 3: Full Integration
   • Replace Symfony routes with Laravel routes (e.g., Route::post('/colissimo/pickup', [ColissimoController::class, 'pickupPoints'])).
   • Add webhook handlers for real-time tracking updates (e.g., ColissimoWebhookHandler listening to colissimo.tracking queue).

Compatibility

• PHP 7.4+: Laravel 9/10 supports this; no conflicts. v1.1.3 introduces no new platform requirements.
• Symfony Components: The bundle uses symfony/http-client, symfony/options-resolver, etc. These can be installed as standalone packages in Laravel:

  composer require symfony/http-client symfony/options-resolver
  

• Authentication (updated for v1.1.3):
  • Shipping / Pickup Points: contract number + password (basic auth) — unchanged.
  • Tracking: contract credentials or API key via the new TrackingService::call option. This removes the previous need to hand-roll an OAuth/API-key extension and reduces the privilege level required by tracking-only workloads.
  • OAuth: still not supported natively; extend via symfony/http-client’s auth stack if Colissimo moves that direction.

Sequencing

1. Prerequisites:
   • Set up Colissimo API credentials in .env (contract number, password, and now API key for tracking).
   • Install required Symfony components (if not using the full bundle).
2. Core Services:
   • Integrate PickupPointsService first (simplest API, contract auth).
   • Then ShippingService (more complex payloads, contract auth).
   • Finally TrackingService — now the cheapest to wire up thanks to v1.1.3’s API-key support; a good candidate for an early read-only slice to de-risk the integration.
3. Edge Cases:
   • Implement error handling for API rate limits (Colissimo’s SLA).
   • Add caching (e.g., Illuminate\Support\Facades\Cache) for pickup points to reduce API calls.
   • Handle missing/invalid API key independently of contract-credential failures so alerting is actionable.

Operational Impact

Maintenance

• Dependency Updates: Monitor cleverage/colissimo-bundle and Symfony components for breaking changes. v1.1.3 is a non-breaking additive patch (single PR, single contribution), so upgrade is low-risk — but pin to ^1.1.3 to lock in the API-key capability. Laravel’s slower release cycle may require backporting fixes.
• Configuration Drift: Centralize Colissimo config in .env to avoid YAML sprawl. Use Laravel’s config() helper to override defaults:

  'colissimo' => [
      'test_mode' => env('COLISSIMO_TEST_MODE', false),
      'auth' => [
          'contract_number' => env('COLISSIMO_CONTRACT_NUMBER'),
          'password' => env('COLISSIMO_PASSWORD'),
      ],
      'tracking' => [
          'api_key' => env('COLISSIMO_API_KEY'),
      ],
  ],
  

• Deprecation: Symfony 6 drops PHP 7.4 support; ensure Laravel’s PHP version aligns with the bundle’s requirements.

Support

• Debugging: Use Laravel’s dd() or Log::debug() to inspect Colissimo API responses. The bundle’s test mode (testModeEnabled: true) helps simulate API calls. With two auth paths, log which auth mode was used per tracking call to shorten incident triage.
• Vendor Lock-in: Minimize direct Symfony service usage. Prefer bundle’s public methods (e.g., getPickupPoints()) over internal classes.
• Community: Limited stars (8) and dependents (0) suggest niche adoption; v1.1.3 is a single-contributor change, so no broader ecosystem validation of the API-key path. Plan for self-support or direct vendor engagement (CleverAge).

Scaling

• API Rate Limits: Colissimo’s API limits may require:
  • Queueing requests (e.g., laravel-queue).
  • Caching responses (e.g., redis for pickup points).
• Horizontal Scaling: Stateless bundle services scale naturally with Laravel’s queue workers or job batches.
• Credential Scaling: API keys are simpler to distribute to read-only/edge consumers (e.g., a tracking microservice or support tooling) than contract credentials, letting tracking traffic scale on separate infrastructure without widening access to shipment creation.

Failure Modes

Ramp-Up

• Onboarding:
  • Documentation: Create a Laravel-specific README.md in your repo covering install, .env keys (including the new COLISSIMO_API_KEY), test-mode usage, and which services require which credential. Document why tracking uses API key vs. contract auth so future maintainers don’t collapse the two.
  • Runbook: One-page incident guide for auth failures, rate limits, and queue backlogs.
  • Training: Half-day walkthrough of the service wrapper, queue setup, and webhook handling for the on-call engineer.
  • Effort Estimate: ~1–2 engineer-weeks for Phases 1–2, plus ~1 week for webhook/queue hardening and documentation; v1.1.3 trims roughly a day of custom tracking-auth work from the original plan.
• Adoption Signal: The 1.1.2 → 1.1.3 turnaround and the responsiveness to an auth gap is a positive maintenance signal, but the single-PR release size means we should validate the API-key path ourselves in a staging environment before relying on it in production tracking flows.