Libphonenumber For Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require giggsey/libphonenumber-for-php
   

   Add to composer.json if using a monorepo or custom setup:

   "repositories": [
       {
           "type": "vcs",
           "url": "https://github.com/giggsey/libphonenumber-for-php"
       }
   ]
   

2. First Use Case: Validate & Parse a Phone Number

   use libphonenumber\PhoneNumberUtil;
   use libphonenumber\PhoneNumberFormat;
   
   $phoneUtil = PhoneNumberUtil::getInstance();
   $number = $phoneUtil->parse('+14155552671', 'US'); // Parse with region
   
   // Validate and format
   if ($phoneUtil->isValidNumber($number)) {
       $formatted = $phoneUtil->format($number, PhoneNumberFormat::E164);
       // Output: +14155552671
   }
   

3. Key Files to Reference

   • vendor/giggsey/libphonenumber-for-php/src/ (Core classes)
   • vendor/giggsey/libphonenumber-for-php/data/ (Phone metadata)
   • Google’s libphonenumber docs (Concepts)

Implementation Patterns

Core Workflows

1. Validation & Sanitization

   $phoneUtil = PhoneNumberUtil::getInstance();
   $number = $phoneUtil->parseAndValidate('123-456-7890', 'US');
   // Returns null if invalid, otherwise a PhoneNumber object
   

2. Geocoding & Region Detection

   $regionCode = $phoneUtil->getRegionCodeForNumber($number);
   $nationalNumber = $phoneUtil->getNationalSignificantNumber($number);
   

3. Batch Processing

   $numbers = ['+442071838750', '1234567890'];
   $results = collect($numbers)->map(function ($num) use ($phoneUtil) {
       return $phoneUtil->parse($num, 'GB') ?: null;
   })->filter();
   

4. Integration with Laravel Requests

   use Illuminate\Http\Request;
   
   public function store(Request $request) {
       $phoneUtil = PhoneNumberUtil::getInstance();
       $phone = $request->input('phone');
   
       $parsed = $phoneUtil->parse($phone, 'US');
       if (!$phoneUtil->isValidNumber($parsed)) {
           return back()->withErrors(['phone' => 'Invalid number']);
       }
   
       // Store E164 format
       $this->user->phone = $phoneUtil->format($parsed, PhoneNumberFormat::E164);
   }
   

5. Testing

   use libphonenumber\PhoneNumberUtil;
   use PHPUnit\Framework\TestCase;
   
   class PhoneNumberTest extends TestCase {
       public function testValidUSNumber() {
           $phoneUtil = PhoneNumberUtil::getInstance();
           $number = $phoneUtil->parse('+14155552671', 'US');
           $this->assertTrue($phoneUtil->isValidNumber($number));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Region Ambiguity

   • Parsing without a region (e.g., parse('1234567890')) defaults to PhoneNumberUtil::DEFAULT_REGION.
   • Fix: Always specify a region or handle ambiguity:

     $number = $phoneUtil->parse('02071838750'); // UK vs. other regions
     $region = $phoneUtil->getRegionCodeForNumber($number);
     

2. Performance with Large Datasets

   • PhoneNumberUtil is not thread-safe. Reuse the singleton instance:

     // ❌ Bad (creates new instance per call)
     $phoneUtil->parse(...);
     
     // ✅ Good (reuse instance)
     $phoneUtil = PhoneNumberUtil::getInstance();
     

3. Edge Cases in Validation

   • Some numbers (e.g., toll-free, VoIP) may pass validation but behave unexpectedly.
   • Tip: Use isPossibleNumber() for lenient checks:

     if (!$phoneUtil->isPossibleNumber($number)) {
         // Handle potential invalid formats
     }
     

4. Time Zone Data

   • The package includes time zone data for geocoding. If missing, download from Google’s repo.

5. Deprecated Methods

   • Avoid PhoneNumberUtil::getDefaultInstance() (use getInstance()).
   • Prefer PhoneNumberFormat::E164 over PhoneNumberFormat::INTERNATIONAL.

Debugging Tips

• Log Parsed Numbers:

  $number = $phoneUtil->parse('+442071838750');
  \Log::debug('Parsed:', [
      'number' => $number->getNationalNumber(),
      'region' => $phoneUtil->getRegionCodeForNumber($number),
      'valid' => $phoneUtil->isValidNumber($number),
  ]);
  

• Test with Known Values: Use Google’s test data to verify edge cases.

Extension Points

1. Custom Metadata Override default phone metadata (e.g., for internal extensions):

   $phoneUtil->setMetadataProvider(new CustomMetadataProvider());
   

2. Event Hooks Extend validation logic via closures:

   $validator = Validator::make($request->all(), [
       'phone' => ['required', function ($attribute, $value, $fail) {
           $phoneUtil = PhoneNumberUtil::getInstance();
           $number = $phoneUtil->parse($value);
           if (!$phoneUtil->isValidNumber($number)) {
               $fail('The '.$attribute.' must be a valid phone number.');
           }
       }],
   ]);
   

3. Caching Cache PhoneNumberUtil instance in Laravel’s cache:

   $phoneUtil = Cache::remember('phoneUtil', 365 * 24 * 60, function() {
       return PhoneNumberUtil::getInstance();
   });