Punycode Laravel Package

Getting Started

Install via Composer: composer require true/punycode. Immediately use it to convert Unicode domain names (e.g., renangonçalves.com) to ASCII-compatible Punycode (xn--renangonalves-pgb.com) and vice versa. The most common first use case is normalizing user-input or external domain names before storing or comparing them—especially in multilingual applications where domains contain non-ASCII characters like accents or Cyrillic. Start by instantiating TrueBV\Punycode and calling encode()/decode() on individual domain names.

Implementation Patterns

• Domain sanitization in forms: Encode user-submitted international domain names before saving to the database to ensure consistent storage format (e.g., always store as Punycode).
• Email domain normalization: Normalize the domain part of email addresses during validation to ensure accurate lookups and prevent duplicates due to encoding differences.
• Redirect/url building: When generating redirects or constructing URLs with user-supplied domains, always encode them to avoid broken links or browser warnings about invalid characters.
• Testing isolation: Use this package in unit tests where ext-intl isn’t available (e.g., minimal CI runners) to ensure portable IDN behavior across environments—just ensure version compatibility (v2.1.0+ is RFC-compliant).

For cleaner Laravel integration, wrap instantiation in a singleton service (e.g., bind TrueBV\Punycode::class in a service provider) or create a dedicated helper class (e.g., app(Punycode::class)->encode($domain)), enabling easy swapping if migrating to symfony/polyfill-intl-idn.

Gotchas and Tips

• Archived & unmaintained: The package has been archived since 2016 and lacks PHP 8+ compatibility testing. Even minor Unicode updates (e.g., new IDN tables) may not be addressed. Strongly consider migrating to symfony/polyfill-intl-idn, which Laravel already uses internally.
• Case handling: Though v2.0.2 fixed casing, always normalize domains to lowercase before encoding/decoding—especially when doing comparisons or uniqueness checks—to avoid subtle failures (e.g., Xn--Renan... vs xn--renan...).
• No TLD validation: This library only handles the Bootstring encoding; it doesn’t enforce IDNA rules like label length (≤63) or total domain length (≤253). Always add your own validation post-encoding.
• Namespace quirk: Uses TrueBV (not True) due to PHP 7 reserved words—double-check imports and avoid use True; to prevent parse errors.
• Laravel-specific gotcha: Avoid direct usage in config files or bootstrappers—defer instantiation to runtime (via dependency injection) to prevent autoloading conflicts during migration or upgrade tasks.