Normalize customer phone number

src/backend/app/Http/Requests/CreateAddressRequest.php

@@ -22,6 +22,7 @@ public function authorize(): bool {
     public function rules(): array {
         return [
             'city_id' => ['required'],
+            'phone' => ['phone:INTERNATIONAL'],
         ];
     }
 }

src/backend/app/Models/Address/Address.php

@@ -12,6 +12,7 @@
 use Illuminate\Database\Eloquent\Relations\MorphOne;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 use Illuminate\Support\Carbon;
+use Propaganistas\LaravelPhone\Casts\E164PhoneNumberCast;
 
 /**
  * Class Address.
@@ -42,6 +43,8 @@ class Address extends BaseModel {
         'city_id' => 'required|exists:cities,id',
     ];
 
+    public $casts = ['phone' => E164PhoneNumberCast::class];
+
     /**
      * @return BelongsTo<City, $this>
      */

src/backend/app/Services/AddressesService.php

@@ -107,8 +107,7 @@ public function save($address): bool {
 
     public function getAddressByPhoneNumber(string $phoneNumber): ?Address {
         return $this->address->newQuery()
-            ->where('phone', $phoneNumber)
-            ->orWhere('phone', ltrim($phoneNumber, '+'))
+            ->where('phone', phone($phoneNumber)->formatE164())
             ->first();
     }
 }

src/backend/app/Services/PersonService.php

@@ -397,6 +397,8 @@ public function createFromRequest(Request $request): Person {
     }
 
     public function getByPhoneNumber(string $phoneNumber): ?Person {
+        $phoneNumber = phone($phoneNumber)->formatE164();
+
         return $this->person->newQuery()->whereHas('addresses', fn ($q) => $q->where('phone', $phoneNumber))
             ->first();
     }

src/backend/app/Sms/Senders/SmsSender.php

@@ -28,11 +28,8 @@ public function sendSms(): void {
 
         $lastRecordedSMS = Sms::query()
             ->where('receiver', $this->receiver)
-            ->orWhere('receiver', ltrim($this->receiver, '+'))
-            ->where(
-                'body',
-                $this->body
-            )->latest()->first();
+            ->where('body', $this->body)
+            ->latest()->first();
 
         if ($lastRecordedSMS == null) {
             throw new SmsRecordNotFoundException('No record of the SMS to be sent to the receiver '.$this->receiver.' was found');
@@ -131,14 +128,13 @@ public function validateReferences(): void {
 
     public function getReceiver(): string {
         if ($this->data instanceof Transaction) {
-            $this->receiver = str_starts_with($this->data->sender, '+') ? $this->data->sender : '+'.$this->data->sender;
+            $this->receiver = phone($this->data->sender)->formatE164();
         } elseif ($this->data instanceof ApplianceRate) {
-            $this->receiver = str_starts_with($this->data->appliancePerson->person->addresses->first()->phone, '+') ? $this->data->appliancePerson->person->addresses->first()->phone
-                : '+'.$this->data->appliancePerson->person->addresses->first()->phone;
+            $this->receiver = $this->data->appliancePerson->person->addresses->first()->phone;
         } elseif (!is_array($this->data) && $this->data->mpmPerson) {
-            $this->receiver = str_starts_with($this->data->mpmPerson->addresses[0]->phone, '+') ? $this->data->mpmPerson->addresses[0]->phone : '+'.$this->data->mpmPerson->addresses[0]->phone;
+            $this->receiver = $this->data->mpmPerson->addresses[0]->phone;
         } else {
-            $this->receiver = str_starts_with($this->data['phone'], '+') ? $this->data['phone'] : '+'.$this->data['phone'];
+            $this->receiver = phone($this->data['phone'])->formatE164();
         }
 
         return $this->receiver;

src/backend/composer.json

@@ -28,6 +28,7 @@
     "parsecsv/php-parsecsv": "^1.3",
     "phpoffice/phpspreadsheet": "^1.7",
     "predis/predis": "^1.1.7",
+    "propaganistas/laravel-phone": "^6.0",
     "pusher/pusher-php-server": "^7.0",
     "spatie/geocoder": "^3.14",
     "spatie/laravel-backup": "^9.0",

src/backend/database/factories/CompanyFactory.php

@@ -18,7 +18,7 @@ class CompanyFactory extends Factory {
     public function definition(): array {
         return [
             'name' => $this->faker->company,
-            'phone' => $this->faker->phoneNumber,
+            'phone' => $this->faker->e164PhoneNumber(),
             'address' => $this->faker->address,
             'email' => $this->faker->email,
             'country_id' => 1,

src/backend/database/factories/PaymentHistoryFactory.php

@@ -20,7 +20,7 @@ public function definition(): array {
             'transaction_id' => 1,
             'amount' => $this->faker->randomFloat(2, 0, 100),
             'payment_service' => 'agent_transaction',
-            'sender' => $this->faker->phoneNumber,
+            'sender' => $this->faker->e164PhoneNumber(),
             'payment_type' => $this->faker->randomElement(['appliance', 'energy', 'installment', 'access rate']),
             'paid_for_type' => $this->faker->randomElement(['appliance', 'token', 'loan_rate', 'access_rate']),
             'paid_for_id' => 1,

src/backend/database/factories/Ticket/TicketUserFactory.php

@@ -17,7 +17,7 @@ class TicketUserFactory extends Factory {
     public function definition(): array {
         return [
             'user_name' => $this->faker->name,
-            'phone' => $this->faker->phoneNumber(),
+            'phone' => $this->faker->e164PhoneNumber(),
             'user_id' => 0,
             'out_source' => 0,
         ];

src/backend/database/factories/TransactionFactory.php

@@ -13,7 +13,7 @@ public function definition(): array {
         return [
             'id' => $this->faker->unique()->randomNumber(),
             'amount' => $this->faker->unique()->randomNumber(),
-            'sender' => $this->faker->phoneNumber,
+            'sender' => $this->faker->e164PhoneNumber(),
             'message' => '47000268748',
         ];
     }

src/backend/database/migrations/tenant/2026_03_12_000000_normalize_phone_numbers_in_addresses.php

@@ -0,0 +1,26 @@
+<?php
+
+use App\Models\Address\Address;
+use Illuminate\Database\Migrations\Migration;
+
+return new class extends Migration {
+    public function up(): void {
+        Address::query()
+            ->whereNotNull('phone')
+            ->where('phone', '!=', '')
+            ->chunkById(500, function ($addresses): void {
+                foreach ($addresses as $address) {
+                    $normalized = phone($address->getRawOriginal('phone'))->formatE164();
+
+                    if ($normalized !== $address->getRawOriginal('phone')) {
+                        $address->phone = $normalized;
+                        $address->save();
+                    }
+                }
+            });
+    }
+
+    public function down(): void {
+        // Normalization is not reversible
+    }
+};

src/backend/tests/CreateEnvironments.php

@@ -205,7 +205,7 @@ protected function createMeterWithTransaction() {
         $this->transaction = TransactionFactory::new()->create([
             'id' => 1,
             'amount' => $this->faker->unique()->randomNumber(),
-            'sender' => $this->faker->phoneNumber,
+            'sender' => $this->faker->e164PhoneNumber(),
             'message' => $meter->serial_number,
             'original_transaction_id' => $this->faker->unique()->randomNumber(),
             'original_transaction_type' => 'agent_transaction',
@@ -218,7 +218,7 @@ protected function createMeterWithTransaction() {
             'transaction_id' => $this->transaction->id,
             'amount' => $this->transaction->amount,
             'payment_service' => 'agent_transaction',
-            'sender' => $this->faker->phoneNumber,
+            'sender' => $this->faker->e164PhoneNumber(),
             'payment_type' => 'energy',
             'paid_for_type' => 'token',
             'paid_for_id' => $this->token->id,
@@ -252,7 +252,7 @@ protected function createMeterManufacturer($manufacturerCount = 1): void {
             $manufacturer = ManufacturerFactory::new()->create();
             $address = Address::query()->make([
                 'email' => $this->faker->email,
-                'phone' => $this->faker->phoneNumber,
+                'phone' => $this->faker->e164PhoneNumber(),
                 'street' => $this->faker->streetAddress,
                 'city_id' => 1,
             ]);
@@ -402,7 +402,7 @@ protected function createPerson($personCount = 1, $isCustomer = 1) {
             $this->people[] = $person;
             $address = Address::query()->make([
                 'email' => $this->faker->email,
-                'phone' => $this->faker->phoneNumber,
+                'phone' => $this->faker->e164PhoneNumber(),
                 'street' => '',
                 'city_id' => collect($this->cities)->random()['id'],
                 'is_primary' => 1,
@@ -561,7 +561,7 @@ protected function createAgentTransaction($agentTransactionCount = 1, $amount =
 
             $transaction = TransactionFactory::new()->make([
                 'amount' => $amount,
-                'sender' => $this->faker->phoneNumber,
+                'sender' => $this->faker->e164PhoneNumber(),
                 'message' => $meter->serial_number,
             ]);
 
@@ -635,7 +635,7 @@ protected function createPaymentHistory($paymentHistoryCount = 1, $amount = 100,
                 'transaction_id' => $this->faker->numberBetween(1, 100),
                 'amount' => $this->faker->randomFloat(2, 0, 100),
                 'payment_service' => 'agent_transaction',
-                'sender' => $this->faker->phoneNumber,
+                'sender' => $this->faker->e164PhoneNumber(),
                 'payment_type' => $this->faker->randomElement(['appliance', 'energy', 'installment', 'access rate']),
             ]);
 
@@ -706,7 +706,7 @@ protected function createTicketUser($ticketUserCount = 1, $userId = 1) {
         while ($ticketUserCount > 0) {
             $ticketUser = TicketUserFactory::new()->create([
                 'user_name' => $this->faker->unique()->name,
-                'phone' => $this->faker->phoneNumber(),
+                'phone' => $this->faker->e164PhoneNumber(),
                 'out_source' => 0,
                 'user_id' => $userId,
             ]);