Libphonenumber For Php Lite Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require giggsey/libphonenumber-for-php-lite
   

   Ensure mbstring extension is enabled in your PHP configuration.

2. First Use Case: Parse and validate a phone number:

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

3. Where to Look First:

   • PhoneNumberUtil Documentation for core functionality.
   • Quick Examples for common use cases.

Implementation Patterns

Core Workflows

1. Parsing and Validation:

   $phoneUtil = PhoneNumberUtil::getInstance();
   $number = $phoneUtil->parse($rawPhoneNumber, $regionCode);
   $isValid = $phoneUtil->isValidNumber($number);
   

2. Formatting:

   // E164 format (e.g., +442071838750)
   $e164 = $phoneUtil->format($number, PhoneNumberFormat::E164);
   
   // National format (e.g., 020 7183 8750 for GB)
   $national = $phoneUtil->format($number, PhoneNumberFormat::NATIONAL);
   
   // International format (e.g., +44 20 7183 8750)
   $international = $phoneUtil->format($number, PhoneNumberFormat::INTERNATIONAL);
   

3. Number Type Detection:

   $numberType = $phoneUtil->getNumberType($number);
   // Returns constants like PhoneNumberType::MOBILE, PhoneNumberType::FIXED_LINE, etc.
   

4. Number Matching:

   $isMatch = $phoneUtil->isNumberMatch($number1, $number2);
   // Returns a confidence level (0-4) indicating if the numbers could be the same.
   

5. Example Numbers:

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

Integration Tips

• Laravel Request Validation: Use the package in Laravel form requests or validation rules:

  use libphonenumber\PhoneNumberUtil;
  
  $validator = Validator::make($request->all(), [
      'phone' => function ($attribute, $value, $fail) {
          $phoneUtil = PhoneNumberUtil::getInstance();
          try {
              $number = $phoneUtil->parse($value);
              if (!$phoneUtil->isValidNumber($number)) {
                  $fail('The phone number is invalid.');
              }
          } catch (\libphonenumber\NumberParseException $e) {
              $fail('The phone number is invalid.');
          }
      },
  ]);
  

• Service Layer: Create a dedicated service class for phone number operations:

  namespace App\Services;
  
  use libphonenumber\PhoneNumberUtil;
  use libphonenumber\PhoneNumberFormat;
  
  class PhoneNumberService
  {
      protected $phoneUtil;
  
      public function __construct()
      {
          $this->phoneUtil = PhoneNumberUtil::getInstance();
      }
  
      public function formatE164($phoneNumber, $regionCode)
      {
          $number = $this->phoneUtil->parse($phoneNumber, $regionCode);
          return $this->phoneUtil->format($number, PhoneNumberFormat::E164);
      }
  
      // Add other methods as needed...
  }
  

• Model Observers/Accessors: Add phone number parsing/validation to Eloquent models:

  use libphonenumber\PhoneNumberUtil;
  
  class User extends Model
  {
      protected static function boot()
      {
          parent::boot();
  
          static::saving(function ($user) {
              $phoneUtil = PhoneNumberUtil::getInstance();
              try {
                  $number = $phoneUtil->parse($user->phone);
                  $user->phone_e164 = $phoneUtil->format($number, PhoneNumberFormat::E164);
              } catch (\libphonenumber\NumberParseException $e) {
                  // Handle exception
              }
          });
      }
  }
  

Gotchas and Tips

Pitfalls

1. Region Code Sensitivity:

   • Always specify a region code when parsing numbers. Without it, the library may not correctly interpret the number.
   • Example: Parsing 02071838750 without a region code might fail, but with GB it works.

2. Exception Handling:

   • Always wrap parsing in a try-catch block to handle NumberParseException:

     try {
         $number = $phoneUtil->parse($rawNumber, $regionCode);
     } catch (\libphonenumber\NumberParseException $e) {
         // Handle invalid numbers gracefully
     }
     

3. Number Type Limitations:

   • Not all numbers can be accurately classified (e.g., VoIP numbers may not always be detected correctly).
   • Use getNumberType() results cautiously in business logic.

4. Short Number Limitations:

   • Short number validation (isValidShortNumber) only checks patterns, not actual usage. False positives are possible.

5. Performance:

   • The library loads metadata on first use, which can be slow. Cache the PhoneNumberUtil instance if initializing frequently:

     $phoneUtil = PhoneNumberUtil::getInstance(); // Expensive first call
     

Debugging Tips

1. Check Raw Input: Use $phoneUtil->getNumberType($number) and $phoneUtil->getRegionCodeForNumber($number) to debug parsing issues.

2. Validate with Online Tools: Cross-check results with Google's libphonenumber demo if unsure about correctness.

3. Log Parsed Numbers: Log the parsed PhoneNumber object to inspect its properties (e.g., countryCode, nationalNumber):

   $number = $phoneUtil->parse($rawNumber, $regionCode);
   \Log::debug([
       'countryCode' => $number->getCountryCode(),
       'nationalNumber' => $number->getNationalNumber(),
       'extension' => $number->getExtension(),
   ]);
   

Extension Points

1. Custom Formatting: Extend the library by creating custom formatters:

   class CustomPhoneNumberFormatter
   {
       public static function formatCustom($phoneNumber)
       {
           $phoneUtil = PhoneNumberUtil::getInstance();
           $e164 = $phoneUtil->format($phoneNumber, PhoneNumberFormat::E164);
           // Add custom logic (e.g., append a suffix)
           return $e164 . '-CUSTOM';
       }
   }
   

2. Region-Specific Logic: Use the PhoneNumberUtil to implement region-specific business rules:

   $regionCode = $phoneUtil->getRegionCodeForNumber($number);
   if ($regionCode === 'US') {
       // Apply US-specific logic
   }
   

3. Carrier Mapping (if needed): Although this is the "lite" version, you can still use the PhoneNumberToCarrierMapper for carrier names:

   $carrierMapper = \libphonenumber\PhoneNumberToCarrierMapper::getInstance();
   $carrierName = $carrierMapper->getNameForNumber($number, 'en');
   

Configuration Quirks

1. Metadata Updates:

   • The library uses pre-compiled metadata. Updates require a new release. If you need the latest metadata, consider using the full libphonenumber-for-php package.

2. Language Support:

   • Carrier names are language-dependent. Always specify the language (e.g., 'en') when using getNameForNumber().

3. Short Number Costs:

   • Not all regions support short number cost detection. Use ShortNumberCost::UNKNOWN_COST as a fallback.