Libphonenumber For Php Lite Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require giggsey/libphonenumber-for-php-lite
   

   Ensure your composer.json includes "require": {"php": "^8.1"} and the mbstring extension is enabled.

2. First Use Case: Parse and validate a phone number in a Laravel controller or service:

   use libphonenumber\PhoneNumberUtil;
   
   $phoneUtil = PhoneNumberUtil::getInstance();
   $number = $phoneUtil->parse('+14155552671', 'US');
   $isValid = $phoneUtil->isValidNumber($number);
   

3. Where to Look First:

   • PhoneNumberUtil Documentation
   • Quick Examples in the README.

Implementation Patterns

Core Workflows

1. Parsing and Validation

• Use Case: Validate user-submitted phone numbers (e.g., registration forms).
• Pattern:

  public function validatePhoneNumber(string $phone, string $regionCode): bool
  {
      $phoneUtil = PhoneNumberUtil::getInstance();
      try {
          $number = $phoneUtil->parse($phone, $regionCode);
          return $phoneUtil->isValidNumber($number);
      } catch (NumberParseException $e) {
          return false;
      }
  }
  

• Laravel Integration: Use in a FormRequest validator or a custom validation rule.

2. Formatting for Display

• Use Case: Display phone numbers in a user-friendly format (e.g., +1 (415) 555-2671).
• Pattern:

  public function formatPhoneNumber(PhoneNumberInterface $number, string $format = PhoneNumberFormat::NATIONAL): string
  {
      $phoneUtil = PhoneNumberUtil::getInstance();
      return $phoneUtil->format($number, $format);
  }
  

• Laravel Blade:

  {{ formatPhoneNumber($user->phoneNumber) }}
  

3. Normalization

• Use Case: Store phone numbers in a consistent format (e.g., E.164) in the database.
• Pattern:

  public function normalizePhoneNumber(string $phone, string $regionCode): string
  {
      $phoneUtil = PhoneNumberUtil::getInstance();
      $number = $phoneUtil->parse($phone, $regionCode);
      return $phoneUtil->format($number, PhoneNumberFormat::E164);
  }
  

• Database Migration:

  $table->string('phone_number')->comment('Stored in E.164 format');
  

4. Number Type Detection

• Use Case: Classify phone numbers (e.g., mobile vs. landline) for business logic.
• Pattern:

  public function getNumberType(PhoneNumberInterface $number): string
  {
      $phoneUtil = PhoneNumberUtil::getInstance();
      return $phoneUtil->getNumberType($number);
  }
  

• Example Usage:

  if ($phoneUtil->getNumberType($number) === PhoneNumberType::MOBILE) {
      // Apply mobile-specific logic
  }
  

5. International Dialing

• Use Case: Format numbers for dialing from another country (e.g., calling Switzerland from the US).
• Pattern:

  public function formatForInternationalDialing(PhoneNumberInterface $number, string $callingCountryCode): string
  {
      $phoneUtil = PhoneNumberUtil::getInstance();
      return $phoneUtil->formatOutOfCountryCallingNumber($number, $callingCountryCode);
  }
  

Integration Tips

Laravel Service Provider

Register the PhoneNumberUtil instance as a singleton in AppServiceProvider:

public function register()
{
    $this->app->singleton(PhoneNumberUtil::class, function () {
        return PhoneNumberUtil::getInstance();
    });
}

Custom Validation Rule

Create a reusable validation rule:

namespace App\Rules;

use libphonenumber\PhoneNumberUtil;
use libphonenumber\PhoneNumberFormat;
use libphonenumber\NumberParseException;

class ValidPhoneNumber implements Rule
{
    protected $regionCode;

    public function __construct(string $regionCode)
    {
        $this->regionCode = $regionCode;
    }

    public function passes($attribute, $value)
    {
        $phoneUtil = PhoneNumberUtil::getInstance();
        try {
            $number = $phoneUtil->parse($value, $this->regionCode);
            return $phoneUtil->isValidNumber($number);
        } catch (NumberParseException) {
            return false;
        }
    }

    public function message()
    {
        return 'The :attribute is invalid.';
    }
}

Usage:

'phone' => ['required', new ValidPhoneNumber('US')],

Eloquent Accessors/Mutators

Add phone number formatting to Eloquent models:

public function getPhoneNumberAttribute($value)
{
    if (empty($value)) return $value;

    $phoneUtil = app(PhoneNumberUtil::class);
    $number = $phoneUtil->parse($value, 'US');
    return $phoneUtil->format($number, PhoneNumberFormat::NATIONAL);
}

public function setPhoneNumberAttribute($value)
{
    $phoneUtil = app(PhoneNumberUtil::class);
    $this->attributes['phone_number'] = $phoneUtil->format(
        $phoneUtil->parse($value, 'US'),
        PhoneNumberFormat::E164
    );
}

Gotchas and Tips

Pitfalls

1. Region Code Ambiguity:

   • Issue: Parsing a number without a region code (e.g., parse("123")) may fail or return unexpected results.
   • Fix: Always specify a region code (e.g., parse("123", "US")).
   • Workaround: Use parse("123", null) and handle NumberParseException to infer the region.

2. Invalid Metadata:

   • Issue: If metadata for a region is missing or outdated, parsing/formatting may fail.
   • Fix: Check the release notes for recent updates. Update the package if needed:

     composer update giggsey/libphonenumber-for-php-lite
     

3. Performance with Large Datasets:

   • Issue: Parsing thousands of numbers sequentially can be slow.
   • Fix: Cache the PhoneNumberUtil instance (already handled by the singleton pattern) and avoid redundant parsing.

4. Edge Cases in Validation:

   • Issue: Some numbers may pass validation but are technically invalid (e.g., short codes, voicemail boxes).
   • Fix: Use getNumberType() to filter out unwanted types:

     $type = $phoneUtil->getNumberType($number);
     if ($type === PhoneNumberType::VOICEMAIL) {
         return false;
     }
     

5. Time Zone Dependencies:

   • Issue: Some number types (e.g., mobile) may vary by region or carrier.
   • Fix: Always validate against the correct region code.

Debugging Tips

1. Logging Parsing Errors:

   • Wrap parsing in a try-catch to log invalid numbers:

     try {
         $number = $phoneUtil->parse($phone, $region);
     } catch (NumberParseException $e) {
         Log::warning("Invalid phone number: {$phone} (Region: {$region})", ['error' => $e->getMessage()]);
     }
     

2. Testing with Examples:

   • Use getExampleNumber() to test edge cases:

     $example = $phoneUtil->getExampleNumber('US');
     $exampleMobile = $phoneUtil->getExampleNumberByType('US', PhoneNumberType::MOBILE);
     

3. Comparing Numbers:

   • Use isNumberMatch() to check if two numbers might refer to the same entity:

     $match = $phoneUtil->isNumberMatch($number1, $number2);
     if ($match === PhoneNumberMatch::POSSIBLE) {
         // Numbers might be the same
     }
     

Extension Points

1. Custom Formatting Patterns:

   • Override formatting for specific regions by extending the library (advanced):

     class CustomPhoneNumberUtil extends PhoneNumberUtil
     {
         protected function chooseFormattingPatternForNumber($regionCode, $number)
         {
             if ($regionCode === 'US') {
                 return '!N<1>XXXXXXX!'; // Custom pattern
             }
             return parent::chooseFormattingPatternForNumber($regionCode, $number);
         }
     }
     

2. Database Storage: