v3.1: immutable ParseOptions, typed output, error codes, new validation rules

[mmucklo]

Summary

Completes the v3.1 roadmap. All additions are non-breaking for v3.0 callers; the one hard cutover is that the 15 ParseOptions rule properties are now readonly (direct assignment throws Error — use the new fluent withX() builders). Existing deprecated setters, factory presets, and the array-based parse() method continue to work unchanged.

What's new

Structured error codes

• ParseErrorCode backed enum with 46 cases grouped by category (structural, character-class, dot placement, local-part content, quoted-string, domain, IP literal, length, display-name). Stable string backing values.
• invalid_reason_code: ?ParseErrorCode on every parsed-address entry, populated alongside the existing invalid_reason string.

Typed output

• ParsedEmailAddress — immutable value object with readonly properties for every per-address field.
• ParseResult — immutable container for multi-address results.
• Parse::parseSingle(string, string): ParsedEmailAddress — typed single-address entry point.
• Parse::parseMultiple(string, string): ParseResult — typed multi-address entry point.

Immutable config

• The 15 boolean rule properties on ParseOptions are readonly via PHP 8.1 constructor promotion.
• 19 withX() fluent builders (15 rules + 4 state fields) that return new immutable instances with a single field replaced.
• The 4 state fields (bannedChars, separators, useWhitespaceAsSeparator, lengthLimits) remain mutable via @deprecated setters; they will become readonly in v4.0.

New validation rules

• validateDisplayNamePhrase — enforce RFC 5322 §3.2.5 phrase syntax (atext + WSP only) on unquoted display names. New error code: InvalidDisplayNamePhrase.
• strictIdna — apply full IDNA2008 conformance on U-label domains (IDNA_USE_STD3_RULES | IDNA_CHECK_BIDI | IDNA_CHECK_CONTEXTJ | IDNA_NONTRANSITIONAL_TO_ASCII) per RFC 5891/5892/5893. Enabled by default in ParseOptions::rfc6531().

Migration for v3.0 users

Only one thing can break existing code: direct assignment to rule properties.

// v3.0
$options = ParseOptions::rfc5322();
$options->requireFqdn = false;  // worked

// v3.1
$options = ParseOptions::rfc5322()->withRequireFqdn(false);  // returns new instance

Factory presets, the deprecated setters (setBannedChars etc.), and parse() are all unchanged. See UPGRADE.md for full migration notes.

Test plan

• composer ci passes (cs:check, PHPStan level 6, 14 tests / 265 assertions)
• Existing 224 YAML test cases pass unchanged via alignReasonCode() reconciliation in the test harness
• New tests cover: typed value objects, fluent builders, error code assertions, display-name phrase validation, IDNA strict-mode validation, readonly-property rejection

Docs updated

• CHANGELOG.md — v3.1.0 entry with Added / Changed / Deprecated sections
• UPGRADE.md — v3.0 → v3.1 section covering the readonly cutover and additive changes
• ROADMAP.md — v3.1 items marked [x] with exact counts
• README.md — typed output example in Basic Usage; withX() builders in Customizing Rules; new rule properties in the reference table

[codecov]

Codecov Report

❌ Patch coverage is 91.33858% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.59%. Comparing base (83669dd) to head (9578072).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Parse.php	75.28%	22 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             master      #50       +/-   ##
=============================================
+ Coverage     78.03%   88.59%   +10.55%     
- Complexity      287      323       +36     
=============================================
  Files             3        5        +2     
  Lines           683      833      +150     
=============================================
+ Hits            533      738      +205     
+ Misses          150       95       -55     

Files with missing lines	Coverage Δ
src/ParseOptions.php	100.00% <100.00%> (+19.82%)	⬆️
src/ParseResult.php	100.00% <100.00%> (ø)
src/ParsedEmailAddress.php	100.00% <100.00%> (ø)
src/Parse.php	84.80% <75.28%> (+7.39%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.