SW Shopware 6 Shopware Beginner

DfAddressAutocomplete — Address Autocomplete for Shopware 6

Install, configure and extend multi-provider address autocomplete (BAN, Google Places) on Shopware 6.6/6.7.

Updated Module version 1.0.0

Overview

DfAddressAutocomplete adds an instant address search to Shopware 6 address forms: checkout, customer account address book and registration. The customer types the beginning of their address, picks a suggestion and every field fills itself — street, additional line, postcode, city and country.

Two providers ship out of the box: BAN (Base Adresse Nationale, free, France) and Google Places (New) (paid, worldwide). The architecture is extensible: any address API can be plugged in through a PHP interface.

Requirements

  • Shopware 6.6 or 6.7
  • PHP 8.2 or higher
  • For Google Places: a Google Cloud API key with the Places API (New) enabled (not the legacy Places API)

Installation

  1. Upload the ZIP into custom/plugins/ or through the Shopware admin (Extensions → My Extensions → Upload extension).
  2. Run the following commands:
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
  1. Compile the storefront so the JavaScript and CSS are bundled:
./bin/build-storefront.sh

On environments without the build script, use bin/console theme:compile after the assets have been compiled once.

Configuration

Go to Extensions → My Extensions → DfAddressAutocomplete → Configure. Every setting is sales-channel scopable.

Provider

  • Autocomplete provider: BAN (default) or Google Places.
  • Google Places API key: only required when Google is selected. The key stays server-side and is never sent to the browser.
  • Country restriction: comma-separated ISO 3166-1 alpha-2 codes (e.g. FR,BE,LU,CH). Blank = no restriction. Only applies to Google (BAN is France-only by nature).

Activation pages

Three independent switches: checkout, customer account (address book) and registration. Each can be enabled or disabled separately.

Behavior

  • Minimum characters (default 3): no search below this threshold.
  • Debounce delay (default 250 ms): wait time after the last keystroke before the API is queried.
  • Maximum suggestions (default 5).
  • Server-side cache (enabled by default): 5 minutes on searches, 15 minutes on details. Cuts Google billing and latency.

Setting up Google Places

  1. In the Google Cloud Console, create or select a project.
  2. Enable the Places API (New) — careful, not the legacy “Places API”.
  3. Create an API key and restrict it by server IP address (your Shopware hosting IP). Do not restrict it by HTTP referrer: the traffic is server-to-server.
  4. Paste the key into the plugin configuration.

The Places API (New) is billed per usage. The plugin’s server-side cache and debounce limit the number of calls, but monitor your consumption in the Google console.

How it works client-side

A search field appears above the standard address form. Keyboard navigation is complete: up/down arrows to browse suggestions, Enter to select, Escape to close. On selection, the standard Shopware fields are filled and the country is automatically selected in the dropdown.

Adding a custom provider

Implement the AutocompleteProviderInterface interface (namespace DataFirefly\DfAddressAutocomplete\Provider) in your own plugin:

final class MapboxProvider implements AutocompleteProviderInterface
{
    public function getKey(): string { return 'mapbox'; }

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Query your API and return an array of AddressSuggestion
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Resolve the id into a full AddressDetails
    }
}

Then tag the service in your services.xml (service id = your provider’s fully qualified class):

<service id="My\Plugin\MapboxProvider">
    <tag name="df_address_autocomplete.provider"/>
</service>

Every suggestion embeds its provider prefix in its id (e.g. mapbox:abc123): detail calls are routed automatically.

Custom themes

The plugin extends the standard component_address_form component and detects fields by their name (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). If your theme renames these fields, override the _cacheTargetFields method of the JavaScript plugin to teach it the new names.

Troubleshooting

  • The search field does not appear: make sure the storefront was recompiled after activation, and that the relevant page is enabled in the configuration.
  • No suggestions with Google: check that the Places API (New) is enabled on the project, that the key is valid and that its IP restriction matches your server’s IP.
  • The country is not selected: the plugin compares the ISO code with the data-country-iso attribute of the dropdown options, then with their visible text. If your theme exposes neither, the current country is kept.

Privacy (GDPR)

The plugin stores no personal data. User input flows through your Shopware server to the selected provider. With BAN, data is processed by a French public service (DINUM). With Google, it is subject to Google Cloud terms — mention it in your privacy policy if applicable.

Was this page helpful?

Still stuck? Contact support