Compiler: lib/Compiler.php is one 62,407-line class with 1,268 methods and 923 fields — trait-based decomposition behind an opcode-md5 corpus gate (lib/Compiler.php, lib/Lint/LintCompiler.php)

[PurHur]

Category

Foundation: · maintainability (87 PRs/day land in this file) · child of #36188

Problem

lib/Compiler.php: 62,407 lines, one class, 1,268 methods (902 private / 344 protected / 21 public), 923 property declarations, 3,599 instanceof (3,185 on Op\…), 10 switch. Dispatch is compileOp (:13352) → compileExpr (:14299, a switch (get_class($expr)) with 43 arms) / compileStmt (:13423) / compileTerminal (:44722). 102 PHP builtin names are hardcoded inside lowering (array_merge 39x, array_replace_recursive 32x, var_export 23x, preg_replace_callback_array 13x …). compileCallArgSends alone is 6,431 lines (the super-quadratic compile child of #36188 covers its algorithm). The ~40 mutable fields shared by the 902 private methods (coalesceResultSlots, ternaryMergeVarSlots, activeCatchVarSlotsByName, …) are why nobody can move code safely, and why merge conflicts in this file are constant at fleet velocity. The one subclass, Lint\LintCompiler, overrides five protected methods (lib/Lint/LintCompiler.php:29,39,53,79,90) — a constraint any split must keep.

PHP implementation target

Traits, not collaborator objects: trait methods keep $this, visibility and overridability, so LintCompiler keeps working. One PR per step, each gated by Printer::print md5 equality over a fixed ≥ 100-file corpus (zero opcode diff), in this order:

1. Compiler\Concern\CompileTimeFold — the ~15 tryFold* methods (all private).
2. Compiler\Concern\ParameterAsserts — the 9 assertNo*/assertVariadic* methods (:999-1130).
3. Compiler\Concern\CoalesceAndNullsafe — compileCoalesce (:15949) + nullsafe prelude machinery.
4. Compiler\Concern\InlineCallArgProducers — the ~60 inline*/sibling*/hoisted*/rewire*/slotFor* methods (~18,000 lines) — the staging ground for the def-use rewrite (super-quadratic compile child of Compiler audit (Sep 2026): fast generated code, Zend-shaped runtime, incremental builds, truthful gates — automation tracker #36188).
5. Compiler\Concern\ClassLowering — compileClassBody (:9308), compileInterface, compileTrait, compileClassLike; keep the five LintCompiler-overridden methods on the class.
6. Only below ~15k lines: convert the 43 compileExpr arms into per-op classes behind a LoweringRegistry (the switch is already an exact dispatch table).
   Do not start with per-op classes — moving state before moving code is where behaviour changes leak in. Add script/opcode-corpus-md5.sh (the gate) first; it doubles as the safety net for the Simplifier-default and operand-index children of Compiler audit (Sep 2026): fast generated code, Zend-shaped runtime, incremental builds, truthful gates — automation tracker #36188.

Done when

• script/opcode-corpus-md5.sh committed and run in check-generated-docs.sh's fast tier
• Steps 1–5 merged with zero opcode diff; lib/Compiler.php < 20,000 lines; LintCompiler tests unchanged
• CONTRIBUTING: new lowering code goes into a Concern, never into Compiler.php directly

[PurHur]

claim: implementer-worker-lane-c — starting this run (lane C tie-break #36230 % 3 == 2; lane overflow: #36143–#36148 / #36142 children closed; #36353 claimed <48h; targeting opcode-corpus-md5 gate + CompileTimeFold trait slice)

[PurHur]

Merged #36363 — first slice of #36230: opcode dump corpus md5 gate.

• script/opcode-corpus-md5.php fingerprints Printer::print for 149 test/differential/cases/*.php
• baseline: test/differential/OPCODE-CORPUS.md5
• wired into check-generated-docs.sh + empty-corpus honesty probe
• verified: opcode-corpus-md5 --check OK (aggregate 153b63787b0cb64141e82293ce5dc90e); check-generated-docs.sh OK

Next slice: extract Compiler\Concern\CompileTimeFold (tryFold* cluster) behind this gate (spine/inventory require_once for the new trait file).

[PurHur]

claim: implementer-worker-lane-c — continuing this run: extract Compiler\Concern\CompileTimeFold (tryFold* cluster) behind opcode-corpus-md5 gate (next slice after #36363)

[PurHur]

Merged #36365 — Compiler\Concern\CompileTimeFold extracted from lib/Compiler.php (~1481 lines; Compiler 62281→60804).

• opcode-corpus-md5 aggregate unchanged vs pre-extract master (07351f2fb54f307acff81169f63b5f75); baseline refreshed for post-gate corpus adds
• spine + bootstrap-inventory include the new trait file (8080)
• aot-smoke 9/9; VM differential 149/151 (same two master diffs)

Next slice: Compiler\Concern\ParameterAsserts (assertNo*/assertVariadic* cluster).

[PurHur]

claim: implementer-worker-lane-c — continuing this run: next Compiler Concern extract behind opcode-corpus-md5 gate (after CompileTimeFold #36365)

[PurHur]

Merged #36369 — Compiler\Concern\ParameterAsserts extracted from lib/Compiler.php (~180 lines; also deduped two accidental spine require_once lines).

Verification:

• opcode-corpus-md5 --check → OK (152 files; 0 changed dumps from extract)
• aot-smoke → 9/9
• make north-star5-verify-fast → OK (8081/8081)

Next slice: Compiler\Concern\CoalesceAndNullsafe (compileCoalesce + nullsafe prelude).

[PurHur]

claim: implementer-worker-lane-c — continuing this run: extract Compiler\Concern\CoalesceAndNullsafe (step 3 after ParameterAsserts #36369)

[PurHur]

Merged #36373 — Compiler\Concern\CoalesceAndNullsafe extracted from lib/Compiler.php (~1427 method lines; Compiler 60624→59188).

Also spine-requires lib/Config.php so inventory regen after Doctor::env (#36368) stays 8083/8083.

Verification:

• opcode-corpus-md5 --check → OK (152 files, aggregate unchanged d6bf5603…)
• spine coverage / bootstrap-inventory → OK 8083/8083
• make north-star5-verify-fast → OK
• ./script/aot-smoke.sh → 9/9 + size gate OK

Next slice: step 4 InlineCallArgProducers (~18k lines) or keep carving smaller contiguous clusters.