International Phone Input (dfphoneintl)
Installation, settings, libphonenumber validation, storage formats and normalization of existing numbers for the international phone input module for PrestaShop 1.7.8 to 9.
Overview
DataFirefly International Phone Input (dfphoneintl) adds a country selector with flags in front of the Phone and Mobile phone fields of PrestaShop addresses. The number is formatted while it is typed, checked with Google’s libphonenumber numbering data, then saved in the format you choose.
New in 2.0.0: validation with Google libphonenumber data (browser and server), local SVG flags, keyboard-accessible combobox, choice of storage format (E.164, readable international, national), mobile type check, normalization tool for existing numbers with backup and undo, selector in the back office, 8 languages and PrestaShop 1.7.8 support.
Requirements
- PrestaShop 1.7.8 to 9.x (tested on 1.7.8.11, 8.2.1 and 9.1.5).
- PHP 7.1 or later (tested on PHP 7.4, 8.1 and 8.5).
- Classic, Hummingbird or a theme that keeps the
phone,phone_mobileandid_countryfield names. - No external service: data, flags and scripts are served by your shop, no CDN.
Installation and upgrade
- Download
dfphoneintl-2.0.0.zipfrom your DataFirefly account. - In Modules > Module Manager, click Upload a module and drop the zip.
- Open Configure: the page opens on the overview.
From 1.0.0, upload the 2.0.0 zip over the old module. The upgrade keeps your settings (enabled fields, preferred countries turned into favourites) and the 1.0.0 behaviour: E.164 storage and soft validation. Numbers already saved are not changed: the Existing numbers tab shows a preview first.
The selector for customers
The selector appears on address forms: My account > Addresses, the address step of the checkout (logged-in customer or guest) and the DataFirefly simplified checkout. Flags are SVG images, readable on every system, Windows included.

The search covers the country name in the customer’s language, the English name, the ISO code and the calling code (+41), accents ignored. The list works fully with the keyboard: arrow keys, Enter to choose, Escape to close.

Typing and checking
The number is formatted while it is typed, without the caret jumping. When the customer leaves the field, the server checks the number with the complete data (assigned ranges, mobile or landline) and shows the result under the field.

A number that is too short, too long, with an unknown calling code or a landline in the mobile field gets a translated message with the expected format. The digits of the example are masked (0• •• •• •• ••): no real number is shown.

A number pasted or typed with +1 or 001 switches the selector to the right country. A foreign number typed on a French address is shown in the international format, so that the server can always read it.

Mobile and checkout
On mobile, the list takes the full width, rows are at least 44 px high and the phone keypad opens (type="tel", inputmode="tel", autocomplete="tel").

In the checkout, the selector follows the Country field until the customer picks a calling code. Forms reloaded in AJAX are handled, without double initialisation.


The configuration page
The overview sums up the fields covered, the validation mode, the storage format and the countries offered. Points to check are listed with a link to the setting concerned, for example a country whose address format has no mobile field.

Fields and validation
- Phone and Mobile phone: enabled separately.
- The mobile field only accepts mobile numbers: a landline is refused there. Countries that do not separate mobiles and landlines (United States, Canada…) are accepted.
- Mobile number required: front office forms, for the countries whose address format shows the mobile field.
- Strict validation (recommended): a number that does not exist in the numbering plan of its country is refused with a message. Soft: a warning is shown but the address can still be saved.
- Live server check when the customer leaves the field. Nothing is saved or logged.

Storage format
Choose the value written in the address, the one your carriers, labels, exports, ERP and SMS modules read:
- E.164:
+33199001234, the format of SMS and WhatsApp gateways and of most APIs; - Readable international:
+33 1 99 00 12 34; - National:
01 99 00 12 34. A number from another country than the address stays international, otherwise it could not be called back.
The module also keeps the E.164 number and what the customer typed in its own table. A separate format can be chosen for the display in order e-mails, without changing the address. PDF invoices show the storage format.

Countries offered and default country
Offer all countries (a customer can give a number from another country than the delivery address), only the active countries of the shop or a list. Favourites are shown first, in the order you set. The country of the selector is chosen as follows:
- the country of the address;
- for a new address and if the option is enabled, the visitor’s country (PrestaShop geolocation, otherwise browser language);
- the default country of the shop.
Live preview
The Live preview tab uses the same selector and the same server check as your customers. Choose the address country and the field, type a number or click a fictional example: you see the type, the three formats, the saved value and the message, if any.


Normalizing existing numbers
The Existing numbers tab rewrites the numbers already saved in the storage format:
- Filter if needed (customer e-mail, countries, fields, deleted addresses), then click Analyse. The analysis is read-only.
- The report counts numbers already clean, to rewrite and invalid, with a before / after preview.
- Rewrite these numbers backs up each value before changing it. Invalid numbers are never rewritten. The modification date of the addresses is only updated if you ask for it.

Every run is listed in the history. Its backup can be downloaded as CSV and the run can be undone: a number changed since by the customer is kept.

Run the analysis on a sample first (filter by e-mail or country) and download the CSV backup before a full rewrite.
Back office and other channels
The selector and the same validation apply to the Customers > Addresses form of the back office (PrestaShop 1.7.8 to 9), to an address edited from an order and to the DataFirefly order creator.

Addresses saved by the webservice, CSV imports or other modules also go through the module while it is enabled: a valid number is written in the storage format, an invalid number is left as it is.
Compatibility
- Classic and Hummingbird themes, native checkout, guest checkout, dynamic country change.
- DataFirefly simplified checkout and Address Lookup: one selector per field, their settings are not changed.
- DataFirefly order creator: selector on its phone fields.
- A field can be excluded from the selector with the
data-dfpi-offattribute on one of its parents.
For developers
E.164 number of an address field, whatever the storage format:
Dfphoneintl::getE164($idAddress, 'phone_mobile'); // '+33199001234' or ''
Hooks used: actionFrontControllerSetMedia, actionValidateCustomerAddressForm, actionObjectAddressAddBefore / UpdateBefore / AddAfter / UpdateAfter / DeleteAfter, actionObjectCustomerDeleteAfter, actionCustomerAddressFormBuilderModifier, actionAdminControllerSetMedia, actionEmailSendBefore, actionDeleteGDPRCustomer, actionExportGDPRData.
Personal data and performance
- No phone number is written in the PrestaShop logs.
- The module table is cleared with the address, with the customer and by the official GDPR module.
- Files are only loaded on pages with an address form and on the back-office address pages. Compressed size (gzip): library 35.6 KB, script 9.5 KB, CSS 1.9 KB, flags 44.5 KB loaded once.
Troubleshooting
The selector is not shown
- Check that the module is enabled and that the field is ticked in Settings.
- The mobile field only appears if the country’s address format contains
phone_mobile(International > Locations > Countries). - If your shop combines CSS and JS (CCC), clear the cache in Advanced Parameters > Performance after an upgrade.
A number is refused
Open the Live preview with the same country and field: the exact reason is shown. Some ranges reserved for fiction or not assigned yet are not in the numbering data and are therefore refused in strict validation.
Uninstallation
Uninstalling deletes the settings, the normalization history and its backups. The numbers saved in the addresses stay as they are.
Third-party licences
The module bundles libphonenumber-js 1.13.15 (MIT), giggsey/libphonenumber-for-php 8.13.55 (Apache-2.0), the Google libphonenumber v9.0.41 data (Apache-2.0) and country-flag-icons 1.6.20 (MIT). Full texts are in THIRD_PARTY_LICENSES.md, at the root of the module.
Support
E-mail support and updates included for 12 months. 14-day money-back guarantee on all DataFirefly modules.