feat: integrate libphonenumber for phone number and carrier detection

Replace hardcoded prefix logic with libphonenumber-for-php library for
detecting countries and carriers from phone numbers. Add CarrierMapper
service to map carrier names to FedaPay payment mode codes.

- Add giggsey/libphonenumber-for-php dependency
- Create CarrierMapper with carrier-to-FedaPay mode mapping
- Refactor PhoneNumberService to use libphonenumber
- Update MobileMoneyDetector with hybrid detection (prefix for Togo, libphonenumber for others)
- Add Celtiis (sbin) support for Benin
- Register phone services as singletons in BillingServiceProvider

Author: Just Chris

composer.json

@@ -28,10 +28,11 @@
     ],
     "require": {
         "php": "^8.4",
-        "spatie/laravel-package-tools": "^1.16",
-        "illuminate/contracts": "^11.0||^12.0",
         "fedapay/fedapay-php": "^0.4",
-        "laravel/prompts": "^0.3"
+        "giggsey/libphonenumber-for-php": "^9.0",
+        "illuminate/contracts": "^11.0||^12.0",
+        "laravel/prompts": "^0.3",
+        "spatie/laravel-package-tools": "^1.16"
     },
     "require-dev": {
         "larastan/larastan": "^3.0",

peck.json

@@ -13,7 +13,9 @@
             "jour",
             "mois",
             "unpause",
-            "transactionable"
+            "transactionable",
+            "libphonenumber",
+            "util"
         ],
         "paths": []
     }

src/BillingServiceProvider.php

@@ -4,12 +4,16 @@
 
 namespace Ratoufa\Billing;
 
+use libphonenumber\PhoneNumberToCarrierMapper;
+use libphonenumber\PhoneNumberUtil;
 use Ratoufa\Billing\Commands\InstallCommand;
 use Ratoufa\Billing\Commands\ProcessRecurringPaymentsCommand;
 use Ratoufa\Billing\Commands\ProcessScheduledPayoutsCommand;
+use Ratoufa\Billing\Services\CarrierMapper;
 use Ratoufa\Billing\Services\CommissionCalculator;
 use Ratoufa\Billing\Services\CommissionService;
 use Ratoufa\Billing\Services\InstantPayoutService;
+use Ratoufa\Billing\Services\PhoneNumberService;
 use Spatie\LaravelPackageTools\Package;
 use Spatie\LaravelPackageTools\PackageServiceProvider;
 
@@ -32,9 +36,27 @@ public function packageRegistered(): void
 
         $this->app->alias(BillingManager::class, 'billing');
 
+        $this->registerPhoneServices();
         $this->registerMarketplaceServices();
     }
 
+    private function registerPhoneServices(): void
+    {
+        $this->app->singleton(PhoneNumberUtil::class, fn (): PhoneNumberUtil => PhoneNumberUtil::getInstance());
+
+        $this->app->singleton(
+            PhoneNumberToCarrierMapper::class,
+            fn (): PhoneNumberToCarrierMapper => PhoneNumberToCarrierMapper::getInstance()
+        );
+
+        $this->app->singleton(CarrierMapper::class);
+
+        $this->app->singleton(PhoneNumberService::class, fn ($app): PhoneNumberService => new PhoneNumberService(
+            $app->make(PhoneNumberUtil::class),
+            $app->make(PhoneNumberToCarrierMapper::class),
+        ));
+    }
+
     private function registerMarketplaceServices(): void
     {
         $this->app->singleton(CommissionCalculator::class);

src/Models/Subscription.php

@@ -127,6 +127,7 @@ public function valid(): bool
         if ($this->active()) {
             return true;
         }
+
         if ($this->onTrial()) {
             return true;
         }

src/Providers/FedaPay/FedaPayProvider.php

@@ -35,8 +35,8 @@ public function __construct(array $config)
     {
         parent::__construct($config);
 
-        $this->mobileMoneyDetector = new MobileMoneyDetector;
-        $this->phoneFormatter = new PhoneNumberFormatter;
+        $this->mobileMoneyDetector = MobileMoneyDetector::create();
+        $this->phoneFormatter = PhoneNumberFormatter::create();
     }
 
     public function name(): string

src/Providers/FedaPay/MobileMoneyDetector.php

@@ -4,20 +4,27 @@
 
 namespace Ratoufa\Billing\Providers\FedaPay;
 
+use Ratoufa\Billing\Services\CarrierMapper;
+use Ratoufa\Billing\Services\PhoneNumberService;
+
 /**
  * Detects mobile money provider from phone number.
+ *
+ * Uses libphonenumber for carrier detection with fallback to prefix-based detection.
  */
-final class MobileMoneyDetector
+final readonly class MobileMoneyDetector
 {
     /**
      * Mobile money modes supported for USSD Push payments.
+     * Used as fallback when libphonenumber cannot detect the carrier.
      *
      * @var array<string, array{country: string, name: string, prefixes: array<int, string>}>
      */
     public const array MODES = [
         // Benin
         'mtn_open' => ['country' => 'bj', 'name' => 'MTN Mobile Money', 'prefixes' => ['229']],
         'moov' => ['country' => 'bj', 'name' => 'Moov Money', 'prefixes' => ['229']],
+        'sbin' => ['country' => 'bj', 'name' => 'Celtiis', 'prefixes' => ['229']],
 
         // Togo
         'moov_tg' => ['country' => 'tg', 'name' => 'Moov Money Togo', 'prefixes' => ['22896', '22897', '22898', '22899']],
@@ -36,28 +43,45 @@ final class MobileMoneyDetector
         'mtn_open_gn' => ['country' => 'gn', 'name' => 'MTN Guinée', 'prefixes' => ['224']],
     ];
 
+    public function __construct(
+        private PhoneNumberService $phoneService,
+        private CarrierMapper $carrierMapper,
+    ) {}
+
+    /**
+     * Create a new instance with default dependencies.
+     */
+    public static function create(): self
+    {
+        return new self(
+            PhoneNumberService::create(),
+            new CarrierMapper(),
+        );
+    }
+
     /**
      * Detect the mobile money mode from a phone number.
      */
     public function detect(string $phoneNumber): ?string
     {
-        $phone = $this->normalizePhone($phoneNumber);
-
-        // Check against known prefixes
-        foreach (self::MODES as $mode => $config) {
-            foreach ($config['prefixes'] as $prefix) {
-                if (str_starts_with($phone, $prefix)) {
-                    return $mode;
-                }
+        // For Togo numbers, use prefix-based detection first (more accurate)
+        $country = $this->phoneService->detectCountry($phoneNumber);
+        if (mb_strtolower($country) === 'tg') {
+            $mode = $this->detectWithPrefixes($phoneNumber);
+            if ($mode !== null) {
+                return $mode;
             }
         }
 
-        // Special detection for Togo (228)
-        if (str_starts_with($phone, '228')) {
-            return $this->detectTogoProvider($phone);
+        // Try libphonenumber
+        $mode = $this->detectWithLibphonenumber($phoneNumber);
+
+        // Fallback to prefix-based detection for other countries
+        if ($mode === null) {
+            return $this->detectWithPrefixes($phoneNumber);
         }
 
-        return null;
+        return $mode;
     }
 
     /**
@@ -75,12 +99,13 @@ public function supportsDirectPayment(string $phoneNumber): bool
      */
     public function getAvailableModes(?string $country = null): array
     {
-        $modes = [];
+        if ($country !== null) {
+            return $this->carrierMapper->getModesForCountry($country);
+        }
 
+        $modes = [];
         foreach (self::MODES as $mode => $config) {
-            if ($country === null || $config['country'] === mb_strtolower($country)) {
-                $modes[$mode] = $config['name'];
-            }
+            $modes[$mode] = $config['name'];
         }
 
         return $modes;
@@ -101,17 +126,66 @@ public function getTogoModes(): array
      */
     public function getModeName(string $mode): ?string
     {
-        return self::MODES[$mode]['name'] ?? null;
+        return $this->carrierMapper->getModeName($mode) ?? self::MODES[$mode]['name'] ?? null;
     }
 
     /**
      * Validate if a mode is supported.
      */
     public function isValidMode(string $mode): bool
     {
+        if ($this->carrierMapper->isValidMode($mode)) {
+            return true;
+        }
+
         return isset(self::MODES[$mode]);
     }
 
+    /**
+     * Detect using libphonenumber carrier detection.
+     */
+    private function detectWithLibphonenumber(string $phoneNumber): ?string
+    {
+        $carrier = $this->phoneService->detectCarrier($phoneNumber);
+
+        if ($carrier === null) {
+            return null;
+        }
+
+        $country = $this->phoneService->detectCountry($phoneNumber);
+
+        return $this->carrierMapper->getFedaPayMode($carrier, $country);
+    }
+
+    /**
+     * Detect using prefix-based matching (fallback).
+     */
+    private function detectWithPrefixes(string $phoneNumber): ?string
+    {
+        $phone = $this->normalizePhone($phoneNumber);
+
+        // Check against known prefixes
+        foreach (self::MODES as $mode => $config) {
+            foreach ($config['prefixes'] as $prefix) {
+                if (str_starts_with($phone, $prefix)) {
+                    // For countries with multiple operators, use specific logic
+                    if ($config['country'] === 'tg') {
+                        return $this->detectTogoProvider($phone);
+                    }
+
+                    return $mode;
+                }
+            }
+        }
+
+        // Special detection for Togo (228)
+        if (str_starts_with($phone, '228')) {
+            return $this->detectTogoProvider($phone);
+        }
+
+        return null;
+    }
+
     /**
      * Detect Togo-specific provider from phone number.
      */

src/Providers/FedaPay/PhoneNumberFormatter.php

@@ -4,26 +4,26 @@
 
 namespace Ratoufa\Billing\Providers\FedaPay;
 
+use Ratoufa\Billing\Services\PhoneNumberService;
+
 /**
  * Formats phone numbers for FedaPay API.
+ *
+ * Wrapper around PhoneNumberService for FedaPay-specific formatting.
  */
-final class PhoneNumberFormatter
+final readonly class PhoneNumberFormatter
 {
+    public function __construct(
+        private PhoneNumberService $phoneService,
+    ) {}
+
     /**
-     * Country code mappings.
-     *
-     * @var array<int|string, string>
+     * Create a new instance with default dependencies.
      */
-    private const array COUNTRY_CODES = [
-        229 => 'bj', // Benin
-        226 => 'bf', // Burkina Faso
-        225 => 'ci', // Côte d'Ivoire
-        223 => 'ml', // Mali
-        227 => 'ne', // Niger
-        221 => 'sn', // Senegal
-        228 => 'tg', // Togo
-        224 => 'gn', // Guinea
-    ];
+    public static function create(): self
+    {
+        return new self(PhoneNumberService::create());
+    }
 
     /**
      * Format a phone number for FedaPay API.
@@ -32,57 +32,32 @@ final class PhoneNumberFormatter
      */
     public function format(?string $phone): ?array
     {
-        if ($phone === null || $phone === '') {
-            return null;
-        }
-
-        $phone = $this->normalize($phone);
-        $country = $this->detectCountry($phone);
-
-        return [
-            'number' => $this->ensurePrefix($phone),
-            'country' => $country,
-        ];
+        return $this->phoneService->format($phone);
     }
 
     /**
      * Normalize a phone number.
      */
     public function normalize(string $phone): string
     {
-        $normalized = preg_replace('/[^0-9+]/', '', $phone);
-
-        return $normalized ?? '';
+        return $this->phoneService->normalize($phone);
     }
 
     /**
      * Detect country from phone number.
      */
     public function detectCountry(string $phone, string $default = 'tg'): string
     {
-        $phone = $this->normalize($phone);
-        $phone = mb_ltrim($phone, '+');
-
-        foreach (self::COUNTRY_CODES as $code => $country) {
-            if (str_starts_with($phone, (string) $code)) {
-                return $country;
-            }
-        }
+        $this->phoneService->setDefaultCountry($default);
 
-        return $default;
+        return $this->phoneService->detectCountry($phone);
     }
 
     /**
      * Ensure phone number has + prefix.
      */
     public function ensurePrefix(string $phone): string
     {
-        $phone = $this->normalize($phone);
-
-        if (! str_starts_with($phone, '+')) {
-            return '+'.$phone;
-        }
-
-        return $phone;
+        return $this->phoneService->ensurePrefix($phone);
     }
 }