Download the PHP package keirontw/sylius-relay-point-plugin without Composer

Sylius Relay Point Plugin

Carrier-agnostic relay point ("point relais") selection for the Sylius 2.x checkout.

Any carrier — French or international — plugs in by implementing a single PHP interface. Geocoding is equally swappable: Addok (French BAN, default, no API key), Nominatim, Google Maps, or Photon.

Screenshots

Features

• Carrier-agnostic — implement RelayPointProviderInterface to add any carrier without touching the plugin core
• Geocoding-agnostic — switch between Addok, Nominatim, Google Maps, Photon, or your own backend via config
• Built-in providers — Mondial Relay, Chronopost, Shop2Shop, Colissimo, InPost, GLS, DPD, DHL, Packeta, PostNL, bpost (skeleton), Colis Privé (skeleton)
• Auto-injected checkout hook — appears automatically in sylius_shop.checkout.select_shipping via Twig Hooks, no template edit required
• Checkout UX — Stimulus controller + Leaflet map, embeddable in any Sylius checkout template
• Session persistence — selected relay point stored in session, readable server-side during checkout completion
• Built-in order subscriber — optional subscriber copies the relay point into the Sylius shipping address at checkout completion

Requirements

• PHP 8.2+
• Sylius 2.0+
• Symfony 7.4+
• ext-soap (for SOAP-based carriers: Mondial Relay, Chronopost, Colissimo, Colis Privé)
• symfony/http-client (for REST-based providers: InPost, GLS, DPD, DHL, Packeta, PostNL)

Installation

Register the plugin in config/bundles.php:

Import plugin routes in config/routes.yaml:

Configuration

Create config/packages/keirontw_sylius_relay_point.yaml:

bpost: bpost does not expose a public API for parcel point search. Access requires a verified business partner agreement via the OSP portal. Contact bpost at https://www.bpost.be/en/business. The BpostProvider skeleton is ready and only needs the correct endpoint and field mapping once credentials are obtained.

Colis Privé: the relay point search WSDL URL and method name must be confirmed with Colis Privé technical support before enabling this provider. The ColisPriveRelayProvider skeleton is ready.

Checkout integration

Automatic Twig Hook (recommended)

The plugin auto-registers itself in the sylius_shop.checkout.select_shipping hook via PrependExtensionInterface. No template changes are required — the widget appears automatically when the customer selects a shipping method whose code is listed in shipping_method_codes.

Override the hook priority if needed:

Manual embed (alternative)

For custom checkout flows that do not use Twig Hooks:

Register the Stimulus controller

Install the npm package:

Add the entry to your assets/controllers.json:

Without npm: copy assets/shop/controllers/relay-point-picker_controller.js into your project's assets/controllers/ and import it in your entrypoint.

Widget events

The Stimulus controller dispatches events that bubble to window:

When selectUrl is provided, the plugin automatically POSTs to the session on confirm. Listen to relay-point-picker:confirmed in your Stimulus controller to trigger the next checkout step:

Handle errors from the widget:

Order completion — built-in subscriber

When apply_relay_point_to_order: true (the default), the plugin registers RelayPointOrderSubscriber which:

1. Runs on the Sylius order completion event
2. Reads RelayPointSessionStorage::get($order->getTokenValue())
3. If a relay point is found, updates the shipping address (street, postcode, city, countryCode, company = relay point name)
4. Clears the session entry

No code change is needed. To disable it:

To extend the behaviour (e.g. store the relay point ID on a custom entity field), disable the built-in subscriber and write your own:

Customising the widget

CSS framework (Tailwind or Bootstrap)

The widget ships with a Tailwind-based layout by default, but the classes are not hardcoded in the template: every element resolves its class list through the relay_ui_class() Twig function, backed by Keirontw\SyliusRelayPointPlugin\Ui\RelayPointUiClasses. If your Sylius shop theme is still on Bootstrap, switch the theme in config — no template change needed:

This also covers the HTML the widget generates client-side (list items, the Leaflet popup, the carrier filter, opening hours). The Stimulus controller receives the active theme via data-relay-point-picker-theme-value and resolves the same semantic keys against its own UI_CLASSES map (assets/shop/controllers/relay-point-picker_controller.js) — the two class maps are kept manually in sync, so if you add a new element to the template, mirror the key in both RelayPointUiClasses and UI_CLASSES.

CSS variables (below) remain the recommended way to adjust colors/radius on either theme — you don't need to touch the class maps for a simple palette change.

CSS variables (theming — no Twig change needed)

All CSS is scoped to .relay-picker. Override the custom properties in your stylesheet:

Twig blocks (structural overrides — via {% embed %})

Use {% embed %} to override individual sections without duplicating the whole template:

Available blocks:

Full template override

Copy the template to your bundle override path — Symfony will use it automatically:

Adding a custom carrier

Implement RelayPointProviderInterface and tag the service. No YAML mapping needed — autoconfiguration applies the tag via _instanceof.

The provider is immediately visible in the registry — no further config needed.

Adding a custom geocoding provider

Troubleshooting

Widget does not appear at checkout

• Verify that the customer's shipping method code is listed in shipping_method_codes for at least one provider.
• If you use the Twig Hook, confirm that sylius_twig_hooks extension is active. Run bin/console debug:config sylius_twig_hooks and look for relay_point_picker in the hook.
• Call {{ relay_method_codes() }} in a template to dump all registered codes.

Geocode returns no result / map is blank

• The Addok endpoint (French BAN) only understands French addresses. Switch to Nominatim or Google Maps for non-French addresses.
• The widget dispatches relay-point-picker:error with the error message — attach a listener to surface it in the UI.

Search returns an empty list

• Check the credentials for the carrier (log level error in the channel keirontw_relay_point).
• Verify the radius (radius query param, default 10 000 m) is large enough for the queried area.
• Confirm the country code matches what the provider supports (e.g. GLS uses two-letter ISO codes in uppercase).

Relay point not saved to the order

• Make sure apply_relay_point_to_order: true (default).
• Confirm selectUrl is passed to the widget and that the POST succeeds (check Network tab — expect {"success":true}).
• The subscriber reads the session via cart token: cartToken must match order.tokenValue.

Licence

MIT. See LICENSE.