Phone Number Laravel Package

Product Decisions This Supports

• Build vs. buy for a bounded admin requirement. A Nova field swap — composer require, replace Text::make('phone') with PhoneNumber::make('phone'), php artisan nova:publish when assets go stale — is roughly half a day to a day including smoke tests, against one to two days of internal custom-field work. Position it as a reversible tactical shortcut, not a platform commitment.
• The canonical phone format decision — the real go/no-go. The package does not decide whether the database stores raw input, digits-only, or E.164. The PM must decide this before adoption. Recommended posture: E.164 at rest, human formatting at render. If the field persists the masked display string ((555) 123-4567), every downstream consumer — SMS/voice providers, dedupe, search, tel: links, analytics, CRM sync — inherits a permanent parsing problem. This single behavior determines whether adoption is a net win or a data-quality debt generator.
• Scope: presentation masking vs. telephony-grade validation. Decide explicitly whether the product needs entry-time guidance and basic validation, or genuine normalization, country-aware parsing, carrier/line-type detection, and compliance-grade handling. The former fits here; the latter means giggsey/libphonenumber-for-php or a vendor service, with this field reduced to a thin veneer over infrastructure you own anyway.
• Product identity reconciliation — the decision that gates the rest. The repository is a Laravel Nova field; the package description markets a general Laravel library for parsing, validating, and formatting international numbers on libphonenumber. Those are different products with different blast radii. Assume the field is what ships, and require a source read to confirm whether any standalone validation rule or formatter is actually exposed. If not, this package contributes zero to canonical phone handling beyond the admin panel, and the PM should not count it toward a normalization roadmap.
• Market and internationalization scope. Input masking is typically country-format-specific. If the product serves non-US numbers, extensions, or mixed regions, a US-shaped mask may actively obstruct correct entry. That is a market-scope decision surfaced as a UI decision — resolve it in product, not in the field's config.
• Surface prioritization: admin-only vs. first-class business asset. Approve for Nova-only admin capture where phone numbers are incidental and volume is low to moderate. Do not approve where phone data is a first-class asset (outbound messaging, dedupe, CRM sync, public forms, APIs, imports) — there the real investment is a shared normalization rule plus backfill, which this package neither provides nor obstructs.
• Roadmap sequencing and opportunity cost. Masked, validated phone entry in Nova CRUD screens is admin UX polish shippable without pulling engineering off higher-value work — useful when the roadmap needs a visible data-quality win at low cost.
• Vendor risk acceptance. 70 stars, zero dependents, single maintainer, MIT license. Acceptable given the shallow integration surface and cheap forkability — but record it as an accepted risk with a named owner, and make the fork-and-vendor call at adoption rather than after ten resources depend on it.
• Instrumentation as a product commitment. Approving adoption also means approving a recurring audit (distinct storage formats on the phone column) so silent corruption, truncated extensions, and stripped country codes surface before a downstream system does.

When to Consider This Package

Adopt when all of the following hold:

• The stack is Laravel Nova 4 or 5, and you are willing to pin your Nova major in composer.json and add a CI job that installs that pinned major, runs nova:publish, and asserts the field renders with an active mask.
• Phone numbers are incidental contact metadata on internal admin resources — Contact, Lead, Customer — with low to moderate volume and no messaging, dedupe, or sync dependency.
• Your entry market is effectively single-region (typically US), with no meaningful multi-country or extension requirements.
• You can enforce normalization outside the field — a model mutator or equivalent on the write path — so imports, seeders, tinker, and API writes are covered, not just the Nova form. If you cannot commit to this, do not adopt: you will get three definitions of "a valid phone number."
• You have capacity for a one-resource, one-release-cycle spike that answers, empirically, what the field writes to the database on submit.
• Someone owns the dependency: pinning, asset publishing in the deploy script, upgrade watching, and the fork-or-not decision on day one.

Look elsewhere — or scope this down to a plain text input plus server-side validation — when:

• Phone numbers are a first-class business asset: outbound SMS/voice, contact dedupe, CRM sync, public-facing forms, API ingestion, or analytics. The real deliverable there is a shared PhoneNumberRule backed by libphonenumber plus a backfill; this package covers none of that.
• Multi-country or extension entry is a live requirement. A fixed mask obstructs correct entry, and extensions get silently truncated. Plan a country-selector-plus-free-text field and a separate extension column instead.
• Your admin tool carries an accessibility commitment. Masking libraries commonly break paste, autofill, screen readers, and mobile numeric keyboards; treat that as an adoption gate, tested on a real device with a real screen reader, not an afterthought.
• You run a CSP-strict environment and cannot get an explicit sign-off for any inline-script or unsafe-eval dependency in the compiled assets.
• The team will not accept a single-maintainer, zero-dependent dependency without either forking it under your namespace or accepting the upgrade-breakage risk in writing.

How to Pitch It (Stakeholders)

For executives — one paragraph. This is a small, MIT-licensed Laravel Nova field that gives our internal admin screens formatted, validated phone entry for roughly half a day of work instead of one to two days of custom build. It is a tactical admin-UX improvement, not a platform bet, and it is reversible. The value is only realized if we also make one product decision up front: store phone numbers in canonical E.164 form and format them only for display. If we skip that, the field will happily save human-formatted strings, and every future integration — messaging, dedupe, CRM sync, reporting — inherits a parsing problem. The ask is approval for the field swap plus the normalization rule behind it, not approval for the field alone.

For engineering — what we are and are not buying. We are buying a Nova field with client-side masking and validation, plus compiled assets delivered through Nova's publish pipeline. We are not buying a canonical phone-number library: the package description advertises a general libphonenumber-backed parser/formatter, but the repository is a Nova field, so treat any standalone rule or helper as unconfirmed until someone reads vendor/dniccum/phone-number/src/. Plan on giggsey/libphonenumber-for-php for parsing, formatting, and the shared validation rule used by form requests, imports, and APIs. Two non-negotiables: (1) a staging spike that dd()s the model after typing (555) 123-4567, because persistence behavior is the entire risk and it is undocumented; (2) normalization on the model write path, so Nova is not the only place data gets cleaned.

Decisions requested, and from whom.

Success looks like: one internal resource running the field for a release cycle, a phone column whose distinct-format count is 1 (E.164), no regression in paste/autofill/mobile entry, and a shared validation rule used identically by Nova and the application's write paths. Failure looks like: masked strings in the database, extensions quietly dropped, and a second source of un-normalized data arriving via CSV import.