LokiCheckout_PostcodeNl

Jump to User Docs

Checkout
Other
PHP 8.1 - 8.4
Magento 2.4.7 | 2.4.8
CSP Yes
Integration Tests 27
Functional Tests 5
PHPStan 1
Magento PHPCS 9
Latest Release 2.1.0

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

Note that this does not require any other third party module.

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:

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.git

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 > Mode
loki_checkout/postcode_nl/mode
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).
Postcode NL > Save region
loki_checkout/postcode_nl/save_region
Enable this, if you want to use the Postcode NL API service to autofill the region as well.
Loki Components

The following LokiComponents are created or references in this module:

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

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

LokiCheckout_Core Loki_Base Loki_Components Loki_CssUtils Loki_FieldComponents Loki_MapComponents Magento_Backend Magento_Catalog Magento_CatalogInventory Magento_Checkout Magento_CheckoutAgreements Magento_Config Magento_Customer Magento_Directory Magento_Eav Magento_MediaStorage Magento_Newsletter Magento_Payment Magento_Quote Magento_Sales Magento_SalesRule Magento_Shipping Magento_Store Magento_Tax Magento_Theme Magento_Vault Yireo_CspUtilities
Composer details
Magento module name
LokiCheckout_PostcodeNl
Composer name
loki-checkout/magento2-postcode-nl
Composer version
2.1.0
Default branch
main
Requirements
ext-json: *
guzzlehttp/guzzle: ^6.0|^7.0
loki-checkout/magento2-core: ^2.4
loki/magento2-components: ^2.0
loki/magento2-css-utils: ^1.0
loki/magento2-field-components: ^2.0
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
magento/module-store: ^101.0
psr/log: ^1.0 | ^2.0 | ^3.0
Releases
2.1.0 12 June 2026
2.0.26 12 June 2026
2.0.25 12 June 2026
2.0.24 12 June 2026
2.0.23 12 June 2026
2.0.22 12 June 2026
2.0.21 12 June 2026
2.0.20 12 June 2026
2.0.19 12 June 2026
2.0.18 12 June 2026
2.0.17 12 June 2026
2.0.16 12 June 2026
2.0.15 12 June 2026
2.0.14 12 June 2026
2.0.13 12 June 2026
2.0.12 12 June 2026
2.0.11 12 June 2026
2.0.10 12 June 2026
2.0.9 12 June 2026
2.0.8 12 June 2026
Changelog

[2.1.0] - 02 June 2026

Added

  • Add address search finder
  • Rename XML layout file from _theme_ to _skin_

Fixed

  • Move grid settings to loki-checkout/magento2-nl module
  • Bump requirement for loki-checkout/magento2-core to 2.4
  • Only change street1 and street2 to col-span-3 for default theme

[2.0.26] - 15 May 2026

Fixed

  • Fix Symfony 7 console command compat
  • Address autocomplete field

[2.0.25] - 06 May 2026

Fixed

  • Remove duplicate DI entries
  • After resetting the country, remove any Postcode NL messages

[2.0.24] - 17 March 2026

Fixed

  • Autofix housenumber addition without error to ease UI

[2.0.23] - 12 March 2026

Fixed

  • Enhance error message with "empty" and other additions
  • Allow for more translations

[2.0.22] - 27 February 2026

Fixed

  • Autocompletion state used null-country at first load

[2.0.21] - 19 February 2026

Fixed

  • Extend ToggleViewModel from FieldViewModel because of template

[2.0.20] - 18 February 2026

Fixed

  • Specifically disable validation for toggling
  • Use generic ViewModel for toggle field to reduce complexity
  • Fix integration test

[2.0.19] - 12 February 2026

Fixed

  • Allow PHP Config to read from current store level
  • Allow disable, enabled and save_region config per StoreView
  • Maximum streetline number should equal customer/address/street_lines

[2.0.18] - 28 January 2026

Fixed

  • Remove required-flag is field is disabled
  • Copy generic CI/CD files

[2.0.17] - 11 December 2025

Fixed

  • Rename deprecated AddressState::save/load to set/get

[2.0.16] - 03 November 2025

Fixed

  • Update composer keywords
  • Only run validation if enabled

[2.0.15] - 22 October 2025

Fixed

  • Fix wrong import of Console class, should by Symfony InputArgument
  • Allow for install under Symfony 5
  • Remove int return type from Symfony commands for Symfony 5 compat
  • Require countryId for usage of StreetLines
  • Allow psr/log 1 and 2 besides 3 as well
  • Double-check supported country before modifying fields via DI plugin
  • Do not escape $css() with escapeHtmlAttr() but escapeHtml()

[2.0.14] - 06 October 2025

Fixed

  • Throw error if customer/address/street_lines is wrong

[2.0.13] - 01 October 2025

Fixed

  • Convert API timeout from float to int
  • Update README

[2.0.12] - 24 September 2025

Fixed

  • Fix block rendering of static blocks

[2.0.11] - 16 September 2025

Fixed

  • Manual merging of LokiCheckout_PostcodeNl MR #11

[2.0.10] - 04 September 2025

Fixed

  • Rename FieldTemplateLocator to FieldTypeManager
  • Fix integration tests
  • Copy generic CI/CD files

[2.0.9] - 02 September 2025

Fixed

  • Refactor Loki-library location in Playwright tests

[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: June 1, 2026