Idna Convert Laravel Package

Product Decisions This Supports

• International market entry / localization roadmap. Native-script domains and TLDs (.中国, .рф, .भारत, Arabic-script labels) are how a meaningful share of users type their own web. This package decides whether onboarding, login, and storefront can accept those inputs at all — a hard gate for launches in those markets.
• Signup and identity flows. Validating and normalizing internationalized domain names and domain-based identifiers (B2B tenant domains, org names, vanity URLs). Directly reduces "my domain is invalid" support tickets.
• Data model / architecture commitment. Canonical storage in punycode (A-label) with Unicode (U-label) display is a schema-level decision with long tails: unique indexes, dedupe, analytics grouping, search. A cheap conversion layer lets us prove the model before committing.
• UGC, CMS, and link handling. Whether to accept and render IDN links, and whether to show decoded Unicode for user trust. This is a trust/UX call as much as a technical one — decoded links are more legible, punycode more honest.
• Security and abuse scope. Homograph and lookalike-domain exposure in user-submitted URLs and in our own brand monitoring. Worth scoping explicitly: this package converts, it does not detect confusables.
• Build vs buy on a deceptively hard problem. Punycode plus nameprep, normalization, bidi rules, and contextual joining is exactly the kind of spec everyone underestimates. In-house implementations fail silently on edge-case scripts. Strong default: buy.
• SEO and canonicalization. Consistent A-label canonical URLs across sitemap, rel=canonical, hreflang, and redirects — affects indexation for localized properties.
• Roadmap sequencing. Answers "is IDN support a launch blocker for market X, or a fast-follow?" with a concrete effort estimate instead of a guess.

When to Consider This Package

Consider it when:

• You need IDNA conversion in pure PHP with no ext-intl / ICU dependency — shared hosting, minimal containers, or production images you can't easily rebuild.
• You need explicit IDNA2003 vs IDNA2008 (transitional vs non-transitional) control rather than inheriting whatever ICU version the host happens to ship. Deterministic behavior across environments is the single strongest argument for this package.
• Your volume is modest and off the hot path — signup validation, admin tooling, import jobs — not a high-throughput resolver.
• You want a dependency-free leaf with no transitive tree, keeping supply-chain and upgrade surface small.
• You're already on the mso/idna-convert lineage and want a maintained continuation. Treat the fork as a like-for-like swap only after checking provenance, changelog, and test coverage.

Look elsewhere when:

• You want ecosystem certainty and default safety: symfony/polyfill-intl-idn (MIT, ubiquitous, also works without ext-intl) or ext-intl's idn_to_ascii when ICU is acceptable. Make one of these the default choice; deviate only for the determinism reason above.
• You need confusable / homograph / mixed-script detection (UTS #39) — that's a different library and a different scope.
• You need DNS resolution, WHOIS/RDAP, or registrability checks. Conversion is one step, not the feature.
• You need true end-to-end EAI / SMTPUTF8 email support. Conversion alone won't deliver it.
• Licensing is constrained. LGPL-2.1 is workable for hosted SaaS and typical PHP deployment, but closed-source redistribution or shipping in an appliance needs legal review, and local patches must be published.
• Social proof is a requirement. 71 stars and 0 dependents means you are the load-bearing adopter. Budget for reading the source and pinning a version.
• Bulk conversion is performance-critical. Benchmark; a pure-PHP implementation will not match ICU.

Adoption guardrails: pin an exact version; wrap it behind an internal IdnConverter / DomainNormalizer interface so the vendor is swappable in days; own test fixtures for the specific scripts and TLDs we care about; watch upstream release cadence (recent releases are a positive signal — confirm it holds).

How to Pitch It (Stakeholders)

Executives: This is a small, tactical dependency that unlocks international customers — it lets us accept and display native-script domains and email addresses instead of rejecting them as invalid. Cost is close to zero: one pure-PHP library, no PHP extensions, no infrastructure change, no migration. The strategic value is market reach and reduced signup friction. The risk is maintenance depth — a small maintainer base and low adoption mean we can't outsource our confidence to the ecosystem — which we mitigate by isolating it behind an internal interface, making replacement a days-not-quarters exercise. Licensing is LGPL, fine for our hosted service, requiring a legal nod only if we ship on-prem. Recommendation: approve as a scoped enabler for [target market/feature], not as a platform bet.

Engineering: One dependency, zero transitive dependencies, no ext-intl requirement, and — the actual reason to prefer it — deterministic IDNA behavior independent of the host's ICU version, which the polyfill and ext-intl cannot promise across our pinned runtime fleet. We wrap it in a single normalization service, store A-labels canonically, render U-labels, and own fixtures for our target scripts. It does not do confusable detection; anti-spoofing is a separate scope decision, not a gap in this package. Effort is a small slice: conversion utility, schema/index confirmation, validation hooks, tests. Ongoing cost is a version pin plus a periodic upstream health check.