This directory records the architecturally significant decisions behind
xphp — the choices that are expensive to reverse and that shape everything
built on top of them: how generics are implemented, what the compiler emits,
how the check gate and the PHPStan layer work, and the quality bar the
codebase holds itself to.
Each record states the problem, the options that were on the table, the option chosen and why, and the consequences (the good and the trade-offs). They are written after the fact, from the project's history, so they read as a map of why xphp is shaped the way it is — useful whether you're evaluating xphp, contributing to it, or just curious.
We use the MADR format. New significant decisions
should be added here as a new numbered file; copy
0000-adr-template.md to start.
| # | Decision | Status |
|---|---|---|
| 0001 | Monomorphization over type erasure | Accepted |
| 0002 | A build-time transpiler that emits plain PHP | Accepted |
| 0003 | RFC-aligned turbofish surface syntax | Accepted |
| 0004 | Marker interfaces for instanceof across specializations |
Accepted |
| 0005 | Nominal, erased bound checking | Accepted |
| 0006 | Bounded specialization with a hard depth cap | Accepted |
| 0007 | The xphp check validate-only gate |
Accepted |
| 0008 | The collect-or-throw diagnostic seam | Accepted |
| 0009 | PHPStan over the compiled output | Accepted |
| 0010 | Undeclared-type and arity validation | Accepted |
| 0011 | PHAR distribution via Humbug Box | Accepted |
| 0012 | The engineering quality bar | Accepted |
| 0013 | Typed constructor parameters on variant classes | Accepted |
| 0014 | Variance markers are class-level only | Accepted |
| 0015 | Variance markers on private properties | Accepted |
| 0016 | No special-cased value-equality bound (use ordinary generics) | Accepted |
| 0017 | Config-manifest, multi-root source resolution (xphp.json) |
Accepted |
| 0018 | Grounding a method-generic bound that references an enclosing class type parameter | Accepted |
| 0019 | Trait-imported members are not modeled in the type hierarchy | Accepted |
| 0020 | Diagnose and restructure self-reintroducing specialization (erased seam deferred) | Accepted |
| 0021 | xphp compile runs the check gate by default |
Accepted |
| 0022 | Bounds are upper-only (no supertype/lower bounds) | Accepted |