🗺️ ROADMAP: Compile a small PHP web application (living document)

[PurHur]

Living roadmap — edit this issue as phases complete. Link PRs here. Check boxes when milestones land on master.

Repository: PurHur/php-compiler
Target: Compile and run a small normal PHP web app (multi-file, forms, headers, optional AOT CGI/FastCGI deploy)—not just echo "Hello".

Issue index: #46–#868. Latest audit: 2026-05-23 batch 58 (#866–#868; expanded #72/#75; de-dupe #98/#174/#47; bisect #866/#867).

---

Phase model (north star)

Delivery order for the compile-a-small-web-app goal:

Phase	Name	GitHub labels (typical)	Milestone
0	Foundation	phase-0:Foundation	Local/Docker CI (#436 ✅, #501 ✅), phpc CLI + phpc init (#312 ✅, #632 ✅), Docker 22.04 (#73 ✅), docs (#245 ✅, #48, #727 phpc-json, #808 gate matrix), JIT compliance (#98, #717 ✅, #728 ✅), inventory gate (#765), self-host probe CI (#829, #830, #868)
1	Language	phase-2:language	OOP VM/JIT ✅ / native AOT link (#568 ✅, #752 ✅), typed props (#767, #169), includes (#54 ✅ VM, #475 JIT), ::class (#740), return types (#205)
2	Stdlib	phase-4:stdlib	Web builtins: headers, JSON, sessions (#64), htmlspecialchars (#124 ✅), path guards (#117, #704 ✅), regex (#93 ✅, #787 preg_quote ✅), redirects (#634 ✅), templates (#275 ✅ extract), rmdir (#759 ✅), unlink (#748 ✅), rename (#772 ✅), touch (#843 ✅)
3	Web AOT	phase-3:aot, phase-1:web-runtime	phpc build --project link ✅ (#752), execute (#764, #848–#849, #866–#867, #831–#834, #784, #807), deploy (#609 ✅, #718 ✅), runtime includes (#623 ✅), VM/AOT CGI (#50 ✅, #665 ✅), FastCGI (#173), debug CLI (#774, #792, #847, #75)
4	Polish	phase-5:reference-app	MiniWebApp VM ✅ (#539) → gates default-on (#641 ✅, #664 ✅, #674 ✅) → AOT execute+HTTP (#676, #747, #478, #833) → docs (#655 ✅, #445, #696, #753, #801) + stale-copy gates (#766, #802, #809) + smoke accuracy

Label prefixes (phase-2:language, etc.) are historical GitHub labels — they do not always match the phase number in this table.

---

Current phase

Active — Phase 4 Polish (AOT execute + HTTP): phpc build --project examples/003-MiniWebApp links on harness (#752 ✅, #812 ✅). Native .phpc/bin/app runs but returns empty stdout for home/hello routes — #764 (not a link failure).

Bisect ladder (smallest → largest):

1. Testing: isset_object_property_array.phpt AOT execute green (resolveAppName, #764) #848 — isset_object_property_array.phpt execute (resolveAppName)
2. Testing: aot phpt miniwebapp_render_home — resolveAppName + layout include (#764) #867 — miniwebapp_render_home.phpt (resolveAppName + one-hop layout include)
3. AOT: $_SERVER reads in runtime-included templates (layout.php SCRIPT_NAME, #764) #866 — $_SERVER read inside included layout.php
4. AOT: private method call chain before runtime include (layout_title_branch, #764) #846 + Testing: layout_title_branch.phpt — wire existing AOT fixture dir (#807, #784) #832 — private method call → layout partial chain
5. AOT: global user function called from class method (contact validation pattern, #764) #831 — global fn from class method (contact validation)
6. AOT: renderApiStatus json_encode + header in class method (#764) #849 — JSON api/status branch in class method
7. AOT: rejectContactInput early-return path in Router::dispatch (404 branch, #764) #834 — reject early-return path
8. AOT: MiniWebApp native binary CLI execute emits empty stdout (post-link) #764 — full 003 integration

Track	Issues
AOT execute (blocker)	#764, #848, #867, #866, #846, #831, #832, #834, #849, #784, #807
AOT execute tests	#785, #773, #775 / #791 ✅, #747 (canonical), #485 (umbrella)
Smoke / messaging	#809, #833, #766, #802, #801, #753
Test infra	#790, #454
DevEx / debug	#847 --list-units, #774, #746, #792, #808
Self-host (stretch)	#829, #830, #868, #816 ✅
HTTP / CGI AOT	#610 (canonical), #478 (umbrella), #682
CI hygiene	#765, #754, #737, #98

In parallel — Phase 1 Language: #205, #475, #145, #740, #169, #767, #195.

In parallel — Phase 0 Foundation: #98 JIT compliance; #113 host php-parser. Canonical CI: ./script/ci-local.sh / make test-docker — #394 GHA disabled.

Stretch (orthogonal): Self-host #540 ✅ — docs/bootstrap-selfhost.md.

---

Next 3 priorities

#	Issue	Why now
1	#848 → #867 → #866 → #846 + #832 + #831 + #834	Bisect ladder before full #764
2	#747 + #790 + #809 + #833 + #849 + #785	Shared CGI env; CLI + HTTP smoke after GET green
3	#766 + #753 + #801 + #802 + #808 + #847	Retire #568 copy; docs; --list-units debug

---

Current state (2026-05-23, batch 58)

Area	Status	Notes
VM execution	✅ Strong	Compliance + RealWorld PHPT + mini_web_app_*.phpt
phpc CLI	✅	serve, run, build, deploy, test, lint, init --profile miniwebapp, doctor --gates (#657 ✅)
001–004 examples	✅ VM/AOT (000–002, 004)	make examples-aot-smoke — 003 execute pending #764
003-MiniWebApp VM	✅	#539, PATH_INFO (#489), assets (#594)
003-MiniWebApp AOT link	✅	#752 ✅, #812 ✅
003-MiniWebApp AOT execute	❌	#764 — exit 0, 0 stdout bytes
AOT bisect fixtures	📋	#848 isset; #867 render_home; #866 $_SERVER in include; #846/#832 layout; #831, #834
JSON api/status AOT	📋	#849 class-method json_encode
Self-host probe CI	📋	#829 wire probe; #830 inventory; #868 cast_int/isset_array_offset link
phpc build --list-units	📋	#847 debug graph
Magic constants	✅	#85 ✅ umbrella
JIT compliance root fix	⚠️	#98 (not #174)
examples/README AOT row	⚠️ stale	#753 cites #568
examples-aot-smoke 003	⚠️ stale skip	#809 — script still skips #568
Bootstrap inventory CI	⚠️	#765, #830
Deploy shell smoke	✅	#718 ✅ (001/002)
touch() stdlib	✅	#843 ✅ closed

Verify on harness (no GHA):

make docker-build-22
./script/docker-ci-local.sh
php script/bootstrap-inventory.php --check   # #765 / #830
./script/ci-fast.sh
make web-smoke && make examples-web-smoke
# AOT bisect (#764):
./script/ci-local.sh --filter 'isset_object_property_array|miniwebapp_render_home'
cd examples/003-MiniWebApp && QUERY_STRING=route=home REQUEST_METHOD=GET ./.phpc/bin/app | wc -c
phpc doctor --gates

---

New issues (batch 58, #866–#868)

#	Title
#866	AOT: $_SERVER reads in runtime-included templates (layout.php SCRIPT_NAME, #764)
#867	Testing: aot phpt miniwebapp_render_home — resolveAppName + layout include (#764)
#868	Self-host: native link bootstrap-aot cast_int.php + isset_array_offset.php (Phase C)

Expanded (batch 58): #72 (closures), #75 (AOT debug symbols).

De-dupe comments (batch 58): #98 ↔ #174; closed #47 → local CI; #394 GHA off.

Prior batch (57, #846–#849)

#	Title
#846	AOT: private method call chain before runtime include (layout_title_branch, #764)
#847	DevEx: phpc build --project --list-units for AOT debug (#764)
#848	Testing: isset_object_property_array.phpt AOT execute green (resolveAppName, #764)
#849	AOT: renderApiStatus json_encode + header in class method (#764)

Expanded (batch 57): #829 (self-host probe in CI), #830 (inventory regen workflow).

De-dupe comments (batch 57): #98 ↔ #174; #485 → #747 canonical; #478 → #610 canonical.

Prior batch (56, #831–#834)

#	Title
#831	AOT: global user function called from class method (#764)
#832	Testing: layout_title_branch.phpt — wire fixture (#807, #784)
#833	Testing: examples-web-smoke.sh --aot 003 PATH_INFO curls
#834	AOT: rejectContactInput early-return path (#764)

---

CI de-duplication (canonical)

Topic	Canonical issue	Notes
Full local gate	./script/ci-local.sh, make test-docker, ./script/docker-ci-local.sh	#245 ✅ docs
Fast iteration	./script/ci-fast.sh, make test-fast	#436 ✅
JIT skipped with LLVM 9	#98, #250 ✅, #717 ✅, #728 ✅	Not #174
LLVM 14+ upgrade	#174	After #98 green on LLVM 9
GHA workflows	#394 ✅ closed	Do not add .github/workflows/* for CI
MiniWebApp AOT execute	#764, #848–#849, #831–#834	Bisect then integrate
MiniWebApp AOT execute tests	#747	#485 umbrella only
ServeAotTest MiniWebApp	#610	#478 umbrella only
Self-host compile probe	#816 ✅ script, #829 CI wire, #830 doc commit, #868 cast/isset link	Stretch Phase 0
AOT debug graph	#847 --list-units	#746 doctor probe
Stale #568 messaging	#766, #792, #802, #801, #809, #753	Scripts + docs

---

How to update

1. Check phase boxes when child issues close.
2. Update Current state after each audit.
3. Comment release notes when a phase completes.
4. Close duplicates; link blockers in Reference app: MiniWebApp runtime green (lint 0, VM serve, routes) #539, Testing: MiniWebApp AOT unskip matrix after #568 (orchestrate #454 #485 #478 #610) #676, AOT: MiniWebApp native binary CLI execute emits empty stdout (post-link) #764.

Child issues: #46–#868.

[PurHur]

Roadmap refreshed after source audit: full suite 341 tests (0 failures), VM compliance 133/133 pass, JIT compliance 133/133 skipped (#98). Added issues #96–#107 for switch, strpos, ??, globals, extends, PHPT web sections, writable superglobals, filter_var, date/time, phpc.json, array assign.

[PurHur]

Roadmap refreshed after source audit (2026-05-18): added issues #113–#126 (host PHP 8.2 parser, ternary/break/append, path stdlib, OB, getenv, require_once, PATH_INFO, redirects, random_bytes, htmlspecialchars JIT, pow, Makefile smoke). Test baseline: 349 tests, 165 skipped, 0 failures via script/ci-local.sh.

[PurHur]

Audit 2026-05-18 (batch 3): ci-local.sh green (366 tests, 0 failures). Fixed ** via TypeReconstructor + patch. Added implementation issues #135–#160. Closed items reflected: #88 serve, #121 PATH_INFO, #125 power, #126 Makefile.

[PurHur]

Audit batch 5 (2026-05-18)

Source review highlights:

• lib/Compiler.php::compileStmt() only handles Jump, JumpIf, Switch_ — no loop statements. Created Language: while, do-while, and for loops (CFG → VM → JIT) #192 (critical blocker for any non-trivial app).
• compileParam() rejects defaults and variadics — Language: Default parameter values and optional arguments #196, Language: Variadic functions (...$args) and func_get_args() #197.
• AOT superglobals still baked via lib/JIT/SuperglobalInit.php — tracked as AOT: Per-request superglobal refresh in native binary (not compile-time bake) #201 (AOT slice of Web: Runtime-populated superglobals for JIT and AOT (per-request $_GET/$_POST) #49).
• Docker: ircmaxell/php-compiler:* images not pullable; harness must use Infrastructure: Publish Docker dev image and document container CI workflow #202 published image workflow.
• Added 22 issues (Language: while, do-while, and for loops (CFG → VM → JIT) #192–DevEx: phpc serve --aot runs precompiled CGI binary per project #213) with acceptance criteria and file pointers.

Next suggested work (P0): #192 → #53 → #49/#201 → #54 → #67/#210.

[PurHur]

Roadmap audit batch 6 (2026-05-19)

Updated: current phase (Phase 2), next 3 priorities (#192 → #53 → #99), closed-issue sync (#47, #193, #196, #200, #201, #203, #213, …), harness/Docker notes.

Created: #234 serve tests in Docker CI, #235 HTTPS/HTTP_HOST, #236 phpc lint diagnostics, #237 LLVM 9 in dev image.

Expanded: #157 param coercion, #158 mb_strlen UTF-8 semantics.

De-duped: comments on #98 / #174 / #73 — local ci-local.sh + docker-ci-local.sh are canonical; GHA is optional mirror.

Next backlog pass: close #158 if byte-length is accepted; merge #73 into #202/#237 when make test-docker is fully green.

[PurHur]

Backlog audit batch 7 (2026-05-19): synced closed #236/#237, created #243–#246, expanded #53/#67, de-duped #98/#174/#73/#202 comments.

[PurHur]

Backlog audit batch 8 (2026-05-19)

ROADMAP body updated: current phase, next 3 priorities, batch 8 state table, CI de-dupe matrix.

Created: #247 (AOT execute smoke 002-StaticWeb), #248 (ServeTest POST), #249 (make test → test-docker), #250 (ci-local JIT skip guard).

Expanded: #54 (include JIT/AOT hints), #114 (ternary hints).

De-duped: comments on #174 / #202 / #73 — local ci-local.sh + Docker canonical; #98 not #174 for JIT skips.

Next implementer focus: #192 → #53 → #99 (unchanged P0 language path).