README

DPD Connect Shipping — Hyvä

Hyvä Checkout compatibility module for DPD Connect Shipping. Replaces the Luma parcelshop picker with a native Alpine.js implementation — interactive map, address-based search, session persistence and checkout validation.

Features · Requirements · Installation · Configuration · Development · Support

📦 Features

🗺️ Parcelshop Selector

Feature	Description
Interactive map	DPDConnect JS widget embedded in the Hyvä checkout
Address-based search	Map centres on the customer's shipping address automatically
Google Maps support	Use a Google Maps API key or DPD's native map key
Change selection	Customer can re-open the map via a "Change parcelshop" link

🔒 Checkout Validation

Feature	Description
Required field	Blocks "Next" and "Place Order" until a parcelshop is selected
Inline error	Shows `This is a required field.` next to the checkout step button
Address guard	Shows an error if postcode or country is missing before opening the map

💾 Session Persistence

Feature	Description
SessionStorage	Selected parcelshop is stored per browser tab
Auto-restore	Selection is restored automatically on component mount
Address refresh	Re-evaluates stored selection when Magewire fires `shipping_address_saved`

🔌 Hyvä / Alpine.js Integration

Feature	Description
Native Alpine.js	Full `initDpdShipping()` Alpine component — no jQuery or KnockoutJS
Magewire bridge	Reads address directly from Magewire's `checkout.shipping-details.address-form`
Server-rendered HTML	Parcelshop confirmation HTML returned by Magento and rendered via `x-html`

✅ Requirements

Dependency	Version	Notes
PHP	`>=8.1`
Magento Framework	`>=103.0.6`	Magento 2.3+
`DpdConnect_Shipping`	any	Parent DPD shipping module
`Hyva_Checkout`	any	Hyvä Checkout module
`dpdconnect/php-sdk`	`^2.1`	Installed via Composer
DPDConnect JS	—	Loaded by `DpdConnect_Shipping`

🚀 Installation

composer require dpdconnect/magento2-shipping-hyva
bin/magento module:enable Hyva_DpdConnectShipping
bin/magento setup:upgrade
bin/magento cache:flush

Verify the module is active:

bin/magento module:status Hyva_DpdConnectShipping
# Module is enabled

⚙️ Configuration

All settings are managed by the parent DpdConnect_Shipping module.

Admin: Stores > Configuration > Sales > Shipping Methods > DPD

Setting	Config Key	Description
Parcelshop Token	`dpd_parcelshop_token`	DPD API token for the map widget
Save URL	`dpd_parcelshop_save_url`	POST endpoint to persist the selection
Use DPD Map Key	`dpd_parcelshop_use_dpd_key`	Toggle between DPD's key and Google Maps
Google Maps API Key	`dpd_parcelshop_google_key`	Required when not using DPD's own key
Locale	`dpd_locale`	Widget language (e.g. `nl`, `de`, `fr`)
Map Width	`dpd_googlemaps_width`	Map container width in pixels
Map Height	`dpd_googlemaps_height`	Map container height in pixels

🛠 Development

Module Structure

magento2-shipping-hyva/
├── registration.php
├── composer.json
├── etc/
│   └── module.xml                                # Load sequence: after DpdConnect_Shipping + Hyva_Checkout
├── ViewModel/
│   └── CheckoutConfig.php                        # Exposes CheckoutConfigProvider to Hyvä templates
└── view/frontend/
    ├── layout/
    │   └── hyva_checkout_components.xml          # Block injection into Hyvä checkout
    └── templates/checkout/shipping/
        ├── dpdshipping.phtml                     # Alpine.js component definition
        └── method/
            └── dpdpickup.phtml                   # Parcelshop picker UI

Key Classes

Class	Purpose
`DpdConnect\ShippingHyva\ViewModel\CheckoutConfig`	Wraps `CheckoutConfigProvider`, exposes `getConfig(): array` to templates

Alpine.js Component

The initDpdShipping() function (defined in dpdshipping.phtml, used via x-data in dpdpickup.phtml) exposes:

Method	Description
`init()`	Mount hook — restores selection or opens map; listens for Magewire address events
`showMap()`	Initialises DPDConnect widget with customer address
`selectParcelshop(parcelshop)`	Saves selection to sessionStorage and POSTs to saveUrl
`handleButtonClick(event)`	Validates selection on checkout step button click
`handleWindowClick(event)`	Handles "Change parcelshop" link clicks
`flatten(object)`	Serialises parcelshop object to `URLSearchParams`

Support

Report a problem on GitHub Issues.

Licensed under the GNU General Public License v3.0

dpdconnect / magento2-shipping-hyva

Package info

Security

Statistics