Mondial Relay Bundle Laravel Package

Getting Started

• Install the underlying library at the required version: composer require ernadoo/mondial-relay:^4.1 (label creation is broken on 4.0.x). The bundle ships as a Symfony bundle; in a Laravel app you either register it through a bundle bridge or — the more common path — bind the library's MondialRelayClientInterface yourself in a service provider. Do not couple your code to the bundle's container ids.
• Set the four credentials in .env using the new MR Connect names: MONDIAL_RELAY_BRAND_CODE, MONDIAL_RELAY_API_LOGIN, MONDIAL_RELAY_API_PASSWORD, MONDIAL_RELAY_PRIVATE_KEY.
• Only the brand code is strictly required. The API login is needed to create labels, the private key to search relay points via the API. Missing credentials fail the specific feature with a clear message rather than the whole app — so start with the brand code and add the rest as you wire each feature.
• Look first at @ErnadooMondialRelayBundle/config/routes.php (the API relay-point search endpoint, cached and rate-limited), then the bundle config for relay_point_picker.mode.
• First use case: checkout delivery-point selection. Render the picker, persist the chosen relay point id on the order, then create the shipment/label with the injected client.

Implementation Patterns

• Picker selection. Two modes: the official Mondial Relay widget, or relay_point_picker.mode: api (equivalently mondial_relay_widget(picker: 'api')) which gives you a list + Leaflet map fed by the search API with no jQuery and no third-party script, styled by your own CSS. The API mode is the friendlier option in a Vite/Livewire/Tall-Kit front end.
• Dependency injection. Always inject MondialRelayClientInterface — that autowiring alias is unchanged. Expose it from a Laravel service provider with $this->app->bind(MondialRelayClientInterface::class, ...) and resolve via the container or constructor injection.
• Error handling. Wrap calls in try/catch and pass the exception to MondialRelayErrorMessage::fromException(); it returns a TranslatableInterface in the ErnadooMondialRelayBundle domain covering invalid phone number, unusable relay point, weight, postal code, country, credentials, MR unavailable and generic rejections. Requires symfony/translation-contracts. Translate it at the edge (Symfony translator, or map the message key into your Laravel lang/ files) and show it next to the form field that caused it.
• Logging. API errors, warnings and created shipments log to the mondial_relay channel in every environment. Wire that channel into config/logging.php (daily/slack) and keep it separate from your default stack so shipment failures are alertable.
• Search endpoint. The bundle's route already caches results and rate-limits per IP. Point your front-end at it rather than calling Mondial Relay from the browser; if you reimplement it, preserve both behaviours.
• Brand display. mondial_relay_brand_code() (and brand_code config) for anything that renders the brand in templates or on labels.

Gotchas and Tips

• Breaking service-id change. Services are now prefixed with the bundle alias (ernadoo_mondial_relay.client, ernadoo_mondial_relay.shipment_client, ernadoo_mondial_relay.parcel_shop_client, ernadoo_mondial_relay.http_client) and are private. Fetching MondialRelayClient::class, RestShipmentClient::class, SoapParcelShopClient::class or Psr18Client::class from the container no longer works, nor does $container->get() on the interface in Symfony. Inject the interface; never resolve by class name.
• Psr18Client collision resolved. The bundle no longer registers Symfony\Component\HttpClient\Psr18Client. If you previously relied on it being there, register your own — and if you had a duplicate registration, that conflict is now gone.
• Credential deprecations. customer_id, login, password, secret_key and the mondial_relay_customer_id() helper still work but are deprecated. Rename now to brand_code, api_login, api_password, private_key to avoid a hard break later.
• Error codes come from the sandbox. Codes not seen there fall through to a generic message; don't assume a code you received in production has a tailored translation. Log the raw code alongside the mapped message when debugging.
• Rate limiting is per IP. Behind a load balancer or proxy, make sure trusted-proxy/forwarded-header handling is correct, otherwise every user shares one bucket and the picker starts returning 429s in the wild.
• Environment coverage. Logging fires in all environments, so dev/staging will produce shipment logs too — scope retention accordingly.
• Translation contracts. MondialRelayErrorMessage needs symfony/translation-contracts; a Laravel app that only pulls illuminate components must add it explicitly or the class will fatal on autoload.