Idna Convert Laravel Package

Product Decisions This Supports

• International market expansion (i18n domains). Whether we can accept, store, validate, and display domain names in non-Latin scripts (e.g. münchen.de, 例え.jp, Arabic/Cyrillic TLDs) in signup, checkout, storefront, and email flows. This package is the conversion layer that makes those flows possible without native extensions.
• Build vs. buy on the IDNA primitive. Writing Punycode encoding is ~100 lines; correctly implementing IDNA2008/UTS #46 mapping, normalization, and validity tables is not. Adopting a maintained converter is almost always cheaper than owning that logic — this package is a valid candidate for that "buy" option, but see the license caveat below.
• Infrastructure constraints as a product constraint. Because it's pure PHP, IDN support stops being gated on ext-intl/ICU availability in our hosting or container image. This directly affects whether we can ship IDN features to customers on shared hosting, older PaaS runtimes, or locked-down enterprise deployments.
• Security posture for domain-facing surfaces. Any place we compare or allowlist hostnames (SSRF allowlists, webhook targets, redirect/return URLs, email domain checks, partner integrations) must compare canonical Punycode, not raw Unicode. Unicode/Punycode mismatch is a known bypass class; a converter is a prerequisite for correct validation, not a nicety.
• Data model and canonicalization decisions. Whether we store the Unicode form, the A-label (Punycode) form, or both, and how we canonicalize for uniqueness constraints, deduplication, and search. This package informs the normalization rules the data model depends on.
• Email and identity flows. Validating internationalized email domains (EAI/IDN) for registration, invitations, and notifications to non-Latin-market users.
• SEO/link integrity roadmap. Canonical URL generation and redirect handling for IDN properties, ensuring marketing sites and campaign links resolve consistently across browsers, CDNs, and analytics tooling.
• Roadmap sequencing. If IDN support is a "someday" item, this is a low-cost, reversible spike that lets us validate demand for international cohorts before committing to an ICU-based platform standard.

When to Consider This Package

Consider it when:

• ext-intl is unavailable or cannot be guaranteed across our deployment targets (shared hosting, minimal containers, Windows dev parity, per-tenant runtime variance).
• We need a self-contained conversion layer with no system library dependency, and the surface area we need is narrow: encode() / decode() around domain strings.
• We want to wrap conversion behind our own interface (e.g. DomainNormalizer) so the implementation is swappable — this package becomes one adapter behind that interface.
• LGPL-2.1 is acceptable to legal, or the usage is clearly internal/non-distributed in a way counsel signs off on.
• We can tolerate a low-adoption, effectively single-maintainer dependency, with mitigations: pin an exact version, vendor the source, and add our own conformance test vectors.

Look elsewhere when:

• ext-intl is reliably available. Native idn_to_ascii() / idn_to_utf8() with ICU is the default choice: faster, battle-tested, no supply-chain exposure. Choose it unless we have a concrete reason not to.
• License policy restricts copyleft. LGPL-2.1 is a real friction point for teams that distribute PHP source; many enterprises blanket-flag it. symfony/polyfill-intl-idn (MIT) is the pure-PHP, Composer-native, widely-deployed alternative and should be the first comparison — it's often the better buy on maintenance and legal grounds alone.
• We need an actively maintained dependency with security response guarantees. 71 stars and the release metadata here warrant verification: check the actual release cadence, commit history, issue responsiveness, and any CVE history before adoption. Treat this as a fork-of-a-classic (phlyLabs lineage) rather than a vendor with an SLA.
• The real requirement is URL/IRI handling, not just hostnames. Use a URL library (league/uri, Symfony's HttpFoundation/Routing) that wraps IDN conversion rather than calling a converter directly in application code.
• The requirement is IDNA2003-legacy behavior or specific registrar rules, or we need TLD-specific policy validation (registrar/SLA semantics) — that's a different product surface than charset conversion.
• We need browser-parity guarantees. Browser IDN display rules (UTS #46 transitional vs. nontransitional, deviation characters) are subtle; validate against real browser behavior rather than assuming any library matches.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost utility that unblocks international domain support without changing our infrastructure. It lets us serve customers in non-Latin-script markets — a prerequisite for expansion into several target regions — for roughly the cost of one integration task. The two things to know: it carries a copyleft-flavored license (LGPL-2.1) that legal should clear before we ship it in distributed code, and it is a low-adoption, single-maintainer project rather than a vendor-supported component. Both are manageable if we isolate it behind our own interface and keep the swap to PHP's built-in intl as a one-line change. Recommendation: approve for a bounded spike, not as a permanent platform commitment.

To engineering: Pure-PHP IDNA/Punycode converter, Composer-installable, no ext-intl requirement — the value is portability across environments where ICU isn't guaranteed. Please treat it as an implementation detail: put it behind a DomainNormalizer contract with toAscii() / toUnicode(), pin the exact version, vendor the source, and add our own conformance fixtures (mixed-script, deviation characters, trailing-dot, uppercase, empty-label cases). Do not call it inline in controllers; all hostname comparison, allowlisting, and uniqueness checks must run through the normalizer so we never compare raw Unicode to Punycode. Document the fallback path to native idn_to_ascii() and benchmark both.

To legal/security: LGPL-2.1 — please confirm obligations for our distribution model. Separately, flag that this component is security-relevant: correct IDN canonicalization is a control against homograph/lookalike and allowlist-bypass attacks, so an unmaintained converter is a latent risk. Ask for a maintenance check (release cadence, open security issues, maintainer responsiveness) before we rely on it in any trust boundary.