Download the PHP package ernadoo/mondial-relay-bundle without Composer

ernadoo/mondial-relay-bundle

Symfony bundle for the ernadoo/mondial-relay PHP SDK.

• Autowiring of MondialRelayClientInterface: label creation and relay point search
• Symfony Profiler integration (call log, duration, errors)
• Relay point picker (Symfony UX): the official Mondial Relay widget, or a list + Leaflet map fed by the API (optional, requires symfony/stimulus-bundle)

Requirements

• PHP 8.2+
• Symfony 6.4, 7.x or 8.x (Symfony 8 requires PHP 8.4+)

Installation

If Symfony Flex is enabled the bundle registers automatically. Otherwise add it to config/bundles.php:

Configuration

Create config/packages/ernadoo_mondial_relay.yaml:

The credentials are named after MR Connect, Mondial Relay's customer area. Each one is only needed by the features that use it:

A missing credential only fails the feature that needs it, with a clear message and a log entry. Add them to your .env.local (never commit them):

Upgrading from 3.2 or older: the former options customer_id, login, password and secret_key still work but are deprecated: rename them brand_code, api_login, api_password and private_key. The Twig function mondial_relay_customer_id() becomes mondial_relay_brand_code().

Sandbox

sandbox: true sends label creation to https://connect-api-sandbox.mondialrelay.com/api/shipment: labels are generated ("SANDBOX MODE") but nothing is recorded. It needs a valid API user. Relay point search always uses the production endpoint. Enable it outside production, for example:

Usage

Inject MondialRelayClientInterface anywhere in your application.

Creating a label

Handling errors

Every failure throws a MondialRelayException: ApiException when Mondial Relay rejects the request (with its codes, getErrors()), TransportException when it cannot be reached or answers with an unusable response, ConfigurationException when a credential is missing. Their messages are in English, for developers and logs.

To tell your users what went wrong, MondialRelayErrorMessage turns the exception into a translatable message (TranslatableInterface), in the ErnadooMondialRelayBundle domain:

English and French are provided. The list of Mondial Relay codes is partial (Mondial Relay does not publish it): unknown codes fall back to error.rejected. Override or add languages as usual, with a translations/ErnadooMondialRelayBundle.<locale>.xlf file in your application.

Searching relay points

Symfony Profiler

In debug mode, every call to createShipment() and searchParcelShops() appears in the Mondial Relay panel of the Symfony Profiler: method, parameters, result, duration and error, if any. Label creation also shows up in the HTTP Client panel.

With symfony/stopwatch installed, calls also appear in the Performance timeline (category mondial_relay), next to your controllers and database queries.

Nothing is recorded by the Profiler outside debug mode.

Logs

In every environment, the client logs on the mondial_relay channel (Monolog, or any PSR-3 logger registered as logger):

Credentials, request and response bodies, and addresses are never logged. To send these logs to a dedicated file with Monolog:

Relay point picker

The picker is optional: label creation and relay point search work without it. Two modes:

Both modes need:

• symfony/stimulus-bundle: it loads the Stimulus controllers shipped with this bundle. Without it, mondial_relay_widget() renders an empty block.
• AssetMapper or Webpack Encore to serve the JavaScript. Projects created with symfony new --webapp already have AssetMapper and StimulusBundle.

With AssetMapper, the controllers are registered automatically. With Webpack Encore, run npm install --force then rebuild your assets.

To use the api mode, import the routes of its search endpoint and choose it:

Options, highlighting a saved relay point, filling your own form fields, theming and the select event are described in the relay point picker documentation.

Tests