Punycode Laravel Package

Technical Evaluation

Architecture fit. rowbot/punycode is a single-purpose, framework-agnostic PHP codec: Bootstring/Punycode encoding (RFC 3492) for IDN conversion to and from the xn-- ASCII form. It has no Laravel coupling, no service provider, no config surface, and no opinion about validation, normalization, or storage. That is a good architectural shape — a pure function behind a small class — but it also means it is a component, not a capability. A TPM should treat it as a low-level primitive to be wrapped, not adopted as a platform dependency.

The most important strategic question is whether we need it at all. Most Laravel applications already have a Punycode encoder transitively (Symfony Mime → symfony/polyfill-intl-idn), and PHP's ext-intl provides idn_to_ascii() / idn_to_utf8() with the UTS#46 variant, which covers IDNA mapping and validation — not just raw Bootstring. This package sits below that line: it encodes and decodes, but by itself does not give us the full IDNA pipeline (Unicode normalization, case folding, bidi and contextual rules, disallowed-code-point rejection). Any adoption decision must be framed as "raw codec, wrapped and guarded by our own IDNA policy layer."

Integration feasibility. High and fast. Composer install, PSR-4 autoload, no extensions required beyond mbstring/iconv (verify against our base image), no bootstrapping. A wrapper service + optional facade is a half-day of work; the real effort is the IDNA policy layer and the differential testing described below.

Technical risk. The dominant risk is not code quality — it is the maintenance signal. One maintainer, 1 star, 0 dependents, no external validation, no published security policy, and no visible adoption by other projects. The surface is small (a few hundred lines), which makes vendor-and-own viable, but "small enough to fork" is not the same as "should be a dependency." Secondary risks: silent behavioral divergence from UTS#46 on edge cases (ß, ZWJ, bidi, trailing dot, emoji, mixed-script labels), and exception-vs-fallback semantics on invalid input that we would be inheriting.

Key questions.

• Do we need raw Punycode, or full IDNA2008/UTS#46 mapping+validation? If the latter, this package is one piece of many.
• Is ext-intl available in all our runtimes (local, CI, containers, shared hosting)? If yes, what does this package buy us over idn_to_ascii()?
• Does it normalize input (NFC) before encoding, and does it reject disallowed code points, or encode them anyway?
• What is the failure contract on malformed input — exception, null, or partial output?
• Does it handle long labels/overflow per RFC 3492 limits, and what is the behavior at the 63-octet boundary?
• Who owns it if the upstream maintainer stops responding? Are we prepared to vendor?
• Licensing/attribution: MIT is compatible, but we must ship the notice if vendored.

Integration Approach

Stack fit. PHP 8.x / Composer, zero framework assumptions; works identically in HTTP, queue, and CLI contexts. The natural Laravel integration is a thin IdnEncoder interface bound in a service provider, consumed by (a) a ValidDomainName validation rule, (b) a normalization step in registration/login and mailer address handling, (c) canonicalization before persistence and before route/tenant lookups.

Migration path. Do not call the library directly from application code. Define an interface (encode(string): string, decode(string): string, plus a tryEncode() returning a result object) and provide three bindings: ext-intl, symfony/polyfill-intl-idn, and rowbot/punycode. That gives us a swap-in path, lets us A/B against the incumbent in staging, and avoids a hard dependency on an unproven package. If we adopt, start in the lowest-blast-radius path (URL/domain display formatting) and expand outward.

Compatibility. Pin the version explicitly; verify the composer.json PHP constraint against our supported matrix (including the newest PHP minors, where deprecation noise is common in older libraries). Confirm no transitive dependency conflicts with Laravel's Symfony pins. Confirm the package does not rely on ext-intl internally — its differentiator is precisely that it should not.

Sequencing.

1. Spike: 1–2 days, encode/decode a corpus of Unicode domains, compare byte-for-byte against idn_to_ascii(..., INTL_IDNA_VARIANT_UTS46).
2. Build the interface + adapters; no production call sites yet.
3. Add the validation rule and boundary normalization (registration, login, mail, tenant creation) behind a feature flag.
4. Run differential tests in CI over a permanent corpus (IDN test vectors, bidi cases, ß, ZWJ, emoji, max-length labels, trailing dot, mixed case, already-encoded input).
5. Decide: keep as a dependency, vendor into app/Support/Idn, or drop in favor of ext-intl. Only then remove the flag.

Operational Impact

Maintenance. Effectively self-maintained. Budget a named owner and a recurring quarterly check (upstream activity, PHP version support, security advisories via our SCA tooling). The vendor-and-own option is realistic given the size, and reduces supply-chain surface — but it converts an upgrade problem into an internal code-ownership problem. Either way, the maintenance cost is small and bounded.

Support. No commercial support, no community of scale, so incident response is entirely internal. Mitigate by keeping the wrapper interface stable so the underlying implementation is replaceable within a release cycle. Add the package to the SCA/dependency-review allowlist only after the differential test corpus is green.

Scaling. Negligible runtime cost — pure CPU, microsecond-scale per conversion, no I/O, no state. The real scaling concern is not CPU but correctness at volume: domain canonicalization must be deterministic and idempotent, and should be cached (or better, computed once at write time and stored alongside the display form) so hot paths never re-encode. Encoding on every request is a design smell, not a performance one.

Failure modes.

• Divergence from UTS#46 — output differs from browsers/ext-intl, producing unresolvable links or mismatched records. Highest-probability failure; caught only by differential testing.
• Insufficient validation — encoding a visually confusable or mixed-script domain without rejecting it, creating homograph/spoofing exposure if we display Unicode forms.
• Non-idempotent canonicalization — the same human-typed domain stored under two keys, yielding duplicate accounts or split tenant data. Guard with a normalize-at-boundary rule and a unique index on the canonical form.
• Failure contract mismatch — exceptions from malformed input bubbling into user-facing 500s. Wrap in a result type and translate to validation errors.
• Boundary/overflow behavior on maximum-length labels and overlong input, including truncation.
• Abandonment — upstream goes quiet and a future PHP release breaks it. Low likelihood, low impact given forkability.

Ramp-up. Hours for a competent PHP engineer to use the API; days to build the wrapper, policy layer, and test corpus properly. The gating skill is not PHP but IDNA/domain-security literacy (bidi rules, homographs, IDNA2003 vs 2008 divergence) — plan for a review by someone with that background before this touches authentication or mail.

TPM recommendation. Do not adopt as a strategic dependency. Treat it as a candidate implementation detail inside an internally owned IdnEncoder abstraction, gated on a differential test suite against ext-intl/UTS#46. If ext-intl is universally available, the honest answer is that this package adds risk without adding capability; its only defensible niche is environments where ext-intl is unavailable and a pure-PHP, dependency-free codec is required. Confirm that constraint before spending further.