# 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…

- Strona: <https://www.datafirefly.com/pl/documentation/dfphoneintl/>
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfphoneintl/index.md), [en](https://www.datafirefly.com/en/documentation/dfphoneintl/index.md), [es](https://www.datafirefly.com/es/documentation/dfphoneintl/index.md), [de](https://www.datafirefly.com/de/documentation/dfphoneintl/index.md), [it](https://www.datafirefly.com/it/documentation/dfphoneintl/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfphoneintl/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfphoneintl/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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

Format przechowywania: dla polskiego klienta wpisującego `601234567` wartość zapisana w bazie to `+48601234567`, czyli numer kierunkowy kraju, usunięcie ewentualnego zera wiodącego (trunk prefix), bez spacji i separatorów.

## 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`.

Lista krajów wyświetlanych w selektorze pochodzi z krajów **aktywnych** w Twoim sklepie (Wysyłka, Strefy geograficzne, Kraje). Kraj wyłączony albo bez uzupełnionego numeru kierunkowego w kolumnie `call_prefix` nie pojawi się na liście.

## 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`.

Istniejące adresy **nie** są modyfikowane wstecznie przy instalacji. Normalizacja zadziała przy kolejnym zapisie każdego adresu. Aby znormalizować masowo istniejące dane, skontaktuj się ze wsparciem: skrypt SQL działający według tej samej logiki jest dostępny na życzenie.

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