Międzynarodowy numer kierunkowy (dfphoneintl)

Prezentacja

DataFirefly International Phone Input (dfphoneintl) dodaje selektor międzynarodowego numeru kierunkowego z flagą do pól Telefon i Telefon komórkowy w PrestaShop oraz ujednolica numery w bazie danych do międzynarodowego formatu E.164. Moduł działa na dwóch poziomach: po stronie przeglądarki dla wygody użytkownika i po stronie serwera, aby zagwarantować, że każde dodanie albo aktualizacja adresu, także przez API, back office czy import, daje numer znormalizowany.

Wymagania

• PrestaShop od 8.0.0 do 9.99.99
• PHP minimum 7.4 (zalecane 8.1+)
• Żadnych zewnętrznych zależności, moduł nie zawiera bibliotek podmiotów trzecich

Instalacja

1. Pobierz archiwum dfphoneintl-1.0.0.zip ze swojego konta klienta DataFirefly.
2. W back office PrestaShop przejdź do Moduły, Menedżer modułów, Zainstaluj moduł.
3. Przeciągnij plik ZIP i kliknij Zainstaluj.
4. Moduł sam rejestruje się na potrzebnych hookach. Żadna tabela SQL nie jest tworzona, ponieważ numery kierunkowe są odczytywane z natywnej tabeli ps_country.

Konfiguracja

Przejdź do Moduły, Menedżer modułów, DataFirefly International Phone Input, Konfiguruj. Dostępne są trzy ustawienia:

• Włącz na polu „Telefon”: włącza albo wyłącza selektor i normalizację na polu phone.
• Włącz na polu „Telefon komórkowy”: to samo dla pola phone_mobile.
• Kraje preferowane: lista kodów ISO2 rozdzielonych przecinkami (na przykład pl,de,cz,sk,ua,gb). Te kraje są przypięte na górze listy rozwijanej. Wartość domyślna: fr,be,lu,ch,gb,us,de,es,it,nl.

Działanie po stronie klienta

Objęte strony

Selektor pojawia się na wszystkich stronach front office zawierających pola telefonu: tworzenie konta, rejestracja, zarządzanie adresami, proces zamówienia (pięcioetapowy i jednostronicowy), strona danych osobowych, strona kontaktu oraz śledzenie zamówienia gościa.

Synchronizacja z krajem

Gdy klient zmienia kraj w formularzu adresowym, numer kierunkowy w selektorze aktualizuje się automatycznie. Wybór Czech przełącza numer na +420, Niemiec na +49 i tak dalej. Ta synchronizacja działa także przy przeładowaniach AJAX natywnego checkoutu: moduł nasłuchuje zdarzeń PrestaShop updatedAddressForm, updatedAddress, updateCustomerAddressForm i changedCheckoutStep, a MutationObserver z debounce stanowi zabezpieczenie dla mocno personalizowanych motywów.

Wykrywanie na istniejących adresach

Jeśli pole zawiera już numer w formacie międzynarodowym (edycja istniejącego adresu), moduł wykrywa odpowiadający mu kraj przez dopasowanie najdłuższego numeru kierunkowego: +1242... jest rozpoznawane jako Bahamy, a nie jako Stany Zjednoczone.

Działanie po stronie serwera

Normalizacja serwerowa jest podpięta pod hooki actionObjectAddressAddBefore i actionObjectAddressUpdateBefore. Przed każdym INSERT albo UPDATE na tabeli ps_address pola phone i phone_mobile przechodzą przez klasę DfPhoneFormatter. Obejmuje to wszystkie kanały zapisu: formularze front office, back office, webservice, importy CSV oraz zewnętrzne moduły operujące na klasie Address.

Reguły normalizacji

Dla adresu przypisanego do kraju o numerze kierunkowym +48:

• Numer zaczynający się od +: zachowany bez zmian, usuwane są tylko separatory. +48 601 234 567 staje się +48601234567.
• Numer zaczynający się od 00: sekwencja 00 jest zastępowana znakiem +. 0048601234567 staje się +48601234567.
• Numer zaczynający się od 0 (trunk prefix): zero jest usuwane, a numer kierunkowy dodawany z przodu.
• Numer zaczynający się już od numeru kierunkowego bez +: dodawany jest sam znak +. 48601234567 staje się +48601234567.
• Inny numer złożony wyłącznie z cyfr: numer kierunkowy jest dodawany z przodu. 601234567 staje się +48601234567.

Zgodność z motywami i checkoutem

• Motyw Classic w PS 8 (Bootstrap 4) i motyw w PS 9 (Bootstrap 5) obsługiwane natywnie.
• Checkout pięcioetapowy i jednostronicowy (OPC) obsługiwane.
• Flagi to emoji Unicode (Regional Indicator Symbols): żadnego sprite’a ani CDN, renderowanie natywne przez wszystkie nowoczesne przeglądarki i systemy.
• Multistore: ustawienia globalne, lista krajów filtrowana per sklep.
• Wielojęzyczność: nazwy krajów wyświetlane w języku odwiedzającego.

Rozwiązywanie problemów

Selektor się nie wyświetla

• Sprawdź, czy dane pole jest włączone w konfiguracji modułu.
• Sprawdź, czy Twój motyw używa standardowych nazw pól phone i phone_mobile (albo address[phone] i address[phone_mobile]). Przy polu przemianowanym przez własny motyw skontaktuj się ze wsparciem.
• Wyczyść cache PrestaShop (Ustawienia zaawansowane, Wydajność) po instalacji.

Flagi wyświetlają się jako litery (PL, DE i inne)

To oczekiwane zachowanie na niektórych starszych systemach Windows, które nie renderują emoji flag. Numer kierunkowy +48 pozostaje widoczny, a moduł działa w pełni poprawnie.

Numer kierunkowy nie podąża za zmianą kraju

Przy bardzo personalizowanym motywie, którego lista wyboru kraju nie używa nazwy id_country, automatyczna synchronizacja nie ma się czego uchwycić. MutationObserver mimo to inicjalizuje widget ponownie, a klient może wybrać numer kierunkowy ręcznie. Skontaktuj się ze wsparciem, podając adres swojego sklepu, aby dostosować moduł.

Deinstalacja

Deinstalacja usuwa trzy klucze konfiguracyjne modułu. Numery już znormalizowane w bazie pozostają w formacie międzynarodowym, żadne dane klientów nie są zmieniane ani usuwane.

Wsparcie

Wsparcie e-mailowe w cenie, aktualizacje w cenie przez 12 miesięcy. Gwarancja satysfakcji albo zwrotu pieniędzy przez 14 dni na wszystkie moduły DataFirefly.