DfAddressAutocomplete: autouzupełnianie adresu dla Shopware 6

Wprowadzenie

DfAddressAutocomplete dodaje błyskawiczne wyszukiwanie adresu do formularzy adresowych Shopware 6: checkoutu, książki adresowej konta klienta i rejestracji. Klient wpisuje początek adresu, wybiera podpowiedź i wszystkie pola wypełniają się automatycznie: ulica, dodatkowe informacje, kod pocztowy, miasto i kraj.

W zestawie są dwa providery: BAN (Base Adresse Nationale, darmowy, Francja) i Google Places (New) (płatny, cały świat). Architektura jest rozszerzalna: dowolne API adresowe można podłączyć przez interfejs PHP.

Wymagania

• Shopware 6.6 lub 6.7
• PHP 8.2 lub nowszy
• Dla Google Places: klucz API Google Cloud z aktywowanym Places API (New) (nie starym Places API)

Instalacja

1. Wgraj ZIP do custom/plugins/ lub przez administrację Shopware (Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie).
2. Wykonaj następujące komendy:

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

3. Skompiluj storefront, aby JavaScript i CSS zostały dołączone:

./bin/build-storefront.sh

Konfiguracja

Przejdź do Rozszerzenia → Moje rozszerzenia → DfAddressAutocomplete → Konfiguruj. Wszystkie ustawienia można zawężać per sales channel.

Provider

• Provider autouzupełniania: BAN (domyślnie) lub Google Places.
• Klucz API Google Places: wymagany tylko przy wybraniu Google. Klucz pozostaje po stronie serwera i nigdy nie jest wysyłany do przeglądarki.
• Ograniczenie krajów: kody ISO 3166-1 alpha-2 rozdzielone przecinkami (np. PL,DE,CZ,FR). Puste = brak ograniczeń. Ograniczenie dotyczy tylko Google (BAN z natury obejmuje wyłącznie Francję).

Strony aktywacji

Trzy niezależne przełączniki: checkout, konto klienta (książka adresowa) i rejestracja. Każdy włącza się lub wyłącza osobno.

Zachowanie

• Minimalna liczba znaków (domyślnie 3): poniżej tego progu wyszukiwanie nie startuje.
• Opóźnienie debounce (domyślnie 250 ms): czas oczekiwania po ostatnim naciśnięciu klawisza przed odpytaniem API.
• Maksymalna liczba podpowiedzi (domyślnie 5).
• Cache serwerowy (domyślnie włączony): 5 minut na wyszukiwania, 15 minut na szczegóły. Zmniejsza rachunki Google i opóźnienia.

Konfiguracja Google Places

1. W Google Cloud Console utwórz lub wybierz projekt.
2. Aktywuj Places API (New); uwaga, nie stare “Places API”.
3. Utwórz klucz API i ogranicz go po adresie IP serwera (adres Twojego hostingu Shopware). Nie ograniczaj go po referrerze HTTP: ruch odbywa się server-to-server.
4. Wklej klucz w konfiguracji pluginu.

Działanie po stronie klienta

Nad standardowym formularzem adresowym pojawia się pole wyszukiwania. Nawigacja klawiaturą jest kompletna: strzałki góra/dół do przeglądania podpowiedzi, Enter do wyboru, Esc do zamknięcia. Po wyborze standardowe pola Shopware zostają wypełnione, a kraj jest automatycznie wybierany z listy rozwijanej.

Dodanie własnego providera

Zaimplementuj interfejs AutocompleteProviderInterface (namespace DataFirefly\DfAddressAutocomplete\Provider) we własnym pluginie:

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
    }
}

Następnie otaguj serwis w swoim services.xml (id serwisu = pełna klasa Twojego providera):

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

Każda podpowiedź niesie prefiks swojego providera w identyfikatorze (np. mapbox:abc123): routing wywołań szczegółów jest automatyczny.

Niestandardowe motywy

Plugin rozszerza standardowy komponent component_address_form i wykrywa pola po ich nazwie (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). Jeśli Twój motyw zmienia nazwy tych pól, nadpisz metodę _cacheTargetFields pluginu JavaScript, aby wskazać mu nowe nazwy.

Rozwiązywanie problemów

• Pole wyszukiwania się nie pojawia: sprawdź, czy storefront został przekompilowany po aktywacji oraz czy dana strona jest włączona w konfiguracji.
• Brak podpowiedzi z Google: sprawdź, czy Places API (New) jest aktywowane w projekcie, czy klucz jest prawidłowy i czy jego ograniczenie IP odpowiada adresowi IP Twojego serwera.
• Kraj się nie wybiera: plugin porównuje kod ISO z atrybutem data-country-iso opcji listy rozwijanej, a następnie z ich widocznym tekstem. Jeśli Twój motyw nie udostępnia ani jednego, ani drugiego, bieżący kraj zostaje zachowany.

Prywatność (RODO)

Plugin nie przechowuje żadnych danych osobowych. Wpisy użytkownika przechodzą przez Twój serwer Shopware do wybranego providera. Przy BAN dane są przetwarzane przez francuską służbę publiczną (DINUM). Przy Google podlegają warunkom Google Cloud; w razie potrzeby wspomnij o tym w swojej polityce prywatności.