LokiCheckout_PostcodeNl

Jump to User Docs

Other
PHP 8.3 | 8.4
Magento 2.4.7 | 2.4.8
Integration Tests 27
Functional Tests 5
Latest Release dev-feature/improve-ux

This is an add-on package for adding support for the Postcode NL address validation and autocompletion to the LokiCheckout.

Overview of this module

This module changes the layout of an address form, so that a streetname and city can be determined by entering a postcode and housenumber (plus housenumber addition). Because the Magento core stores the street as multiple streetlines, the fields are renamed by this module: The field street0 is renamed to Streetname, the field street1 is renamed to House Number, the field street2 is renamed to House Number Addition. The field street3 is not handled by this module.

The fields Streetname and City are disabled when autocompletion is enabled.

An additional checkbox Use autocompletion is added to allow customers to disable the Postcode NL lookup. When autocompletion is disabled (HTML attribute disabled), the fields Streetname and City are enabled again.

Thanks Trinos

Portions of this module are shamelessly copied (and rewritten) from the Trinos_PostcodeNL module. Thank you, Trinos, for kickstarting this module. Note that this module is not depending on the Trinos module though.

Installation

Install this package via composer (assuming you have setup the composer.yireo.com repository correctly already):

composer require loki-checkout/magento2-postcode-nl

Next, enable this module:

bin/magento module:enable LokiCheckout_PostcodeNl

Basic configuration

Configure the Postcode NL settings via the backend (Store > Configuration > Yireo > Loki Checkout > Postcode NL) or via the CLI:

magerun2 config:set loki_checkout/postcode_nl/enable 1
magerun2 config:set loki_checkout/postcode_nl/api_key YOUR_API_KEY
magerun2 config:set loki_checkout/postcode_nl/api_secret YOUR_API_SECRET

In the backend, you can also validate the credentials right away via the button Validate API credentials.

Dealing with streetlines

We recommend you to set the configuration value customer/address/street_lines to be 3.

If the configuration value customer/address/street_lines is 3, both the field House Number and House Number Addition are taken into account when dealing with the Postcode NL autocompletion. When there are multiple options for the housenumber addition, the House Number Addition changes from an input field to a select field. When there are no options to choose from, you can also disable the field itself by setting the configuration option Disable Empty House Number Addition to Yes. Likewise, the configuration option Require Housenumber to be Numeric can be enabled to force the value of the field House Number to be numeric.

If the configuration value customer/address/street_lines is 2, the field House Number Addition is never shown. Instead, the value of House Number allows for adding the addition as well (like: 10A). Here, it is assumed that the numerical prefix is the value for the house number (10) and the remainder is the addition (A). The configuration option Require Housenumber to be Numeric has no effect at this moment.

Debugging

When the configuration option Debug is enabled, a new block is shown in the checkout (with yellow background). The autocompletion state (saved to the checkout session) is shown.

Possible errors are shown as well. For instance Housenumber addition is not available: A [street1, street2] would tell you that a specific local error is shown for the components street1 and street2.

The raw API data show the response from the Postcode NL API.

CLI usage

This module also comes with a simple CLI command to check for specific addresses:

bin/magento loki-checkout:postcode-nl:check 1000AA 1 A

Support

For getting support, create an Issue under the following project URL:

https://gitlab.yireo.com/loki-checkout/LokiCheckout_PostcodeNl

Configuration Options

The following options of this module can be configured via the Store Configuration:

Postcode NL > Enable
loki_checkout/postcode_nl/enable
Enable or disable the functionality of Postcode NL
Postcode NL > Debug
loki_checkout/postcode_nl/debug
Display an additional block in the address with API details, like the raw API result, the values of errors and other handy information.
Postcode NL > API Key
loki_checkout/postcode_nl/api_key
The API Key as provided by Postcode EU
Postcode NL > API Secret
loki_checkout/postcode_nl/api_secret
The API Secret as provided by Postcode EU
Postcode NL > API Check
loki_checkout/postcode_nl/api_check
Hit the button and a check is performed to see if the API Key and API Secret are valid.
Postcode NL > API Client Timeout
loki_checkout/postcode_nl/api_client_timeout
A setting to determine after how many seconds an API client call times out.
Postcode NL > Require Housenumber to be Numeric
loki_checkout/postcode_nl/housenumber_number_validator
With this setting, the value of the "Housenumber" field must be numeric. Note, however, that enabling this might be conflicting with browser autofill options. Perhaps it is best to keep it disabled, even though the idea sounds good.
Postcode NL > Disable Empty House Number Addition
loki_checkout/postcode_nl/disable_empty_housenumber_addition
When an API call is made and the result suggests that no house number addition is available, this setting automatically disables the "House Number Addition" field (<code>street2</code> aka the third line of the multiline street value).
Loki Components

The following LokiComponents are created or references in this module:

loki-checkout.shipping.address.postcode_nl_toggle loki-checkout.billing.address.postcode_nl_toggle loki-checkout.shipping.address.postcode_nl_debug loki-checkout.billing.address.postcode_nl_debug loki-checkout.shipping.address.postcode loki-checkout.billing.address.postcode loki-checkout.shipping.address.street1 loki-checkout.billing.address.street1 loki-checkout.shipping.address.street2 loki-checkout.billing.address.street2 loki-checkout.shipping.address.country_id loki-checkout.billing.address.country_id
Module Dependencies

The following dependencies are declared in the module its `etc/module.xml` file:

Magento_Backend Magento_Checkout Magento_Config Magento_Customer Magento_Quote Magento_Store LokiCheckout_Core Loki_Components Loki_FieldComponents Yireo_IntegrationTestHelper
Composer details
Magento module name
LokiCheckout_PostcodeNl
Composer name
loki-checkout/magento2-postcode-nl
Composer version
2.0.8
Default branch
main
Requirements
magento/framework: ^103.0
magento/module-backend: ^102.0
magento/module-checkout: ^100.4
magento/module-config: ^101.0
magento/module-customer: ^103.0
magento/module-quote: ^101.0
loki-checkout/magento2-core: ^2.0
loki/magento2-field-components: ^2.0
loki/magento2-css-utils: ^1.0
loki/magento2-components: ^2.0
composer/composer: ^2.8
psr/log: ^3.0
guzzlehttp/guzzle: ^6.0|^7.0
ext-json: *
Releases
dev-feature/improve-ux 16 August 2025
dev-main 29 August 2025
2.0.8 27 August 2025
2.0.7 26 August 2025
2.0.6 21 August 2025
2.0.5 18 August 2025
2.0.4 15 August 2025
2.0.3 13 August 2025
2.0.2 06 August 2025
2.0.1 01 August 2025
2.0.0 22 July 2025
Changelog

[2.0.8] - 27 August 2025

Fixed

  • Make sure to extend default grid layout
  • Add new CI files
  • Replace yireo/opensearch with yireo/opensearch-dummy in Gitlab CI

[2.0.7] - 26 August 2025

Fixed

  • 2f549c1 Add GitLab CI files

[2.0.6] - 21 August 2025

Fixed

  • Add dependency with loki/magento2-css-utils
  • Add escaping of template code
  • Fix newlines after comments
  • Declare used PHP namespaces

[2.0.5] - 18 August 2025

Fixed

  • Lower requirements to PHP 8.1
  • Fix label ID
  • Move address template help from this module to official docs
  • Add new configuration option to skip saving the region
  • Fixes for radio buttons
  • Rename tab in Store Config from "Yireo" to "Loki"
  • Fix integration tests with ConfigFixture scope

[2.0.4] - 15 August 2025

Fixed

  • Implement new CSS class loki-col-span properly
  • Dutch translation of postcode and housenumber mismatch
  • Move config from Yireo tab to Loki tab
  • Add dep with LokiCheckout_Nl module

[2.0.3] - 13 August 2025

Fixed

  • Add error when house number does not match
  • Remove toggle button if API credentials are empty
  • Prevent invalid credentials from throwing fatal error

[2.0.2] - 06 August 2025

Fixed

  • Lower PHP requirement to PHP 8.2+

[2.0.1] - 01 August 2025

Fixed

  • Make strings translatable

[2.0.0] - 01 July 2025

Fixed

  • Upgrade to major 2

[1.0.3] - 20 June 2025

Fixed

  • Finalize new grid settings
  • Extend loki_checkout.xml default grid
  • Add Dutch translations
  • Make help text translatable

[1.0.2] - 20 June 2025

Fixed

  • Hide debug block if not enabled
  • Hide debug option if not enabled

[1.0.1] - 19 June 2025

Fixed

  • Use Loki test-case in Playwright to detect JS errors automatically
  • Rewrite @helpers to @loki in Playwright tests

[1.0.0] - 27 May 2025

Fixed

  • Add Integration Tests
  • Add Playwright tests
  • Properly check for enabled-flag everywhere

[0.0.14] - 26 May 2025

Fixed

  • Update admin settings with tooltip and regenerate new MODULE.json
  • Generate new MODULE.json with simple test count
  • Streamline when housenumber addition is incorrect
  • Allow PHP 8.4 in CI
  • Remove deprecated classes

[0.0.13] - 25 April 2025

Fixed

  • Allow upgrading to LokiFieldComponents and LokiCheckout 1.0
  • Allow upgrade to LokiComponents 1.0
  • Remove CheckoutSession from context
  • Remove FieldTemplateLocator from context
  • Remove CartRepository from all contexts
  • Reduce dependencies with CheckoutState::saveQuote()
  • Make loader icon in fields depend on Alpine and activate only after configurable timeout

[0.0.12] - 16 April 2025

Fixed

  • Move loki_checkout.xml of Nl and PostcodeNl module to Demo module
  • Disable housenumber_number_validator by default because it conflicts with autofill

[0.0.11] - 09 April 2025

Fixed

  • Fix formatting HTML
  • Fix broken HTML
  • Add help-text to toggle box

[0.0.10] - 08 April 2025

Fixed

  • Housekeeping changes

[0.0.9] - 11 March 2025

Fixed

  • Move GridLayout from XML layout to config
  • Remove default grid class
  • Add module dependencies
  • Huge refactoring to move logic into new LokiFieldComponents

[0.0.8] - 24 February 2025

Fixed

  • Add Dutch translations

[0.0.7] - 24 February 2025

Fixed

  • Housenumber addition error when switching country

[0.0.6] - 22 February 2025

Fixed

  • Update loki_checkout.xml grid CSS for mobile

[0.0.5] - 22 February 2025

Fixed

  • Small responsive fixes
  • Change deps
  • Refactor to reusable RegionProvider

[0.0.4] - 20 February 2025

Fixed

  • Trigger Postcode API when changing country as well
  • Improve loading logic of streetlines
  • Fix possible issues in API client (like timeouts and outage)

[0.0.3] - 18 February 2025

Fixed

  • Better logic when validating faulty housenumber values
  • Fix local messages per field
  • Allow housenumber to be non-numeric via config option
  • Remove debug warnings (because they are in backend System Check)

[0.0.2] - 17 February 2025

Fixed

  • Dump housenumber addition properly
  • Add warning about streetlines in debug box
  • Properly skip API when country is not supported; Fix housenumber additions completion

[0.0.1] - 21 January 2025

Fixed

  • Add proper deps
  • Initial release
Jump to User Docs

Last modified: July 22, 2025