MAGIK-927: Global Phone Number Format & Validation

[MAGIKBIT]

Story 6 — Global Phone Number Format & Validation

Epic: EPIC-010 — Global Internationalization & Multi-Language Support (GitHub #100)
Priority: P1

User Story

As an international user, I want to enter my phone number in my local format with country code, and have it validated and stored correctly, so my contact information works globally.

Requirements

Phone Number Handling

• Input: Accept phone numbers in any local format with country code selector
• Validation: Use libphonenumber (Google) PHP library via Composer
• Storage: E.164 format in database (e.g., +12025551234, +251911234567)
• Display: Format per locale for display (e.g., (202) 555-1234 for US, 091 123 4567 for Ethiopia)

Country Code Selector

• Dropdown with flag emoji + country code + country name
• Default country based on user locale or existing phone number
• Key countries: US (+1), Ethiopia (+251), Eritrea (+291), Mexico (+52), Saudi Arabia (+966), UAE (+971)
• Full list of all ITU country codes

Validation Rules

Country	Format	Length	Example
US/CA	(XXX) XXX-XXXX	10 digits	+1 202 555 1234
Ethiopia	0XX XXX XXXX	9 digits (after 0)	+251 911 234 567
Eritrea	XX XXX XXXX	7 digits	+291 1 234 567
Mexico	XX XXXX XXXX	10 digits	+52 55 1234 5678
Saudi Arabia	0XX XXX XXXX	9 digits	+966 50 123 4567

Integration Points

• Profile settings phone field
• Registration form phone field
• Lead capture forms
• vCard export (TEL property with TYPE=CELL and international format)
• Admin user management phone display

Composer Dependency

• giggsey/libphonenumber-for-php — PHP port of Google libphonenumber
• Provides: validation, formatting, parsing, country detection

Acceptance Criteria

#	Criteria	Priority
1	Phone input shows country code selector with flags	P0
2	Phone numbers stored in E.164 format	P0
3	Validation rejects invalid numbers per country	P0
4	Display formatting matches local convention	P1
5	Existing US numbers migrated to E.164	P1
6	vCard TEL property uses international format	P1
7	libphonenumber integrated via Composer	P0
8	Country auto-detected from locale or existing number	P2

Files to Create

• app/app.portalv2/app/Libraries/PhoneService.php
• app/app.portalv2/public/js/phone-input.js — country selector + formatting
• sql/migration_phone_e164.sql

Files to Modify

• app/app.portalv2/composer.json — add libphonenumber dependency
• app/app.portalv2/app/Views/profile/settings.php — phone input component
• app/app.portalv2/app/Views/auth/registration.php — phone input component
• app/app.portalv2/app/Libraries/VcardService.php — international TEL format