v3.3: serialization, canonical form, local-part normalizer

[mmucklo]

Summary

Delivers the v3.3 roadmap (ecosystem bridges deferred per direction). Fully additive — no breaking changes, no behavior changes for v3.2 callers. Also updates README examples to use the typed parseSingle() API throughout.

What's new

Serialization on value objects

• ParsedEmailAddress::toArray() — round-trips to the legacy parse() array shape exactly (assertable via assertSame).
• ParsedEmailAddress::toJson(int $flags = 0) — wraps json_encode with JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES. ParseErrorCode serializes to its backing string value.
• ParseResult::toArray() + toJson() — same pattern for the multi-address container.

Stringable

ParsedEmailAddress now implements \Stringable. (string) $parsed returns simpleAddress for valid addresses, empty string otherwise.

Canonical RFC 5322 display form

ParsedEmailAddress::canonical() applies minimal quoting per §3.2.4 (local-part) and §3.2.5 (phrase). Drops unnecessary quotes from the input and adds them only when required:

"John Doe" <j@example.com>        → John Doe <j@example.com>        (name quotes unnecessary)
"John Q. Public" <j@example.com>  → "John Q. Public" <j@example.com> (period requires quoting)
"with space"@example.com          → "with space"@example.com         (local-part quoting required)

Local-part normalizer callback

New opt-in hook on ParseOptions:

$opts = ParseOptions::rfc5322()->withLocalPartNormalizer(
    fn (string $local, string $domain): string =>
        $domain === 'gmail.com'
            ? strtolower(str_replace('.', '', strtok($local, '+')))
            : $local,
);
$parser = new Parse(null, $opts);
$result = $parser->parseSingle('John.Doe+spam@gmail.com');
$result->localPartParsed;    // 'johndoe'
$result->simpleAddress;      // 'johndoe@gmail.com'
$result->originalAddress;    // 'John.Doe+spam@gmail.com' — verbatim preserved

The callback runs after local-part validation succeeds; it never sees invalid input. Returning the input unchanged is a safe no-op. Gated behind a property, so normalization is opt-in per parser instance.

Docs

• README: nine parse($email, false) call sites rewritten to use parseSingle() / typed property access. One legacy example preserved under "Other Examples" to document the array shape, with a note pointing new code at the typed API.
• Basic Usage section gains a v3.3 serialization + canonical block.
• Rule-properties table gets localPartNormalizer.
• CHANGELOG [3.3.0] entry.
• ROADMAP v3.3 items flipped to [x]. Ecosystem bridges (Symfony, Laravel, PSR-14) marked deferred.
• UPGRADE v3.2 → v3.3 section.

Test plan

• composer ci passes (cs:check, PHPStan with --memory-limit=512M, 60 tests / 472 assertions)
• toArray() round-trip verified with assertSame against the legacy parse() output
• toJson() decodes cleanly; ParseErrorCode serializes to its backing string ('multiple_opening_angle', etc.)
• Stringable returns simpleAddress for valid addresses, empty string for invalid
• canonical() covered: addr-spec only, atext name (no quotes), unnecessary-quotes stripping, required-quotes retention for periods, quoted local-part with space, empty result for invalid
• Normalizer covered: Gmail-style rewrite (dots + +tag), domain gating (pass-through for non-gmail), not invoked on invalid addresses, withLocalPartNormalizer(null) clears a previously-set callback

What's left (not in this PR)

Deferred ecosystem bridges (Symfony Constraint, Laravel rule, PSR-14 events) — listed but unchecked in ROADMAP; they'd be separate packages anyway.

v4.0 now trimmed to just the genuinely breaking items: DNS/MX validation callback and RFC 6854 group syntax.

[codecov]

Codecov Report

❌ Patch coverage is 98.61111% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 90.02%. Comparing base (77d4d20) to head (f37b437).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Parse.php	87.50%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master      #52      +/-   ##
============================================
+ Coverage     89.34%   90.02%   +0.67%     
- Complexity      357      380      +23     
============================================
  Files             6        6              
  Lines           910      982      +72     
============================================
+ Hits            813      884      +71     
- Misses           97       98       +1     

Files with missing lines	Coverage Δ
src/ParseOptions.php	98.93% <100.00%> (+0.04%)	⬆️
src/ParseResult.php	100.00% <100.00%> (ø)
src/ParsedEmailAddress.php	100.00% <100.00%> (ø)
src/Parse.php	85.98% <87.50%> (+0.01%)	⬆️

🚀 New features to boost your workflow:

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