feat: E.164 phone validation and storage with libphonenumber

- Add giggsey/libphonenumber-for-php, PhoneNumberNormalizer, ValidPhoneNumber rule

- Store subscribers as E.164; mutator normalizes on save; optional phone required from form block

- Migration to normalize legacy subscriber phones; Mailwizz/search/UI/tests updated

- Add run-deploy-from-local.sh and PREREGISTER_DEFAULT_PHONE_REGION in .env.example

Made-with: Cursor

app/Http/Controllers/Admin/SubscriberController.php

@@ -95,7 +95,7 @@ class SubscriberController extends Controller
             foreach ($subscribers as $sub) {
                 $row = [$sub->first_name, $sub->last_name, $sub->email];
                 if ($phoneEnabled) {
-                    $row[] = $sub->phone ?? '';
+                    $row[] = $sub->phoneDisplay() ?? '';
                 }
                 $row[] = $sub->created_at?->toDateTimeString() ?? '';
                 $row[] = $sub->synced_to_mailwizz ? 'Yes' : 'No';

app/Http/Requests/SubscribePublicPageRequest.php

@@ -5,7 +5,10 @@ declare(strict_types=1);
 namespace App\Http\Requests;
 
 use App\Models\PreregistrationPage;
+use App\Rules\ValidPhoneNumber;
+use App\Services\PhoneNumberNormalizer;
 use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
 use Illuminate\Validation\Rules\Email;
 
 class SubscribePublicPageRequest extends FormRequest
@@ -28,13 +31,23 @@ class SubscribePublicPageRequest extends FormRequest
             ->rfcCompliant()
             ->preventSpoofing();
 
+        $phoneRules = ['nullable', 'string', 'max:255'];
+
+        if ($page->isPhoneFieldEnabledForSubscribers()) {
+            $phoneRules = [
+                Rule::requiredIf(fn (): bool => $page->isPhoneFieldRequiredForSubscribers()),
+                'nullable',
+                'string',
+                'max:32',
+                new ValidPhoneNumber(app(PhoneNumberNormalizer::class)),
+            ];
+        }
+
         return [
             'first_name' => ['required', 'string', 'max:255'],
             'last_name' => ['required', 'string', 'max:255'],
             'email' => ['required', 'string', 'max:255', $emailRule],
-            'phone' => $page->isPhoneFieldEnabledForSubscribers()
-                ? ['nullable', 'string', 'regex:/^[0-9]{8,15}$/']
-                : ['nullable', 'string', 'max:255'],
+            'phone' => $phoneRules,
         ];
     }
 
@@ -45,7 +58,6 @@ class SubscribePublicPageRequest extends FormRequest
     {
         return [
             'email' => __('Please enter a valid email address.'),
-            'phone.regex' => __('Please enter a valid phone number (8–15 digits).'),
         ];
     }
 
@@ -73,15 +85,22 @@ class SubscribePublicPageRequest extends FormRequest
 
         /** @var PreregistrationPage $page */
         $page = $this->route('publicPage');
-        $phone = $this->input('phone');
         if (! $page->isPhoneFieldEnabledForSubscribers()) {
             $this->merge(['phone' => null]);
 
             return;
         }
+
+        $phone = $this->input('phone');
+        if ($phone === null || $phone === '') {
+            $this->merge(['phone' => null]);
+
+            return;
+        }
+
         if (is_string($phone)) {
-            $digits = preg_replace('/\D+/', '', $phone);
-            $this->merge(['phone' => $digits === '' ? null : $digits]);
+            $trimmed = trim($phone);
+            $this->merge(['phone' => $trimmed === '' ? null : $trimmed]);
         }
     }
 }

app/Jobs/SyncSubscriberToMailwizz.php

@@ -128,7 +128,7 @@ class SyncSubscriberToMailwizz implements ShouldBeUnique, ShouldQueue
         ];
 
         if ($phoneEnabled && $config->field_phone !== null && $config->field_phone !== '') {
-            $phone = $subscriber->phone;
+            $phone = $subscriber->phoneDisplay();
             if ($phone !== null && $phone !== '') {
                 $data[$config->field_phone] = $phone;
             }

app/Models/PreregistrationPage.php

@@ -108,6 +108,19 @@ class PreregistrationPage extends Model
         return (bool) $this->phone_enabled;
     }
 
+    /**
+     * When the form block marks the phone field as required (only applies if phone is enabled).
+     */
+    public function isPhoneFieldRequiredForSubscribers(): bool
+    {
+        $form = $this->getBlockByType('form');
+        if ($form !== null) {
+            return (bool) data_get($form->content, 'fields.phone.required', false);
+        }
+
+        return false;
+    }
+
     public function headlineForMeta(): string
     {
         $hero = $this->getHeroBlock();

app/Models/Subscriber.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Models;
 
+use App\Services\PhoneNumberNormalizer;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -36,6 +37,52 @@ class Subscriber extends Model
         return $this->belongsTo(PreregistrationPage::class);
     }
 
+    /**
+     * @param  string|null  $value
+     */
+    public function setPhoneAttribute(mixed $value): void
+    {
+        if ($value === null) {
+            $this->attributes['phone'] = null;
+
+            return;
+        }
+
+        if (! is_string($value)) {
+            $this->attributes['phone'] = null;
+
+            return;
+        }
+
+        $trimmed = trim($value);
+        if ($trimmed === '') {
+            $this->attributes['phone'] = null;
+
+            return;
+        }
+
+        $normalized = app(PhoneNumberNormalizer::class)->normalizeToE164($trimmed);
+        $this->attributes['phone'] = $normalized;
+    }
+
+    /**
+     * Phones are stored as E.164 (e.g. +31612345678). Legacy rows may still be digits-only.
+     */
+    public function phoneDisplay(): ?string
+    {
+        $phone = $this->phone;
+        if ($phone === null || $phone === '') {
+            return null;
+        }
+
+        $p = (string) $phone;
+        if (str_starts_with($p, '+')) {
+            return $p;
+        }
+
+        return preg_match('/^\d{8,15}$/', $p) === 1 ? '+'.$p : $p;
+    }
+
     public function scopeSearch(Builder $query, ?string $term): Builder
     {
         if ($term === null || $term === '') {
@@ -47,7 +94,8 @@ class Subscriber extends Model
         return $query->where(function (Builder $q) use ($like): void {
             $q->where('first_name', 'like', $like)
                 ->orWhere('last_name', 'like', $like)
-                ->orWhere('email', 'like', $like);
+                ->orWhere('email', 'like', $like)
+                ->orWhere('phone', 'like', $like);
         });
     }
 }

app/Providers/AppServiceProvider.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Providers;
 
 use App\Models\PreregistrationPage;
+use App\Services\PhoneNumberNormalizer;
 use Illuminate\Pagination\Paginator;
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\ServiceProvider;
@@ -16,7 +17,11 @@ class AppServiceProvider extends ServiceProvider
      */
     public function register(): void
     {
-        //
+        $this->app->singleton(PhoneNumberNormalizer::class, function (): PhoneNumberNormalizer {
+            return new PhoneNumberNormalizer(
+                (string) config('preregister.default_phone_region', 'NL')
+            );
+        });
     }
 
     /**

app/Rules/ValidPhoneNumber.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Rules;
+
+use App\Services\PhoneNumberNormalizer;
+use Closure;
+use Illuminate\Contracts\Validation\ValidationRule;
+
+final class ValidPhoneNumber implements ValidationRule
+{
+    public function __construct(
+        private readonly PhoneNumberNormalizer $normalizer
+    ) {}
+
+    public function validate(string $attribute, mixed $value, Closure $fail): void
+    {
+        if ($value === null || $value === '') {
+            return;
+        }
+
+        if (! is_string($value)) {
+            $fail(__('Please enter a valid phone number.'));
+
+            return;
+        }
+
+        if ($this->normalizer->normalizeToE164(trim($value)) === null) {
+            $fail(__('Please enter a valid phone number.'));
+        }
+    }
+}

app/Services/PhoneNumberNormalizer.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use libphonenumber\NumberParseException;
+use libphonenumber\PhoneNumberFormat;
+use libphonenumber\PhoneNumberUtil;
+
+/**
+ * Parses international and national phone input and normalizes to E.164 for storage (includes leading +).
+ */
+final class PhoneNumberNormalizer
+{
+    public function __construct(
+        private readonly string $defaultRegion
+    ) {}
+
+    /**
+     * Returns E.164 (e.g. +31612345678) or null if empty/invalid.
+     */
+    public function normalizeToE164(?string $input): ?string
+    {
+        if ($input === null) {
+            return null;
+        }
+
+        $trimmed = trim($input);
+        if ($trimmed === '') {
+            return null;
+        }
+
+        $util = PhoneNumberUtil::getInstance();
+
+        try {
+            $number = $util->parse($trimmed, $this->defaultRegion);
+        } catch (NumberParseException) {
+            return null;
+        }
+
+        if (! $util->isValidNumber($number)) {
+            return null;
+        }
+
+        return $util->format($number, PhoneNumberFormat::E164);
+    }
+}