first commit
This commit is contained in:
96
README.md
Normal file
96
README.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# PrestaShop Phone Number Normalizer Module
|
||||
|
||||
[]
|
||||
[](https://www.prestashop.com)
|
||||
[](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).
|
||||
Reference in New Issue
Block a user