Mondial Relay Bundle Laravel Package

Technical Evaluation

Architecture fit: The v3.3.0 notes describe ErnadooMondialRelayBundle, a Symfony bundle, not a native Laravel package. It depends on Symfony bundle routing, DI service ids/autowiring, Twig functions, translation contracts, and a mondial_relay log channel. That is a poor architectural fit for a Laravel-only application using Illuminate container, Blade, Laravel routing/middleware, and Laravel logging. Fit is strong for a Symfony/Twig app and weak-to-moderate for Laravel unless the team deliberately wraps the underlying library.

New feature value: The api relay point picker is the most leverageable addition: a list and Leaflet map fed by the relay point search API, with no jQuery and no Mondial Relay script, plus custom styling. Its search endpoint caches results and rate-limits searches per IP. That reduces third-party front-end dependency and gives product/design control, but the endpoint lives in @ErnadooMondialRelayBundle/config/routes.php, so a Laravel integration must port or proxy it. The relay_point_picker.mode: api and mondial_relay_widget(picker: 'api') switches are Symfony/Twig-facing.

Error handling and observability: MondialRelayErrorMessage::fromException() maps Mondial Relay failures into translatable user messages: invalid phone number, unusable relay point, parcel weight, postal code, country, credentials, Mondial Relay unavailable, and other rejections. Unknown codes fall back to a generic message; it is based on sandbox codes and requires symfony/translation-contracts. English and French are provided, but other locales need mapping. Mondial Relay API errors, warnings, and created shipments are logged in every environment on the mondial_relay channel; TPM must verify credentials/PII redaction and add a matching Laravel channel if adapted.

Credential and breaking changes: Credentials now follow MR Connect naming: brand_code (formerly customer_id), api_login (login), api_password (password), private_key (secret_key). Former options still work but are deprecated, as is mondial_relay_customer_id(). The recipe uses MONDIAL_RELAY_BRAND_CODE, MONDIAL_RELAY_API_LOGIN, MONDIAL_RELAY_API_PASSWORD, and MONDIAL_RELAY_PRIVATE_KEY. Only the brand code is required; the API user is needed to create labels, and the private key is needed to search relay points through the API. Missing credentials fail the feature that needs them with a clear message. This is good feature-scoped configuration but requires migration action.

Dependency and container risk: The release requires ernadoo/mondial-relay 4.1 because label creation did not work with 4.0.x, and 4.1 brings logging and clear missing-credential messages. Pin >=4.1. Service ids now follow bundle best practices: 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 private. Injecting MondialRelayClientInterface remains supported via the autowiring alias; fetching MondialRelayClient::class, RestShipmentClient::class, SoapParcelShopClient::class, or Psr18Client::class from the container, or the interface with $container->get(), no longer works. The bundle no longer registers Symfony\Component\HttpClient\Psr18Client, which avoids collisions but breaks apps that assumed it. This is a container-level breaking change; in Laravel do not rely on Symfony autowiring—bind the interface to an explicit factory.

Technical risk: High for Laravel-native adoption due to framework mismatch; medium for Symfony. Key risks are porting the API picker endpoint safely, rate-limit correctness behind proxies, cache TTL/staleness, Leaflet/CSP/assets, credential migration, EN/FR-only translations, log redaction, reliance on sandbox-derived error codes, and label-creation compatibility. API picker requires private_key; label creation requires api_login; missing credentials fail by design but must be surfaced cleanly.

Key questions: Is the target app actually Laravel or Symfony? If Laravel, is there a maintained Laravel wrapper, or should we use ernadoo/mondial-relay 4.1 directly and build app-native bindings/routes/Blade component? What are the relay search endpoint contract, cache TTL, and rate-limit thresholds? How are trusted proxies and client IPs handled? Does the picker endpoint need auth/CSRF? Are logs redacted for credentials/PII? Are error codes stable and documented? What is the deprecation window for old credential names and mondial_relay_customer_id()? Do we use the official widget, API picker, or both? What locales beyond EN/FR are required? What PHP/Symfony/Laravel versions are supported, and what is the maintenance cadence/license?

Integration Approach

Stack fit: For Symfony/Twig, integration is mostly configuration: set relay_point_picker.mode: api if desired, use new env vars, inject MondialRelayClientInterface, require ernadoo/mondial-relay ^4.1, add symfony/translation-contracts, configure the mondial_relay channel, and replace concrete service fetches. For Laravel, do not install the Symfony bundle just for Twig functions or bundle routes. Use the underlying library as a PHP SDK and wrap it in a Laravel service provider, config, facade/adapter, routes/controller, Blade component, RateLimiter, Cache, log channel, and translations.

Migration path: Inventory current usage first: official MR widget vs API picker, label creation, relay point search, mondial_relay_customer_id(), concrete service fetches, and env names. Pin ernadoo/mondial-relay to ^4.1 and the bundle to v3.3.0. Rename env/config to MONDIAL_RELAY_BRAND_CODE, MONDIAL_RELAY_API_LOGIN, MONDIAL_RELAY_API_PASSWORD, and MONDIAL_RELAY_PRIVATE_KEY; keep old aliases only for one release cycle. Replace concrete container fetches with MondialRelayClientInterface injection or an explicit factory binding. Remove assumptions that the bundle registers Psr18Client; provide an app-owned PSR-18 client if needed. If adopting API picker in Laravel, port the search endpoint to a Laravel route/controller with cache and per-IP RateLimiter, and build a Blade + Leaflet component. Expose a mondial_relay_brand_code() helper or config value if templates need it. Map MondialRelayErrorMessage to Laravel translations or reuse translation-contracts if acceptable. Configure mondial_relay logging with redaction.

Compatibility: The bundle expects Symfony DI, bundle routing, Twig, and translation contracts. Laravel has Symfony components but not the bundle kernel; a bridge adds complexity. symfony/translation-contracts is installable in Laravel. Leaflet is front-end only; API mode removes jQuery/MR script requirements. Only brand code is mandatory, but label creation needs API login and relay-point API search needs private key; plan feature flags accordingly. Old credential names still work but are deprecated; new code should not use them. Service ids are private and prefixed; MondialRelayClientInterface remains the supported injection point.

Sequencing: 1) Decide Symfony-native vs Laravel-native adapter. 2) Pin v3.3.0 and ernadoo/mondial-relay ^4.1 in a branch. 3) Update env/config names and feature-scoped credential validation. 4) Replace container fetches with interface/factory. 5) If API picker: implement/port route, cache, IP rate limit, Leaflet UI, EN/FR labels, brand-code helper. 6) Wire error-message mapping and mondial_relay logging with redaction. 7) Test sandbox for label creation, relay search, missing-credential failures, invalid inputs, MR outage, and rate-limit/cache behavior. 8) Canary in production; monitor logs and error rates. 9) Remove deprecated aliases/functions after the deprecation window. 10) Update runbooks and support docs.

Operational Impact

Maintenance: For Symfony, maintenance is mostly dependency pinning, env migration, and replacing private service fetches. For Laravel, maintenance is higher: you own the adapter, picker route, Blade/Leaflet component, rate limiting, caching, logging, and translation mapping. Two release streams—the bundle and ernadoo/mondial-relay—must be tracked. v3.3.0 is a meaningful release because label creation requires 4.1 and service/container conventions changed; deferring keeps a known 4.0.x label-creation bug and misses logging/error improvements.

Support: Error messages are much better for end users and support: specific messages for phone, relay point, weight, postal code, country, credentials, Mondial Relay unavailable, and other rejections; unknown codes fall back generic. This reduces vague failures but only EN/FR are provided, so other locales need translation work. Missing-credential failures are clear and feature-scoped, which helps triage. The mondial_relay channel gives support a diagnostic trail if redaction is correct. Deprecated config names may create confusion; update docs and .env.example.

Scaling: The API picker search endpoint is cached and rate-limited per IP, which is the right shape for public relay search. In Laravel, replicate with Cache::remember and RateLimiter; include country/postal/city/search radius in cache keys and match TTL to relay data volatility. Watch cache stampede on popular queries and rate-limit bypass via proxy headers. Leaflet map loads client-side; no jQuery/MR script reduces third-party JS but adds asset/CSP management. Label creation and relay search have different credential and API quota profiles; monitor separately. Mondial Relay API rate limits are not specified here; load test before high-traffic campaigns.

Failure modes: Missing brand code fails all features; missing API login fails label creation; missing private key fails API relay search. Mondial Relay outage maps to “unavailable” if codes match, otherwise generic. Invalid phone/relay/weight/postal/country and credential rejection have specific messages. Container fetch of concrete clients or Psr18Client fails after upgrade; interface via $container->get() also fails—use injection/factory. The bundle no longer registers Psr18Client, so apps that relied on it must bind their own. The API picker endpoint may be abused if rate limiting is weak or IP resolution is wrong; cache may serve stale points. Leaflet/CSP issues can blank the map. Logging may expose credentials/PII if not redacted. Old env names still work but may break in a future release.

Ramp-up: Symfony teams: moderate; understand MR credentials, new service ids, Twig picker mode, error mapping, and logging channel. Laravel-only teams: high; need to learn the underlying MR SDK, Symfony bundle assumptions, Leaflet, Laravel rate limiting/caching, and translation-contracts or mapping. TPM should schedule a spike to validate direct library use in Laravel, confirm the API picker endpoint contract and rate-limit values, and test sandbox label creation before committing to the bundle. Budget for docs because release notes are Symfony-centric and Laravel integration guidance is not provided.