Laravel Tel Input Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require victorybiz/laravel-tel-input
   npm install intl-tel-input --save
   

   Publish assets and config:

   php artisan vendor:publish --provider="VictoryBiz\TelInput\TelInputServiceProvider" --tag=config
   npm run dev  # or build if using Laravel Mix
   

2. First Use Case: Add the directive to a Blade form:

   <x-tel-input name="phone" placeholder="Enter phone number" />
   

   This renders a country-aware phone input with auto-formatting.

3. Livewire Integration: For Livewire 2/3, use the provided component:

   <x-tel-input wire:model="phone" name="phone" />
   

Where to Look First

• Blade Directives: Check resources/views/vendor/tel-input/ for default templates.
• Configuration: Review config/tel-input.php for default country, utilsScript, and other settings.
• JavaScript: Inspect resources/js/tel-input.js for customization hooks.

Implementation Patterns

Core Workflows

1. Basic Form Integration:

   <form method="POST" action="/contact">
       @csrf
       <x-tel-input name="phone" required />
       <button type="submit">Submit</button>
   </form>
   

   • Automatically validates and formats input (e.g., +1 (123) 456-7890).

2. Livewire Data Binding:

   // Livewire Component
   public $phone = '';
   
   // Blade
   <x-tel-input wire:model="phone" name="phone" />
   

   • Syncs with Livewire’s reactivity system; no manual JS handling needed.

3. Country-Specific Logic:

   <x-tel-input
       name="phone"
       default-country="us"
       separate-dial-code
       wire:model="phone"
   />
   

   • default-country: Pre-selects a country (e.g., us, gb).
   • separate-dial-code: Shows dial code separately (e.g., +1 dropdown).

4. Validation:

   use VictoryBiz\TelInput\Rules\Phone;
   
   $request->validate([
       'phone' => ['required', new Phone],
   ]);
   

   • Uses VictoryBiz\TelInput\Rules\Phone for server-side validation.

Integration Tips

• Custom Templates: Override Blade directives in resources/views/vendor/tel-input/.
• Asset Optimization: Use Laravel Mix/Vite to bundle intl-tel-input with your app’s JS.
• Localization: Pass lang to the directive (e.g., lang="es") for translated UI.
• Hidden Inputs: Use hidden-input to store raw formatted data:

  <x-tel-input name="phone" hidden-input="phone_raw" />
  

Gotchas and Tips

Common Pitfalls

1. Missing JavaScript:

   • Error: Input renders but doesn’t format numbers.
   • Fix: Ensure intl-tel-input is included in your JS bundle and utilsScript is set in config (e.g., https://cdnjs.cloudflare.com/ajax/libs/intl-tel-input/17.0.8/js/utils.js).

2. Livewire 3 Compatibility:

   • Issue: wire:model may not sync properly if using older Livewire versions.
   • Fix: Explicitly declare the property in your Livewire component and use wire:model.live for real-time updates.

3. Validation Mismatch:

   • Error: Server rejects valid-looking phone numbers.
   • Fix: Use new Phone(['country' => 'us']) to specify validation rules per country.

4. Country Codes Not Loading:

   • Cause: Missing intl-tel-input CSS or JS.
   • Fix: Verify node_modules/intl-tel-input/build/css/intlTelInput.css is linked in your layout.

Debugging Tips

• Check Console: Look for intlTelInput errors in browser dev tools.
• Inspect Network: Ensure utils.js and country data files load (e.g., https://cdnjs.cloudflare.com/ajax/libs/intl-tel-input/17.0.8/js/country-data.js).
• Log Raw Input: Add a hidden field to debug formatted vs. raw values:

  <input type="hidden" name="phone_raw" id="phone_raw">
  <script>
      document.getElementById('phone').addEventListener('countrychange', (e) => {
          console.log('Formatted:', e.target.value);
          console.log('Full number:', e.target.intlTelInput.getNumber());
      });
  </script>
  

Extension Points

1. Custom Countries: Modify config/tel-input.php to include/exclude countries:

   'countries' => ['us', 'gb', 'de'], // Default: all
   

2. Dynamic Configuration: Pass options dynamically via Blade:

   <x-tel-input
       name="phone"
       :options="['onlyCountries' => ['us', 'ca'], 'geoIpLookup' => false]"
   />
   

3. Event Listeners: Attach JS events to the input:

   document.addEventListener('DOMContentLoaded', () => {
       const input = document.querySelector('#phone');
       input.intlTelInput('on', 'countrychange', (e) => {
           console.log('Country changed:', e.countryData.iso2);
       });
   });
   

4. Server-Side Parsing: Use the VictoryBiz\TelInput\Phone helper to parse numbers:

   use VictoryBiz\TelInput\Phone;
   
   $phone = Phone::parse($request->phone, 'us'); // Returns normalized E.164 format