v5.0.0-rc1

The first release candidate for IDNA Convert v5 is ready for testing.

This major release improves Unicode normalization and IDNA validation, adds public validation APIs, and strengthens automated conformance checks. Some inputs accepted by earlier versions are now rejected or produce different normalized results.

This is a prerelease. Please test it with your application before upgrading production installations.

Highlights

• Unicode 18.0 NFC normalization and non-transitional UTS #46 mapping for IDNA2008.
• Unicode 3.2 NFKC normalization for IDNA2003.
• IDNA2008 contextual and bidirectional validation, including ContextJ and ContextO rules.
• Validation of canonical A-labels, hyphen placement, and DNS label and domain lengths.
• Public InputValidator and IdnaValidator APIs.
• Expanded regression tests and reproducible Unicode data generation.

Breaking changes

• Stricter validation rejects malformed or non-canonical A-labels, invalid contextual or bidirectional sequences, and prohibited characters.
• Empty labels and labels that become empty after mapping are rejected. DNS length validation is enabled by default and also rejects a trailing empty root label.
• Normalization and mapping changes can alter conversion results. IDNA2008 preserves ß and final sigma.
• Native API types and changes to the PunycodeInterface constructor require updates to some custom implementations and subclasses.
• UCS-4 conversion inputs now require consecutive, zero-based lists of integer Unicode scalar values where validation applies.
• The protected AbstractPunycode::$unicodeTransCoder property has been replaced by $ucs4Codec.

See UPGRADING.md for details, configuration options, and migration guidance.

The minimum PHP version remains 8.1.

Verification

• 476 tests with 2,518 assertions.
• 185,815 Unicode normalization assertions.
• All 6,396 cases in the pinned Unicode 18.0 ToASCII corpus checked without omissions:
  • 398 exact conversion results.
  • 5,836 rejections required by the corpus.
  • 160 additional rejections under the strict IDNA2008 profile.
  • 2 malformed UTF-8 inputs rejected.
• PHPStan level 10, coding-standard checks, mutation testing, and consumer installation checks.

The ToASCII checks cover non-transitional UTS #46 mapping followed by strict IDNA2008 validation. They do not establish full UTS #46 conformance or conformance of the separate ToUnicode decoder.

Try the release candidate

composer require algo26-matthias/idna-convert:5.0.0-rc1

We particularly welcome testing with existing domain collections, URLs, email addresses, and custom implementations of the library's interfaces. Check for changed conversion results and newly raised exceptions, especially when comparing or storing normalized domain names.

Please report unexpected behavior through GitHub Issues, including the input, expected and actual behavior, PHP version, and converter options.

Version support

Support periods begin with v5.0.0 stable, not this release candidate:

• v5: active development and maintenance.
• v4: security fixes and important backward-compatible bug fixes for 12 months.
• v3: critical security fixes, where a backport is feasible, for 3 months.

See SECURITY.md for the maintenance policy.