Ws Colissimo Laravel Package

Getting Started

This is a standalone PHP library, not a Laravel package. There's no service provider, facade, or publishable config. You wire it yourself.

composer require lexik/ws-colissimo

Register credentials in config/services.php and .env:

// config/services.php
'colissimo' => [
    'wsdl'     => env('COLISSIMO_WSDL'),
    'login'    => env('COLISSIMO_LOGIN'),
    'password' => env('COLISSIMO_PASSWORD'),
],

Bind the client as a singleton in AppServiceProvider so the WSDL is parsed once per process:

$this->app->singleton(\Lexik\WSColissimo\Client\WSColissimoClient::class, fn () => new \Lexik\WSColissimo\Client\WSColissimoClient(
    config('services.colissimo.wsdl'),
    config('services.colissimo.login'),
    config('services.colissimo.password'),
    ['trace' => true, 'connection_timeout' => 15]
));

First use case: generate one label from an order. Build a LetterRequest (sender, addressee, parcel, service code such as COL / DOS), call getLabel(), then download the returned pdfUrl immediately and store it. Look first at src/Model/Request/ for the request objects and WSColissimoClient for the operation surface.

Implementation Patterns

• Wrap the SOAP layer in App\Services\ColissimoLabelService and inject the client. Nothing above that service should know about SOAP.
• Queue it. GenerateColissimoLabel job with retries/backoff. The SOAP endpoint is slow; never call it inline in a checkout or web request.
• One call per parcel. For multi-parcel orders, build a fresh LetterRequest per parcel — don't mutate and reuse a single request object, or fields leak between labels.
• Persist parcelNumber before anything else. That's your carrier tracking number (parcelNumberPartner is just your reference). If the response is lost, the label is orphaned.
• Storage pipeline: $response->getPdfUrl() / getCn23PdfUrl() → Storage::disk('labels')->put(...) → store the local path on the Shipment model. Keep the raw URL only as a debug artefact.
• Manifests: schedule a command that calls the manifest operation for the previous day's shipments and stores the bordereau PDF. Same download-immediately rule applies.
• Testing: SoapClient isn't mockable. Type-hint an interface you own (LabelGenerator) and swap in a fake in tests that returns canned response objects. Enable trace => true in dev and log __getLastRequest() / __getLastResponse() on failures.

Gotchas and Tips

• Archived. No fixes for PHP 8.x SoapClient deprecations or endpoint changes will land. Pin the exact version, audit it before each PHP upgrade, and have a plan to replace it.
• WSDL caching: SoapClient caches WSDLs in sys_get_temp_dir(). In Docker this produces stale-cache failures after endpoint changes — clear the cache in your deploy script or set soap.wsdl_cache_ttl.
• French accents in sender/addressee fields get mangled. Normalise with Str::ascii() before building the request; Colissimo either rejects or garbles non-ASCII names.
• No hard address validation. getAddress doesn't prevent a typo from producing a printed label. Validate upstream.
• Per-service limits (weight, dimensions) differ and exceeding them raises \SoapFault. Catch it and surface faultstring — the raw message is unreadable to customers.
• Timeouts: set connection_timeout and ensure your queue worker's --timeout is longer than the SOAP call, or the worker is killed mid-call.
• Idempotency: there is none. If the request succeeds but your DB write fails, you've paid for a label you can't associate. Write the tracking number to a durable log first, or reconcile against the manifest.
• Sandbox vs production: Colissimo issues a separate test WSDL and dummy account. Pointing production credentials at the test endpoint produces labels that are rejected at drop-off.