Libphonenumber For Php Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require giggsey/libphonenumber-for-php:^9.0

Note: Updated to version 9.0+ to leverage latest metadata and features.

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

   use libphonenumber\PhoneNumberUtil;
   use libphonenumber\PhoneNumberFormat;
   
   $phoneUtil = PhoneNumberUtil::getInstance();
   $number = $phoneUtil->parse('+919876543210', 'IN'); // Updated India metadata
   
   // Validate and format
   if ($phoneUtil->isValidNumber($number)) {
       $formatted = $phoneUtil->format($number, PhoneNumberFormat::NATIONAL);
       // Output: 9876543210 (India national format)
   }
   

3. Key Files to Reference

   • vendor/giggsey/libphonenumber-for-php/src/ (Core classes, v9.0+)
   • vendor/giggsey/libphonenumber-for-php/data/ (Updated metadata for CL, CZ, DE, IN, SG)
   • Google’s libphonenumber v9.0 docs

Implementation Patterns

Core Workflows

1. Region-Specific Formatting (New in v9.0)

   $phoneUtil = PhoneNumberUtil::getInstance();
   $number = $phoneUtil->parse('+49301234567', 'DE'); // Germany
   
   // Use NATIONAL format for local display
   $formatted = $phoneUtil->format($number, PhoneNumberFormat::NATIONAL);
   // Output: 030 1234567 (Germany national format)
   

2. Carrier Detection (Enhanced in v9.0)

   $phoneUtil = PhoneNumberUtil::getInstance();
   $number = $phoneUtil->parse('+56912345678', 'CL'); // Chile
   
   $carrier = $phoneUtil->getNumberType($number);
   // Returns PhoneNumberType::MOBILE, FIXED_LINE, etc.
   

3. Batch Processing with Updated Metadata

   $numbers = ['+919876543210', '+420123456789', '+8613800138000'];
   $results = collect($numbers)->map(function ($num) use ($phoneUtil) {
       $parsed = $phoneUtil->parse($num);
       return [
           'number' => $parsed,
           'valid' => $phoneUtil->isValidNumber($parsed),
           'region' => $phoneUtil->getRegionCodeForNumber($parsed),
       ];
   })->filter(fn($item) => $item['valid']);
   

4. Integration with Laravel Requests (v9.0 Compatibility)

   use Illuminate\Http\Request;
   use libphonenumber\PhoneNumberUtil;
   
   public function store(Request $request) {
       $phoneUtil = PhoneNumberUtil::getInstance();
       $phone = $request->input('phone');
   
       $parsed = $phoneUtil->parse($phone);
       if (!$phoneUtil->isValidNumber($parsed)) {
           return back()->withErrors(['phone' => 'Invalid number']);
       }
   
       // Store in E164 format (recommended for databases)
       $this->user->phone = $phoneUtil->format($parsed, PhoneNumberFormat::E164);
   
       // Optional: Store carrier/type for analytics
       $this->user->phone_type = $phoneUtil->getNumberType($parsed)->getName();
   }
   

5. Testing with Updated Regions

   use libphonenumber\PhoneNumberUtil;
   use PHPUnit\Framework\TestCase;
   
   class PhoneNumberTest extends TestCase {
       public function testValidIndiaNumber() {
           $phoneUtil = PhoneNumberUtil::getInstance();
           $number = $phoneUtil->parse('+919876543210', 'IN');
           $this->assertTrue($phoneUtil->isValidNumber($number));
           $this->assertEquals('IN', $phoneUtil->getRegionCodeForNumber($number));
       }
   
       public function testGermanyFormatting() {
           $phoneUtil = PhoneNumberUtil::getInstance();
           $number = $phoneUtil->parse('+49301234567', 'DE');
           $this->assertEquals('030 1234567', $phoneUtil->format($number, PhoneNumberFormat::NATIONAL));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Breaking Changes in v9.0

   • Deprecated: PhoneNumberUtil::getDefaultInstance() (use getInstance()).
   • Removed: Legacy PhoneNumberFormat::INTERNATIONAL in favor of E164 for consistency.
   • Fix: Update all format calls to use PhoneNumberFormat::E164 or NATIONAL.

2. Region-Specific Quirks (v9.0 Updates)

   • India (IN): Updated alternate formatting (e.g., 919876543210 → 9876543210).
   • Germany (DE): New national formatting rules (e.g., +49301234567 → 030 1234567).
   • Chile (CL) / Czechia (CZ): Carrier data may now return more granular types.
   • Tip: Test with local numbers for these regions post-upgrade.

3. Performance with Carrier Data

   • Carrier detection (getNumberType) is now more accurate but slightly slower.
   • Optimization: Cache results for frequent lookups:

     $carrierCache = Cache::remember("carrier_{$phone}", 365, function() use ($phoneUtil, $number) {
         return $phoneUtil->getNumberType($number)->getName();
     });
     

4. Metadata Loading Issues

   • If you encounter missing data for regions like CL, CZ, or SG, ensure you’re using the latest data/ files from the package.
   • Debug: Verify metadata files exist in vendor/giggsey/libphonenumber-for-php/data/.

5. Time Zone Data for Geocoding

   • Updated geocoding data for 91 (India) may affect time zone resolution.
   • Fix: If geocoding fails, explicitly set the region:

     $phoneUtil->setRegionCodeForNumber($number, 'IN');
     

Debugging Tips

• Log Updated Metadata:

  $phoneUtil = PhoneNumberUtil::getInstance();
  \Log::debug('Supported regions:', array_keys($phoneUtil->getSupportedRegions()));
  \Log::debug('India metadata:', $phoneUtil->getMetadataForRegion('IN'));
  

• Validate Against New Test Cases: Use the updated test data for regions like CL, CZ, and SG from Google’s v9.0 tests.

• Handle Carrier Data Changes:

  $number = $phoneUtil->parse('+56912345678', 'CL');
  $type = $phoneUtil->getNumberType($number);
  \Log::debug('Carrier type:', $type->getName(), [
      'isMobile' => $type === PhoneNumberType::MOBILE,
      'isFixedLine' => $type === PhoneNumberType::FIXED_LINE,
  ]);
  

Extension Points

1. Custom Region Handling Override region-specific logic for edge cases (e.g., toll-free numbers in IN):

   $phoneUtil->setRegionCodeForNumber($number, 'IN');
   $phoneUtil->setMetadataProvider(new CustomMetadataProvider([
       'IN' => [
           'toll_free_prefixes' => ['1800', '18000'],
       ],
   ]));
   

2. Event-Driven Validation Extend validation with carrier/type checks:

   $validator = Validator::make($request->all(), [
       'phone' => ['required', function ($attribute, $value, $fail) {
           $phoneUtil = PhoneNumberUtil::getInstance();
           $number = $phoneUtil->parse($value);
           if (!$phoneUtil->isValidNumber($number)) {
               $fail('Invalid phone number.');
           }
           // Block toll-free numbers if needed
           if ($phoneUtil->getNumberType($number) === PhoneNumberType::TOLL_FREE) {
               $fail('Toll-free numbers are not allowed.');
           }
       }],
   ]);