Filament Phone Input Laravel Package

Product Decisions This Supports

• Data model for phone numbers. The package forces an explicit decision on how we store numbers: E.164 (default, inputNumberFormat) versus national format, and whether to persist the country separately via countryStatePath('phone_country'). That choice affects deduplication, matching against call/SMS vendors, migration effort later, and reporting by region. Getting this wrong is expensive to unwind, so the component is a forcing function for a decision we'd otherwise defer.
• Validation policy per market. validateFor(country, type, lenient) lets us encode business rules — e.g. mobile-only for SMS-based 2FA markets, fixed-line allowed for B2B account contacts, or a country allowlist for a launch region. This is a product policy question (who can sign up, which regions we serve) that becomes a one-line config rather than custom code.
• Build vs. buy for admin-panel form inputs. Building a country-flag dropdown + libphonenumber parsing + format-on-display + format-as-you-type in-house is roughly a 1–2 week build with ongoing maintenance; this is a composer require plus asset publish. Good candidate for "buy" — it is UI plumbing, not differentiation.
• Scope and market coverage decisions. onlyCountries / excludeCountries / countryOrder make region rollout a configuration lever rather than an engineering ticket — a launch in three countries can ship without a code change when we expand.
• UX and support-cost tradeoffs. Options like separateDialCode, showFlags(false), countrySearch, autoPlaceholder, useFullscreenPopup, and disableLookup() (geo-IP) are levers to test against support-ticket volume and form abandonment, not architecture. Low-cost experiments.
• Consistent display across surfaces. PhoneInput (form), PhoneColumn (table), and PhoneEntry (infolist) share one formatting vocabulary (PhoneInputNumberType::NATIONAL | E164 | INTERNATIONAL | RFC3966), so support agents, exports, and dashboards see numbers identically — a small but real defection-reduction lever.
• Roadmap signal for the admin layer. Because the package is Filament-specific, adopting it is a soft commitment to Filament for internal tooling. That is a platform decision worth making consciously rather than by accretion.

When to Consider This Package

Consider it when:

• We're on Filament 3.x with PHP ^8.1 and internal/admin forms are the primary surface. This is squarely an internal-tooling component, not a public-facing signup widget.
• The product genuinely handles international numbers, or will within the planning horizon — otherwise a plain TextInput plus a regex is cheaper in dependencies.
• We want libphonenumber-grade validation without owning the parsing logic (it wraps propaganistas/laravel-phone, which brings libphonenumber).
• A short time-to-market matters more than owning the input, and the team has no dedicated frontend capacity for a phone widget.
• We can absorb one additional JS asset pipeline step (filament:assets + filament-phone-input:install) in deploy.

Look elsewhere or build thin when:

• We're on or moving to Filament 4 — the README explicitly scopes this to Filament 3 (with a 3.x branch), so upgrade timing is a real risk. Verify a v4-compatible release exists before committing.
• We need asynchronous phone verification (OTP, Twilio/Vonage lookup, carrier type detection). This package validates format; it does not verify the number belongs to the user. That's a separate vendor decision.
• We need heavy markup control, design-system conformance, or custom per-country dynamic fields — we'd end up fighting the wrapper around intl-tel-input.
• Procurement or security review requires vendor support, an SLA, or a named corporate maintainer. This is an MIT, effectively single-maintainer package (~329 stars, 0 dependent packages on Packagist). Note the caveat: dependents counts packages, not applications, so it understates real usage — but it does mean low ecosystem entrenchment and no downstream pressure to keep it healthy. We should be prepared to fork.
• Numbers are single-country and stable — the abstraction earns nothing.
• The public-facing side of the product needs it too; that's a different component, and using two implementations risks format inconsistency.

De-risk before committing: confirm Filament 4 status in the changelog, pin the version, and confirm the laravel-phone and intl-tel-input transitive dependencies pass our dependency policy.

How to Pitch It (Stakeholders)

One line: A drop-in, MIT-licensed phone number input for our Filament admin panel that handles country selection, formatting, and libphonenumber-grade validation — roughly a week of build we don't do, and a data-format decision we make explicitly now instead of migrating later.

To executives: Low cost, low lock-in. MIT license, no per-seat or usage fee, installs in an afternoon. The value is threefold: (1) fewer bad phone numbers entering the system, which directly reduces failed SMS/OTP and manual cleanup; (2) faster delivery of international support across our admin surfaces; (3) it forces a clean, canonical storage format so our data stays portable to whatever CRM or messaging vendor we pick next. The risk is maintenance, not money — it's a small, single-maintainer project, so we pin the version and treat it as forkable if it stalls. We should decide before we're on Filament 4, since that's the main upgrade constraint.

To engineering: It wraps intl-tel-input on the frontend and propaganistas/laravel-phone on the backend, exposing one component (PhoneInput) plus a PhoneColumn and PhoneEntry for tables and infolists. Integration is composer + two artisan commands to publish assets, then configuration at the field level — inputNumberFormat, displayNumberFormat, defaultCountry, validateFor, and countryStatePath if we split country into its own column. Two things to check in a spike: the Filament 4 compatibility path, and whether we're comfortable owning the transitive dependency chain. Recommend we pin a version, add a translation key per the README's validation note, and avoid deep customization of the underlying markup so a fork stays cheap.