Intl Tel Input Bundle Laravel Package

Getting Started

• Install with Composer: composer require mpetrini/intl-tel-input-bundle. In Symfony 4, register the bundle in config/bundles.php if Flex does not do it automatically.
• Look first at the package README, then Form/Type/, Resources/config/, Resources/views/Form/, and Resources/public/. Those tell you whether it exposes a custom form type, a form type extension, a Twig form theme, or prebuilt assets.
• Install the front-end dependency. The bundle may ship an older copy of intl-tel-input, but most teams will want to install intl-tel-input via npm/yarn and include it through Webpack Encore or a CDN.
• First use case: add a phone field to a contact or registration form. Use the bundle’s form type if present, render the form normally, and confirm that the country dropdown, flag sprite, and formatted number appear.
• As a Laravel developer, treat this as a Symfony-specific reference implementation. You would not install it in Laravel; you would copy the pattern: render an input with the right data attributes, initialize intlTelInput in JavaScript, and submit an E.164-formatted value to the server.

Implementation Patterns

• Use the bundle’s form type directly in a Symfony form:

  $builder->add('phone', IntlTelInputType::class, [
      'initial_country' => 'us',
      'preferred_countries' => ['us', 'gb', 'de'],
  ]);
  

  If the bundle only provides a type extension, add the option to a normal TextType or TelType instead.
• Keep a visible phone input for the widget and a hidden input for the canonical value. On submit, call intlTelInput.getNumber() and write the E.164 result into the hidden field before the form posts.
• Normalize and validate server-side. Client-side intl-tel-input validation is a convenience only. Use giggsey/libphonenumber-for-php in a custom constraint or form event to validate and reformat the submitted number.
• Reuse the field through a Twig form theme block. If the bundle provides a block, override it in your app’s form theme to control markup, classes, and hidden-input behavior.
• For AJAX-driven forms, reinitialize intlTelInput after the field is inserted into the DOM. The plugin binds to an existing input element, so replacing HTML requires a new call.
• Store phone numbers in E.164 form (+14155552671) and keep the country code separately only if your domain needs it. This avoids ambiguity when users change the country selector.
• In EasyAdmin, Sonata, or custom admin forms, override the field template and include the same JavaScript initialization used on the front end.
• If the bundle’s form type is too rigid, decorate it or write a form type extension that adds only the data attributes you need. You can also bypass the bundle and initialize the plugin yourself; the integration surface is mostly HTML and JavaScript.

Gotchas and Tips

• The package has no stars and no dependents. Audit the source before relying on it in production, and expect little ongoing maintenance.
• It targets Symfony 4. Check compatibility before using it on Symfony 5/6; form type signatures, bundle registration, and asset handling may differ.
• The bundled intl-tel-input version may be old. If you need current country data, formatting, or accessibility fixes, install the npm package and override the bundle’s assets.
• The flag sprite CSS uses relative image paths. If flags are missing, check how assets are published or served through Encore/CDN and adjust the CSS background-image path.
• Make sure utils.js is loaded if you rely on formatting or validation helpers. Many “undefined is not a function” errors come from missing utils rather than the core plugin.
• Set the initial number explicitly after initialization: call setNumber() or set the input’s value, then trigger the plugin’s country detection. Otherwise, editing an existing record can show the wrong country.
• Do not trust the visible formatted value. The submitted value should come from getNumber() or a hidden field updated on countrychange and blur.
• Debug by inspecting the generated input’s data-* attributes and checking the browser console for intlTelInput is not defined. If the bundle silently renders a plain input, its form theme block or asset include is probably not active.
• Extension points are limited: override the form theme, decorate the form type, add a form type extension, or replace the bundle’s JavaScript with your own initializer. For a Laravel app, the pragmatic path is to skip the bundle entirely and use the npm package with Alpine, Vue, or Livewire.