README

A lightweight PHP library to sanitize, validate, mask, and detect carriers of Vietnamese phone numbers 🇻🇳. Useful for backend validation, privacy masking, telco grouping, and data normalization.

✅ Features

• 🔒 Mask sensitive phone numbers (markPhone)
• 🧹 Sanitize & normalize phone strings (sanitize)
• 📲 Detect mobile carrier (Viettel, MobiFone, etc.)
• ✅ Validate if phone number is correct & valid
• 📊 Group phone numbers by carrier

📦 Installation

Install via Composer:

composer require hoang.tran/telco-utilities

----------------------------------------------------------------------------

🚀 Usage

use HoangTran\TelcoUtilities\PhoneHelper;

// Sanitize and normalize
$normalized = PhoneHelper::sanitize('+84 912 345 678');
// Output: 0912345678

// Validate
$isValid = PhoneHelper::isValidPhone('0968123456');
// Output: true

// Detect carrier
$carrier = PhoneHelper::detectCarrier('0968123456');
// Output: Viettel

// Mask phone number
$result = PhoneHelper::markPhone('0968123456');
// Output:
[
    'masked' => '096***3456',
    'raw'    => '0968123456',
    'valid'  => true,
    'carrier'=> 'Viettel',
    'error'  => null
]

// Group by carrier
$grouped = PhoneHelper::groupByCarrier([
    '0912345678',
    '0968123456',
    '0923456789',
]);
// Output:
[
    'Vinaphone'    => ['0912345678'],
    'Viettel'      => ['0968123456'],
    'Vietnamobile' => ['0923456789']
]

----------------------------------------------------------------------------

🛠 API Reference
| Method                    | Description                                   |
| ------------------------- | --------------------------------------------- |
| `sanitize($phone)`        | Remove non-digits, normalize +84/84 → 0       |
| `isValidPhone($phone)`    | Validate if phone is a valid VN mobile number |
| `detectCarrier($phone)`   | Return carrier name (e.g. Viettel, Vinaphone) |
| `markPhone(...)`          | Mask sensitive parts of phone number          |
| `groupByCarrier($phones)` | Group array of phone numbers by telco         |

----------------------------------------------------------------------------

📁 Directory Structure
telco-utilities/
├── src/
│   └── PhoneHelper.php
├── test.php
├── composer.json
└── README.md

----------------------------------------------------------------------------

📝 License
MIT © Hoang Tran

----------------------------------------------------------------------------

🙋‍♂️ Contributing
Pull requests are welcome! Please open an issue first to discuss any major changes.

----------------------------------------------------------------------------