4.0 — breaking modernization

[mmucklo]

🎨 Visual review companion → — the same content as colorful before/after diagrams and charts, at high / mid / low zoom.

4.0 is a breaking-modernization release. Same parser, tighter surface: the API is modernized and the internals are typed, but a valid address parses identically — output is byte-identical, verified by the full spec corpus.

✅ 0 behavior changes	✅ 14/14 CI checks green	✅ net −39 source LOC	✅ 109 tests / 7.2k assertions

---

High level — what's merging

Everything sorts into four buckets. Only the first two touch callers.

flowchart LR
    B["🔴 BREAKING · 2<br/>7 setters removed<br/>validators → private"]:::brk
    D["🟠 DEPRECATED · 2<br/>parse()<br/>getInstance()"]:::dep
    I["🔵 INTERNAL · 3<br/>ParserState enum<br/>snake → camelCase<br/>readonly config"]:::int
    X["🟢 DOCS · 3<br/>UPGRADE guide<br/>ROADMAP<br/>CHANGELOG"]:::saf
    B --> R
    D --> R
    I --> R
    X --> R
    R["v4.0<br/>0 behavior changes<br/>net −39 LOC"]:::rel
    classDef brk fill:#f8e3e2,stroke:#cf3b3b,color:#7a1f1f
    classDef dep fill:#f6ecd6,stroke:#a9721a,color:#5a3d0e
    classDef int fill:#e2ecfb,stroke:#2f6bd6,color:#1a3c73
    classDef saf fill:#e0f0e7,stroke:#2c8253,color:#164a2e
    classDef rel fill:#e7e4fb,stroke:#5b4fe3,color:#2c2470,stroke-width:2px

Loading

Mid level — the public surface, before → after

API	v3.9	v4.0	Impact
parseSingle / parseMultiple / parseStream	✅	✅ primary	none
ParseOptions::withX() builders	✅	✅ unchanged	none
parse(string, bool $multiple)	✅	⚠️ @deprecated (→5.0)	soft
getInstance()	✅	⚠️ @deprecated (→5.0)	soft
7× ParseOptions::setX()	✅	🔴 removed	breaking
validateLocalPart() / validateDomainName()	protected	🔴 private	breaking
STATE_* (12 consts)	ints	🔵 enum ParserState: int	internal
ParseOptions state fields	private + setters	🟢 public readonly	additive

The two breaking rows are the whole upgrade. Migration is mechanical — full table in the new v3.x → v4.0 section of UPGRADE.md:

// setters → withX() (reassign; withX returns a new instance)
$o->setBannedChars($a);      →   $o = $o->withBannedChars($a);
// deprecated methods → typed API
$parser->parse($in, true);   →   $parser->parseMultiple($in);
Parse::getInstance();        →   new Parse(null, ParseOptions::rfc5322());

Low level — the numbers GitHub's diff buries

GitHub shows +787 / −722 (1,509 lines touched) — it reads like a rewrite. It isn't:

Metric	Value	Note
GitHub churn	+787 / −722	moves & renames counted on both sides
Net source footprint	−39 LOC	src/ 3,035 → 2,996 — the release removes more than it adds
— snake_case → camelCase	~305 sites	pure rename (output keys unchanged)
— STATE_* → ParserState::	75 sites	pure rename
— setters removed	7 methods	deletion
Parsing-logic changes	0	the diff is find-and-replace + removal, not new behavior

Per-file: Parse.php 792 · ParseContext.php 164 · ParseTest.php 162 · ParseOptions.php 106 · ParserState.php 37 (new) · PropertyTest.php 10.

Proof it's safe

• Behavior: the 235-case testspec.yml corpus asserts exact output; the runner was re-pointed at parseMultiple()->toArray() and every case still matches → byte-identical.
• CI (all green): tests on PHP 8.1–8.6, PHPStan L8, Psalm, CS Fixer, Coverage, and the Benchmarks (vs base) job — the ParserState enum lands within ±2% of master, well under the 1.5× gate (enum === is identity comparison).
• Upgrade cost: if you use the typed methods + withX(), nothing changes; otherwise ~2 minutes of find-and-replace.

Notable / worth a look

• Test suite now validates the typed path, not the deprecated parse() — a strict improvement that shipped for free with the deprecation.
• parse() is a shim over a new private parseInternal() core — parseSingle/parseMultiple/parseStream call the core directly, so the deprecated method has no internal callers.
• Immutability is now complete: every ParseOptions property is readonly; you can't keep the mutating setters and readonly, which is why removal (not just deprecation) is the right call.
• Scope is deliberately lean — DNS/MX, confusable-target, and RFC 6854 groups are deferred to 4.1–4.3 (additive), and the deprecation removals to 5.0. See ROADMAP.md (incl. the new North Star on error identity vs. presentation).

Draft until the UPGRADE guide gets a final read and a 4.0.0-beta1 tag is cut to soak.

[codecov]

Codecov Report

❌ Patch coverage is 94.07216% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.42%. Comparing base (6d4a628) to head (4cf4348).

Files with missing lines	Patch %	Lines
src/Parse.php	93.40%	23 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master      #72      +/-   ##
============================================
+ Coverage     95.84%   96.42%   +0.57%     
+ Complexity      446      438       -8     
============================================
  Files             7        7              
  Lines          1108     1091      -17     
============================================
- Hits           1062     1052      -10     
+ Misses           46       39       -7     

Files with missing lines	Coverage Δ
src/ParseContext.php	100.00% <100.00%> (ø)
src/ParseOptions.php	100.00% <100.00%> (+0.96%)	⬆️
src/Parse.php	94.84% <93.40%> (+0.65%)	⬆️

🚀 New features to boost your workflow:

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