PS PrestaShop Beginner

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.

Updated Module version 2.0.0

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_mobile and id_country field names.
  • No external service: data, flags and scripts are served by your shop, no CDN.

Installation and upgrade

  1. Download dfphoneintl-2.0.0.zip from your DataFirefly account.
  2. In Modules > Module Manager, click Upload a module and drop the zip.
  3. 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.

Country selector opened in front of the Phone field: SVG flags, calling codes and favourite countries first
Phone country selector

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.

Searching a country by its name in the customer's language, accents ignored
Country search

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.

Number formatted while typing and confirmed by the server check: valid, with its type
Valid number checked by the server

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.

Number too short: translated message under the field with the expected format, digits masked
Error: number too short

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.

International number pasted: the selector switches to the right country by itself
Pasted international number

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").

On mobile: full-width list, large tap targets and phone keypad
Selector on mobile

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.

Hummingbird checkout as a guest: address step with the selector and the checked number
Hummingbird checkout
Classic theme checkout: same selector and same check at the address step
Classic checkout

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.

Module overview: fields covered, validation, storage format and points to check
Module overview

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.
Field and validation settings: strict or soft, mobile numbers only, server check
Field and validation settings

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.

Choice of storage format (E.164, readable international, national) and format in e-mails
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:

  1. the country of the address;
  2. for a new address and if the option is enabled, the visitor’s country (PrestaShop geolocation, otherwise browser language);
  3. 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.

Live preview: British number on a French address, read, validated and saved in E.164
Live preview
Preview: a landline typed in Mobile phone is refused with a clear message
Landline refused in the mobile field

Normalizing existing numbers

The Existing numbers tab rewrites the numbers already saved in the storage format:

  1. Filter if needed (customer e-mail, countries, fields, deleted addresses), then click Analyse. The analysis is read-only.
  2. The report counts numbers already clean, to rewrite and invalid, with a before / after preview.
  3. 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.
Normalization report of the existing numbers: already clean, to rewrite, invalid, before / after preview
Normalization report

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.

Normalization history: CSV backup and undo of a run
History and undo

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.

Address in the back office: selector on Phone and Mobile phone, error and Australian mobile detected
Address in the back office

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-off attribute 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.

Was this page helpful?

Still stuck? Contact support