# PrestaShop Phone Number Normalizer Module

[![PHP Version](https://img.shields.io/badge/PHP-8.1-blue.svg?logo=PHP)]
[![PrestaShop Version](https://img.shields.io/badge/PrestaShop-8.x%20|%209.x-blue.svg?logo=prestashop)](https://www.prestashop.com)
[![License](https://img.shields.io/badge/license-AFL%203.0-green.svg)](https://opensource.org/licenses/AFL-3.0)

Tired of inconsistent phone number formats in your customer database? `(555) 123-4567`, `555.123.4567`, `+1 555 123 4567`... This module solves the problem by automatically sanitizing and normalizing customer phone numbers to the international **E.164 standard** (e.g., `+15551234567`).

It uses the powerful `giggsey/libphonenumber-for-php` library, a PHP port of Google's `libphonenumber`, to intelligently parse and format phone numbers based on the customer's country.

## Features

-   **Automatic Normalization on Save**: Hooks into the address creation and update process to normalize numbers in real-time. No manual action is needed for new addresses.
-   **E.164 International Format**: Converts valid phone numbers into a consistent, machine-readable format perfect for SMS gateways and other integrations.
-   **Country-Aware Parsing**: Uses the country selected in the customer's address as a hint to correctly interpret local and national phone number formats.
-   **Safe Fallback**: If a number cannot be fully parsed into a valid international format, it saves a sanitized version (digits and `+` only), **ensuring no customer-provided digits are ever lost**.
-   **Batch Processing**: Includes a Back Office tool to process and normalize all existing addresses in your database with a single click.
-   **Detailed Logging**: Every change made to a phone number is recorded in a log file for auditing and debugging purposes.

## Compatibility
-   PHP `8.1`
-   PrestaShop `8.0`
-   PrestaShop `9.x`

## Installation

You have two options for installation, depending on your needs.

### Method 1: Recommended (For Store Owners)

This is the easiest method. You will download a pre-packaged `.zip` file that already includes all the necessary libraries.

1.  Go to the [Releases page](https://github.com/panariga/prestashop-phonenormalizer/releases) of this repository.
2.  Download the latest `phonenormalizer.zip` file.
3.  In your PrestaShop Back Office, navigate to **Modules > Module Manager**.
4.  Click on the **"Upload a module"** button and select the `.zip` file you downloaded.
5.  After the module uploads, find "Phone Number Normalizer" in the module list and click **Install**.

### Method 2: Manual / Developer (Using Composer)

Use this method if you have cloned the repository and have command-line access to your server.

1.  Clone this repository into your PrestaShop `modules/` directory:
    ```bash
    git clone https://github.com/panariga/prestashop-phonenormalizer.git phonenormalizer
    ```
2.  Navigate into the new module directory:
    ```bash
    cd phonenormalizer
    ```
3.  Install the required PHP dependencies using Composer:
    ```bash
    composer install --no-dev --prefer-dist
    ```
4.  In your PrestaShop Back Office, navigate to **Modules > Module Manager**.
5.  Find "Phone Number Normalizer" in the module list and click **Install**.

## Usage

### Automatic Normalization

Once the module is installed, it works automatically. When a customer creates a new address or updates an existing one, the `phone` and `phone_mobile` fields will be processed and normalized before being saved to the database.

### Batch Normalization (For Existing Addresses)

To clean up all the addresses that were in your database before you installed the module:

1.  Navigate to **Modules > Module Manager**.
2.  Find **Phone Number Normalizer** in the list and click its **Configure** button.
3.  You will see a "Batch Processing" panel. **Please read the warning!** It is highly recommended to **back up your `ps_address` database table** before running this process.
4.  Click the **"Normalize All Existing Addresses"** button.
5.  The process may take some time depending on the size of your database. Once complete, you will see a confirmation message indicating how many addresses were updated.

## Logging

All changes made by this module are logged for your review. This is useful for seeing exactly what was changed and why.

-   **Log file location**: `[prestashop_root]/var/logs/modules/phonenormalizer/phonenormalizer.log`

-   **Example log entry**:
    ```log
    2023-10-27 14:35:01 [REAL-TIME] - Address ID: 12 - Changed field 'phone' FROM '(555) 123-4567' TO '+15551234567'
    2023-10-27 14:40:11 [BATCH] - Address ID: 25 - Changed field 'phone_mobile' FROM '06.12.34.56.78' TO '+33612345678'
    ```

## Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

## License

This module is licensed under the [Academic Free License (AFL 3.0)](https://opensource.org/licenses/AFL-3.0).

---

Developed by [panariga](https://github.com/panariga).