Filament Phone Input Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require erlenwald/filament-phone-input
   php artisan vendor:publish --tag=filament-phone-input-assets
   php artisan filament:assets
   php artisan optimize:clear
   

2. Basic Usage:

   use Erlenwald\FilamentPhoneInput\PhoneInput;
   
   PhoneInput::make('phone')
       ->required()
       ->label('Phone Number');
   

3. First Use Case: Add a phone field to a Filament form/resource:

   // In a Filament Form or Resource
   PhoneInput::make('contact_phone')
       ->phoneNumberFormat(\Erlenwald\FilamentPhoneInput\Enums\PhoneNumberFormat::E164);
   

Implementation Patterns

Common Workflows

1. Form Integration:

   // In a Filament Form
   PhoneInput::make('phone')
       ->phoneStatePath('normalized_phone')
       ->countryStatePath('country_code')
       ->defaultCountry('US');
   

2. Resource Usage:

   // In a Filament Resource
   PhoneInput::make('user_phone')
       ->countries(['US', 'CA', 'GB'])
       ->favoriteCountries(['US', 'CA'])
       ->displayCountryFlag();
   

3. Dynamic Configuration:

   PhoneInput::make('phone')
       ->phoneNumberFormat(fn ($record) => $record->preferred_format ?? 'e164')
       ->countries(fn ($record) => $record->allowed_countries ?? ['US', 'GB']);
   

4. Validation Integration:

   PhoneInput::make('phone')
       ->required()
       ->rules(['regex:/^\+[0-9]{10,15}$/']);
   

Integration Tips

• State Management: Use phoneStatePath() and countryStatePath() to customize how data is stored in your database.
• Localization: Publish translations (filament-phone-input-translations) and override country names or labels.
• IP-Based Detection: Enable IP lookup for automatic country detection:

  PhoneInput::make('phone')
      ->enableIpLookup()
      ->ipLookup('/api/ip-country', 'country');
  

• Flag Customization: Use SVG flags by publishing and overriding CSS variables in resources/css/vendor/erlenwald/filament-phone-input/phone-input.css.

Gotchas and Tips

Pitfalls

1. Asset Publishing:

   • Forgetting to publish assets (filament-phone-input-assets) will break flag display.
   • Always run filament:assets and optimize:clear after publishing custom CSS or translations.

2. Country Restrictions:

   • countries() restricts the dropdown, while defaultCountry() only sets a fallback. Ensure these are aligned with your use case.

3. IP Lookup:

   • IP lookup is not a replacement for user input. It only populates the field if empty.
   • Test your IP lookup endpoint thoroughly, as malformed responses may cause errors.

4. Flag Atlas:

   • SVG flags are larger (~1.5MB) than WebP (~188KB). Use WebP by default unless SVG is explicitly needed.

5. State Path Conflicts:

   • Overriding phoneStatePath() without considering existing database columns may lead to missing data or validation errors.

Debugging Tips

• Check Published Assets: Verify flags are in public/vendor/erlenwald/filament-phone-input/flags/ after publishing.
• Inspect Network Requests: Use browser dev tools to confirm IP lookup endpoints return valid JSON (e.g., {"country_code": "US"}).
• Clear Cache: After publishing custom CSS/translations, always run:

  php artisan optimize:clear
  php artisan filament:assets
  

• Log State: Add temporary logging to confirm state paths are working:

  ->phoneStatePath(fn ($state) => {
      \Log::info('Phone state path:', ['path' => $state]);
      return 'custom_phone';
  });
  

Extension Points

1. Custom Formats: Extend the PhoneNumberFormat enum or use raw strings for non-standard formats:

   ->phoneNumberFormat('custom:[+][country_code][number]');
   

2. Dynamic Countries: Fetch countries dynamically from an API:

   ->countries(fn () => collect(http_get('api/countries'))->pluck('code')->toArray())
   

3. Custom Validation: Override validation rules in your Form/Resource:

   ->rules(['phone' => 'required|phone:US,CA,GB']);
   

4. Styling: Override CSS variables in phone-input.css:

   .fi-phone-input__input {
       --fi-phone-input-input-border-color: #e2e8f0;
   }
   

5. Translations: Extend published translations for custom country names or labels:

   // lang/vendor/erlenwald-filament-phone-input/en/phone-input.php
   return [
       'countries' => [
           'XX' => 'Custom Country Name',
       ],
   ];