Phone Number Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require misd/phone-number-bundle
   

2. Enable Bundle (Symfony 4+): Add to config/bundles.php:

   return [
       // ...
       Misd\PhoneNumberBundle\MisdPhoneNumberBundle::class => ['all' => true],
   ];
   

3. First Use Case: Validate and format a phone number in a controller:

   use Misd\PhoneNumberBundle\PhoneNumber\PhoneNumber;
   use Misd\PhoneNumberBundle\PhoneNumber\PhoneNumberUtil;
   
   public function validatePhone(Request $request)
   {
       $phoneUtil = new PhoneNumberUtil();
       $phoneNumber = $phoneUtil->parse('+14155552671', 'US');
   
       if (!$phoneUtil->isValidNumber($phoneNumber)) {
           return new Response('Invalid number');
       }
   
       $formatted = $phoneUtil->format($phoneNumber, PhoneNumber::E164);
       return new Response($formatted);
   }
   

Key Entry Points

• PhoneNumberUtil: Core class for parsing, validating, and formatting.
• PhoneNumber: Represents a parsed phone number object.
• Twig Extension: Access phone utilities via phone_number Twig filter.

Implementation Patterns

Common Workflows

1. Form Validation:

   use Symfony\Component\Validator\Constraints as Assert;
   use Misd\PhoneNumberBundle\Validator\Constraints\ValidPhoneNumber;
   
   $builder->add('phone', TextType::class, [
       'constraints' => [
           new Assert\NotBlank(),
           new ValidPhoneNumber(['countryCode' => 'US']),
       ],
   ]);
   

2. Internationalization:

   $phoneUtil = new PhoneNumberUtil();
   $number = $phoneUtil->parse('02079460000', 'GB');
   $formatted = $phoneUtil->format($number, PhoneNumber::NATIONAL);
   

3. Twig Integration:

   {{ user.phone|phone_number('international') }}
   

4. Geocoding:

   $regionCode = $phoneUtil->getRegionCodeForNumber($phoneNumber);
   $timeZones = $phoneUtil->getSupportedRegions();
   

Integration Tips

• Dependency Injection: Bind PhoneNumberUtil as a service in services.yaml:

  services:
      App\Service\PhoneService:
          arguments:
              $phoneUtil: '@misd_phone_number.phone_number_util'
  

• Event Listeners: Extend functionality (e.g., auto-format on save):

  public function onUserUpdate(UserEvent $event)
  {
      $phoneUtil = $this->phoneUtil;
      $number = $phoneUtil->parse($event->getUser()->getPhone());
      $event->getUser()->setPhone($phoneUtil->format($number, PhoneNumber::E164));
  }
  

Gotchas and Tips

Pitfalls

1. Performance:

   • Parsing/validating thousands of numbers in bulk? Cache PhoneNumberUtil:

     services:
         misd_phone_number.phone_number_util:
             synthetic: true
     

   • Avoid instantiating PhoneNumberUtil per request if possible.

2. Region Ambiguity:

   • Numbers like +44 (UK) or +1 (US/Canada) may require manual region specification:

     $phoneUtil->parse('441234567890', null); // Ambiguous; specify 'GB' or 'US'.
     

3. Deprecated Methods:

   • Prefer PhoneNumberUtil::parse() over PhoneNumberUtil::parseAndKeepRawInput() unless you need raw input preservation.

4. Symfony 5+:

   • If using Symfony 5+, ensure autowiring: true in config/services.yaml for seamless DI.

Debugging

• Invalid Numbers: Use PhoneNumberUtil::isValidNumber() and check PhoneNumberUtil::getErrorMessage():

  try {
      $phoneNumber = $phoneUtil->parse('invalid', 'US');
  } catch (\giggsey\LibPhonenumber\NumberParseException $e) {
      return new Response($e->getMessage());
  }
  

• Time Zone Issues: If geocoding fails, verify PhoneNumberUtil::getSupportedRegions() includes the expected country code.

Extension Points

1. Custom Validators: Extend ValidPhoneNumber constraint for business rules:

   class CustomValidPhoneNumber extends ValidPhoneNumber
   {
       protected function getOptions()
       {
           return array_merge(parent::getOptions(), ['allowShortNumbers' => false]);
       }
   }
   

2. Override Default Formatter: Create a custom formatter service:

   services:
       app.phone_formatter:
           class: App\Service\CustomPhoneFormatter
           arguments:
               $phoneUtil: '@misd_phone_number.phone_number_util'
   

3. Add New Regions: Dynamically load regions at runtime:

   $phoneUtil->setRegionCodeForNumberOverride('+1', 'CA'); // Override US default.
   

Configuration Quirks

• Default Country: Set a default country in config/packages/misd_phone_number.yaml:

  misd_phone_number:
      default_country: 'US'
  

  This affects validation when no region is specified.

• Strict Mode: Enable strict parsing (throws exceptions for invalid numbers):

  misd_phone_number:
      strict: true