Mondial Relay Bundle Laravel Package

Product Decisions This Supports

• Checkout & delivery experience: build vs. buy on the picker. v3.3.0 adds an api relay point picker (list + Leaflet map, own styles, no jQuery, no Mondial Relay script) as an alternative to the official widget. This turns a previously vendor-controlled surface into a product decision: you can now match the picker to your design system, avoid a third-party script (perf, CSP, privacy/GDPR surface), and A/B test the selection flow. That is a conversion-relevant lever, not just a technical one.
• Roadmap: cross-border shipping for FR/EU. Native EN/FR labels on the picker and on user-facing errors lower the cost of shipping to France, Belgium, Spain, Portugal, etc. Useful when scoping an EU expansion epic — the localization work is largely already done.
• Support cost reduction as a shippable outcome. MondialRelayErrorMessage::fromException() converts raw API failures into translated, actionable messages (invalid phone, unusable relay point, parcel weight, postal code, country, credentials, carrier unavailable). Combined with logging on the mondial_relay channel in every environment, this is a measurable lever on contact rate and checkout abandonment — frame it as a support-deflection initiative, not a refactor.
• Least privilege / security review. Credentials are renamed to MR Connect nomenclature (brand_code, api_login, api_password, private_key) and only the brand code is now mandatory — API user is needed only to create labels, private key only for API relay point search. That lets storefront-only deployments hold fewer secrets, and makes a partial misconfiguration fail only the feature that needs it, with a clear message.
• Build vs. buy on carrier integration. You are buying the Mondial Relay domain logic (SOAP/REST clients, parcel shop search, label creation, error taxonomy) and keeping only the UX and the business rules in-house. Worth stating explicitly in any buy-vs-build discussion that would otherwise produce a homegrown client.
• Upgrade planning as a roadmap item. This release carries breaking container changes and deprecations; it needs a scheduled slice of engineering capacity, not a drive-by dependency bump.
• Operational readiness. Cached search results and per-IP rate limiting on the relay point search endpoint (config/routes.php) are the kind of thing that matters on launch day / peak season — mention it when reviewing traffic and abuse assumptions.

When to Consider This Package

Consider it when:

• You sell physical goods into France/Europe and need Mondial Relay pickup point selection and/or shipment label creation, and you run a Symfony (or Symfony-kernel-based) PHP application with autowiring.
• You want the option to own the picker UI — either via relay_point_picker.mode: api / mondial_relay_widget(picker: 'api'), or by keeping the official widget and switching later without a rewrite.
• User-facing, translated failure messages matter to you (TranslatableInterface, English + French, generic fallback for unknown codes) — this is exactly the gap most carrier integrations leave to the frontend team.
• You want credential handling aligned to MR Connect and a lower-privilege storefront configuration.
• You can pin ernadoo/mondial-relay to ^4.1 (note: 4.0.x literally did not create labels — that is a strong reason to be on 4.1) and accept symfony/translation-contracts.

Look elsewhere or defer when:

• You are on Laravel. This is a Symfony bundle (@ErnadooMondialRelayBundle, Twig functions, service ids, bundle config). It is not drop-in for Laravel — adopting it means an adapter/bridge, or using the underlying ernadoo/mondial-relay library directly. Budget for that glue explicitly; it changes the build-vs-buy math.
• You need multi-carrier abstraction (DHL, UPS, Colissimo, GLS alongside Mondial Relay). This is single-carrier by design; wrapping it in your own shipping port is a prerequisite, not a feature.
• You need pickup points outside the Mondial Relay network, or you do not want a Mondial Relay account/contract at all.
• You fetch services by class name from the container (MondialRelayClient::class, RestShipmentClient::class, SoapParcelShopClient::class, Psr18Client::class), or inject PSR-18 clients expecting the bundle to register Symfony\Component\HttpClient\Psr18Client. These break in 3.3.0 — you must inject the MondialRelayClientInterface alias.
• You are on an old PHP/Symfony baseline, or a strict no-third-party-script / minimal-dependency posture that won't accept Leaflet assets.
• You need the picker to work in locales beyond English and French out of the box.

How to Pitch It (Stakeholders)

For executives (one paragraph): v3.3.0 upgrades our Mondial Relay shipping integration from "works" to "product-ready" at near-zero incremental cost. Three things change commercially: we can render the relay point picker in our own brand and styles instead of an embedded third-party widget (better page performance, fewer script/privacy dependencies, and a UI we can test and iterate on); customer-facing shipping errors arrive already translated and understandable, which should reduce checkout abandonment and support contacts; and the shipping integration now logs consistently across all environments, so failures are diagnosable in production. The upgrade itself is a small, well-scoped engineering task with a defined migration checklist — no new vendor contract, no new spend.

For engineering leads: Plan this as a contained dependency upgrade with three mandatory steps. (1) Require ernadoo/mondial-relay: ^4.1 — 4.0.x could not create labels. (2) Rename credentials to brand_code / api_login / api_password / private_key (env: MONDIAL_RELAY_BRAND_CODE, MONDIAL_RELAY_API_LOGIN, MONDIAL_RELAY_API_PASSWORD, MONDIAL_RELAY_PRIVATE_KEY); old names and mondial_relay_customer_id() still work but are deprecated, so plan removal. (3) Replace any container lookups by class name with autowired MondialRelayClientInterface; service ids are now bundle-prefixed and private, and the bundle no longer registers Psr18Client, so if you relied on that, register your own. Note the semantics change: only the brand code is mandatory, so a partially configured environment will boot fine and fail at feature use — add smoke tests for both relay point search (needs private_key) and label creation (needs api_login / api_password), and alert on the mondial_relay log channel.

For customer support / ops: Error codes are now mapped to user-readable messages in English and French (invalid phone number, unusable relay point, parcel weight, postal code, country, credentials, carrier unavailable, other rejections). Point CS at those strings when handling tickets, and use the mondial_relay channel for anything that does not resolve. Unknown codes fall back to a generic message by design — treat an uptick in generic messages as a signal that the carrier added a new rejection reason we should map.