Phone Number Info Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bytes4sale/phone-number-info
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Bytes4Sale\PhoneNumberInfo\PhoneNumberInfoServiceProvider"
   

2. Basic Usage Fetch carrier info for a phone number:

   use Bytes4Sale\PhoneNumberInfo\Facades\PhoneNumberInfo;
   
   $carrier = PhoneNumberInfo::getCarrier('+1234567890');
   dd($carrier);
   

3. First Use Case Validate a phone number and display its carrier:

   $number = '+1234567890';
   $info = PhoneNumberInfo::getInfo($number);
   
   if ($info->isValid()) {
       echo "Carrier: " . $info->carrier;
       echo "Country: " . $info->country;
   } else {
       echo "Invalid phone number";
   }
   

Implementation Patterns

Common Workflows

1. User Registration/Verification

   // Validate and store user phone with carrier info
   $phoneInfo = PhoneNumberInfo::getInfo(request('phone'));
   if ($phoneInfo->isValid()) {
       User::create([
           'phone' => request('phone'),
           'carrier' => $phoneInfo->carrier,
           'country' => $phoneInfo->country,
       ]);
   }
   

2. Fraud Detection

   // Check for high-risk carriers (e.g., prepaid/SIM-only)
   $carrier = PhoneNumberInfo::getCarrier($user->phone);
   if (str_contains(strtolower($carrier), ['prepaid', 'sim'])) {
       event(new SuspiciousPhoneDetected($user));
   }
   

3. Localization

   // Route users based on phone country
   $country = PhoneNumberInfo::getCountry($request->phone);
   return redirect()->route("localized.dashboard.$country");
   

Integration Tips

• Cache Responses

  $carrier = Cache::remember("phone_carrier_{$phone}", now()->addHours(1), function() use ($phone) {
      return PhoneNumberInfo::getCarrier($phone);
  });
  

• Queue Long-Running Requests

  PhoneNumberInfo::getHLRInfo($phone)->onQueue('hlr-queue');
  

• Laravel Nova/Forge Integration Add a custom field to Nova:

  public static function label()
  {
      return 'Carrier';
  }
  
  public function value(User $user)
  {
      return PhoneNumberInfo::getCarrier($user->phone) ?: 'Unknown';
  }
  

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • The package may throttle requests. Implement retries with exponential backoff:

     try {
         $info = PhoneNumberInfo::getInfo($phone);
     } catch (RateLimitExceededException $e) {
         sleep(2 ** $e->retryAfter);
         retry();
     }
     

2. Number Formatting

   • Ensure numbers are in E.164 format (+<country><number>). Normalize inputs:

     use libphonenumber\PhoneNumberUtil;
     $phone = PhoneNumberUtil::getInstance()->format($rawInput, PhoneNumberFormat::E164);
     

3. HLR Data Limitations

   • HLR (Home Location Register) data is not always accurate or available. Handle null responses gracefully:

     $hlr = PhoneNumberInfo::getHLRInfo($phone);
     if (!$hlr->isActive()) {
         // Fallback logic (e.g., SMS verification)
     }
     

Debugging

• Enable Logging Add to config/phone-number-info.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Mock Responses for Testing

  // In tests, stub the facade:
  PhoneNumberInfo::shouldReceive('getCarrier')
      ->once()
      ->andReturn('Test Carrier');
  

Extension Points

1. Custom Data Sources Override the default provider in config/phone-number-info.php:

   'provider' => Bytes4Sale\PhoneNumberInfo\Providers\CustomProvider::class,
   

2. Add Metadata Fields Extend the PhoneNumberInfo model:

   namespace App\Extensions;
   use Bytes4Sale\PhoneNumberInfo\Models\PhoneNumberInfo as BaseInfo;
   
   class ExtendedPhoneNumberInfo extends BaseInfo {
       public function getRiskScore(): float {
           // Custom logic
       }
   }
   

3. Webhook Integration Listen for carrier updates:

   PhoneNumberInfo::listen(function ($event) {
       // Handle real-time updates (e.g., number porting)
   });
   

Config Quirks

• API Keys Set your API key in .env:

  PHONE_NUMBER_INFO_API_KEY=your_key_here
  

  Or via config:

  'api_key' => env('PHONE_NUMBER_INFO_API_KEY'),
  

• Fallback Providers Define a chain of providers in config:

  'providers' => [
      Bytes4Sale\PhoneNumberInfo\Providers\PrimaryProvider::class,
      Bytes4Sale\PhoneNumberInfo\Providers\FallbackProvider::class,
  ],