DfAddressAutocomplete — Adress-Autovervollständigung für Shopware 6

Überblick

DfAddressAutocomplete fügt den Adressformularen von Shopware 6 eine Sofortsuche hinzu: im Checkout, im Adressbuch des Kundenkontos und bei der Registrierung. Der Kunde tippt den Anfang seiner Adresse, wählt einen Vorschlag und alle Felder füllen sich automatisch — Straße, Zusatz, Postleitzahl, Stadt und Land.

Zwei Anbieter sind enthalten: BAN (Base Adresse Nationale, kostenlos, Frankreich) und Google Places (New) (kostenpflichtig, weltweit). Die Architektur ist erweiterbar: Jede Adress-API kann über ein PHP-Interface angebunden werden.

Voraussetzungen

• Shopware 6.6 oder 6.7
• PHP 8.2 oder höher
• Für Google Places: ein Google-Cloud-API-Schlüssel mit aktivierter Places API (New) (nicht die alte Places API)

Installation

1. Laden Sie das ZIP in custom/plugins/ hoch oder über die Shopware-Administration (Erweiterungen → Meine Erweiterungen → Erweiterung hochladen).
2. Führen Sie folgende Befehle aus:

bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear

3. Kompilieren Sie die Storefront, damit JavaScript und CSS eingebunden werden:

./bin/build-storefront.sh

Konfiguration

Gehen Sie zu Erweiterungen → Meine Erweiterungen → DfAddressAutocomplete → Konfigurieren. Alle Einstellungen sind pro Sales Channel scopebar.

Anbieter

• Autovervollständigungsanbieter: BAN (Standard) oder Google Places.
• Google Places API-Schlüssel: nur erforderlich, wenn Google ausgewählt ist. Der Schlüssel bleibt serverseitig und wird nie an den Browser gesendet.
• Länderbeschränkung: kommagetrennte ISO-3166-1-alpha-2-Codes (z. B. FR,BE,LU,CH). Leer = keine Einschränkung. Gilt nur für Google (BAN ist naturgemäß auf Frankreich beschränkt).

Aktivierungsseiten

Drei unabhängige Schalter: Checkout, Kundenkonto (Adressbuch) und Registrierung. Jeder lässt sich einzeln aktivieren oder deaktivieren.

Verhalten

• Mindestzeichen (Standard 3): keine Suche unterhalb dieser Schwelle.
• Entprell-Verzögerung (Standard 250 ms): Wartezeit nach dem letzten Tastendruck, bevor die API abgefragt wird.
• Maximale Vorschläge (Standard 5).
• Serverseitiger Cache (standardmäßig aktiviert): 5 Minuten bei Suchen, 15 Minuten bei Details. Senkt Google-Kosten und Latenz.

Google Places einrichten

1. Erstellen oder wählen Sie in der Google Cloud Console ein Projekt.
2. Aktivieren Sie die Places API (New) — Achtung, nicht die alte „Places API“.
3. Erstellen Sie einen API-Schlüssel und beschränken Sie ihn per Server-IP-Adresse (die IP Ihres Shopware-Hostings). Beschränken Sie ihn nicht per HTTP-Referrer: Der Traffic läuft Server-zu-Server.
4. Fügen Sie den Schlüssel in die Plugin-Konfiguration ein.

Funktionsweise im Frontend

Über dem Standard-Adressformular erscheint ein Suchfeld. Die Tastaturnavigation ist vollständig: Pfeiltasten zum Durchblättern der Vorschläge, Enter zum Auswählen, Escape zum Schließen. Bei der Auswahl werden die Shopware-Standardfelder gefüllt und das Land automatisch im Dropdown ausgewählt.

Einen eigenen Anbieter hinzufügen

Implementieren Sie das Interface AutocompleteProviderInterface (Namespace DataFirefly\DfAddressAutocomplete\Provider) in Ihrem eigenen Plugin:

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

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Fragen Sie Ihre API ab und geben Sie ein Array von AddressSuggestion zurueck
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Loesen Sie die id in ein vollstaendiges AddressDetails auf
    }
}

Taggen Sie anschließend den Service in Ihrer services.xml (Service-ID = vollqualifizierte Klasse Ihres Anbieters):

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

Jeder Vorschlag trägt das Präfix seines Anbieters in seiner ID (z. B. mapbox:abc123): Detailaufrufe werden automatisch geroutet.

Individuelle Themes

Das Plugin erweitert die Standardkomponente component_address_form und erkennt Felder anhand ihres Namens (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). Falls Ihr Theme diese Felder umbenennt, überschreiben Sie die Methode _cacheTargetFields des JavaScript-Plugins mit den neuen Namen.

Fehlerbehebung

• Das Suchfeld erscheint nicht: Stellen Sie sicher, dass die Storefront nach der Aktivierung neu kompiliert wurde und die betroffene Seite in der Konfiguration aktiviert ist.
• Keine Vorschläge mit Google: Prüfen Sie, ob die Places API (New) im Projekt aktiviert ist, der Schlüssel gültig ist und die IP-Beschränkung zur IP Ihres Servers passt.
• Das Land wird nicht ausgewählt: Das Plugin vergleicht den ISO-Code mit dem Attribut data-country-iso der Dropdown-Optionen, dann mit deren sichtbarem Text. Stellt Ihr Theme keines von beiden bereit, bleibt das aktuelle Land erhalten.

Datenschutz (DSGVO)

Das Plugin speichert keinerlei personenbezogene Daten. Nutzereingaben laufen über Ihren Shopware-Server zum gewählten Anbieter. Bei BAN werden die Daten von einem französischen öffentlichen Dienst (DINUM) verarbeitet. Bei Google unterliegen sie den Google-Cloud-Bedingungen — erwähnen Sie dies gegebenenfalls in Ihrer Datenschutzerklärung.