# Prefisso Telefonico Internazionale (dfphoneintl)

> Panoramica DataFirefly International Phone Input (dfphoneintl) aggiunge un selettore di prefisso telefonico con bandiera sui campi Telefono e Telefono cellulare di PrestaShop e uniforma i numeri al formato internazionale E.164…

- Pagina: <https://www.datafirefly.com/it/documentation/dfphoneintl/>
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [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), [pl](https://www.datafirefly.com/pl/documentation/dfphoneintl/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfphoneintl/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfphoneintl/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## Panoramica

DataFirefly International Phone Input (`dfphoneintl`) aggiunge un selettore di prefisso telefonico con bandiera sui campi **Telefono** e **Telefono cellulare** di PrestaShop e uniforma i numeri al formato internazionale E.164 nel database. Il modulo agisce su due livelli: lato browser per l'esperienza utente e lato server per garantire che ogni inserimento o aggiornamento di indirizzo — anche via API, back-office o importazione — produca un numero normalizzato.

Formato di archiviazione: per un cliente francese che inserisce `0633547864`, il valore salvato nel database è `+33633547864` — prefisso del paese, rimozione dello 0 iniziale (trunk prefix), nessuno spazio né separatore.

## Requisiti

- PrestaShop da 8.0.0 a 9.99.99
- PHP 7.4 minimo (8.1+ consigliato)
- Nessuna dipendenza esterna — il modulo non include alcuna libreria di terze parti

## Installazione

1. Scaricate l'archivio `dfphoneintl-1.0.0.zip` dal vostro account cliente DataFirefly.
2. Nel back-office di PrestaShop, andate su **Moduli → Gestione moduli → Carica un modulo**.
3. Trascinate il file ZIP e fate clic su **Installa**.
4. Il modulo si registra automaticamente sugli hook necessari. Non viene creata alcuna tabella SQL — i prefissi vengono letti dalla tabella nativa `ps_country`.

## Configurazione

Andate su **Moduli → Gestione moduli → DataFirefly International Phone Input → Configura**. Sono disponibili tre impostazioni:

- **Attivare sul campo «Telefono»** — attiva o disattiva il selettore e la normalizzazione sul campo `phone`.
- **Attivare sul campo «Telefono cellulare»** — lo stesso per il campo `phone_mobile`.
- **Paesi preferiti** — elenco di codici ISO2 separati da virgole (es. `fr,be,lu,ch,gb,us,de`). Questi paesi sono fissati in cima al menu a discesa. Valore predefinito: `fr,be,lu,ch,gb,us,de,es,it,nl`.

I paesi mostrati nel selettore provengono dai paesi **attivati** nel vostro negozio (Spedizione → Località → Paesi). Un paese disattivato, o senza prefisso definito nella colonna `call_prefix`, non appare.

## Funzionamento lato client

### Pagine coperte

Il selettore appare su tutte le pagine front-office con campi telefono: creazione account, registrazione, gestione indirizzi, checkout (5 passaggi e one-page), pagina identità, pagina contatti e tracciamento ordini ospite.

### Sincronizzazione con il paese

Quando il cliente cambia il paese nel modulo indirizzo, il prefisso del selettore si aggiorna automaticamente. Selezionare Belgio passa il prefisso a +32, Germania a +49, ecc. Questa sincronizzazione funziona anche durante i ricaricamenti AJAX del checkout nativo: il modulo ascolta gli eventi PrestaShop `updatedAddressForm`, `updatedAddress`, `updateCustomerAddressForm` e `changedCheckoutStep`, con un MutationObserver con debounce come rete di sicurezza per i temi molto personalizzati.

### Rilevamento su indirizzi esistenti

Se il campo contiene già un numero in formato internazionale (modifica di un indirizzo esistente), il modulo rileva il paese corrispondente tramite corrispondenza del prefisso più lungo (longest dial-code match): `+1242...` viene riconosciuto come Bahamas e non come Stati Uniti.

## Funzionamento lato server

La normalizzazione lato server è collegata agli hook `actionObjectAddressAddBefore` e `actionObjectAddressUpdateBefore`. Prima di ogni INSERT o UPDATE sulla tabella `ps_address`, i campi `phone` e `phone_mobile` passano attraverso la classe `DfPhoneFormatter`. Questo copre tutti i canali di scrittura: moduli front, back-office, webservice, importazioni CSV e moduli di terze parti che manipolano la classe `Address`.

### Regole di normalizzazione

Per un indirizzo associato a un paese con prefisso +33:

- Numero che inizia con `+` → conservato così com'è, vengono rimossi solo i separatori: `+33 6 33 54 78 64` diventa `+33633547864`.
- Numero che inizia con `00` → il `00` viene sostituito da `+`: `0033633547864` diventa `+33633547864`.
- Numero che inizia con `0` (trunk prefix) → lo `0` viene rimosso e il prefisso viene anteposto: `0633547864` diventa `+33633547864`.
- Numero che inizia già con il prefisso senza `+` → viene semplicemente aggiunto il `+`: `33633547864` diventa `+33633547864`.
- Qualsiasi altro numero composto solo da cifre → il prefisso viene anteposto.

Gli indirizzi esistenti **non** vengono modificati retroattivamente all'installazione. La normalizzazione si applica al successivo salvataggio di ciascun indirizzo. Per una normalizzazione massiva dei dati esistenti, contattate il supporto — uno script SQL con la stessa logica è disponibile su richiesta.

## Compatibilità temi e checkout

- Tema Classic PS 8 (Bootstrap 4) e tema PS 9 (Bootstrap 5) supportati nativamente.
- Checkout a 5 passaggi e one-page checkout (OPC) supportati.
- Le bandiere sono emoji Unicode (Regional Indicator Symbols): nessuno sprite né CDN, resa nativa su tutti i browser e sistemi moderni.
- Multinegozio: parametri globali, elenco paesi filtrato per negozio.
- Multilingua: nomi dei paesi mostrati nella lingua del visitatore.

## Risoluzione dei problemi

### Il selettore non appare

- Verificate che il campo sia attivato nella configurazione del modulo.
- Verificate che il vostro tema usi i nomi di campo standard `phone` / `phone_mobile` (o `address[phone]` / `address[phone_mobile]`). Per un campo rinominato da un tema personalizzato, contattate il supporto.
- Svuotate la cache di PrestaShop (Parametri avanzati → Prestazioni) dopo l'installazione.

### Le bandiere vengono mostrate come lettere (FR, BE...)

Comportamento previsto su alcuni vecchi sistemi Windows che non visualizzano le emoji bandiera. Il prefisso `+33` resta visibile e il modulo rimane pienamente funzionante.

### Il prefisso non segue il cambio di paese

Su un tema molto personalizzato il cui select del paese non usa il nome `id_country`, la sincronizzazione automatica non può agganciarsi. Il MutationObserver reinizializza comunque il widget e il cliente può scegliere manualmente il prefisso. Contattate il supporto con l'URL del vostro negozio per un adattamento.

## Disinstallazione

La disinstallazione rimuove le tre chiavi di configurazione del modulo. I numeri già normalizzati nel database restano in formato internazionale — nessun dato cliente viene modificato o eliminato.

## Supporto

Supporto via email incluso, aggiornamenti inclusi per 12 mesi. Garanzia soddisfatti o rimborsati di 14 giorni su tutti i moduli DataFirefly.