🗺️ 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–#881. Latest audit: 2026-05-23 batch 59 (#878–#881; expanded #48/#113; de-dupe #98/#174).

---

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 ✅), addslashes (#874)
3	Web AOT	phase-3:aot, phase-1:web-runtime	phpc build --project link ✅ (#752), execute (#764, bisect #878–#880, #867, #866, #846–#849, #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, #881) → 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; updated batch 59):

Step	Issue	Fixture / probe	Status
1	#848	isset_object_property_array.phpt	✅ closed
2	#806 / #783	require_return_config.phpt	✅ closed
3	#878	nested_include_two_tier.phpt	📋 open
4	#867	miniwebapp_render_home.phpt (add tree)	📋 open
5	#866	$_SERVER in included layout.php	📋 open
6	#846 + #832	private method → layout partial chain	📋 open
7	#831	global fn from class method (contact)	📋 open
8	#849	JSON api/status in class method	📋 open
9	#834	reject early-return path	📋 open
10	#764	full 003 integration	❌ blocker

DevEx (batch 59): #879 script/miniwebapp-aot-bisect.sh, #880 @group miniwebapp-bisect, #881 retarget examples-aot-smoke.sh 003 slice.

Track	Issues
AOT execute (blocker)	#764, #878, #867, #866, #846, #831, #832, #834, #849, #784, #807
AOT execute tests	#785, #773, #775 / #791 ✅, #747 (canonical), #485 (umbrella)
Smoke / messaging	#881, #809, #833, #766, #802, #801, #753
Test infra	#790, #454, #880
DevEx / debug	#879, #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	#867 + #878 + #866	Middle bisect after closed #848/#806 — before layout branches
2	#879 + #880 + #747 + #790	Ordered local bisect + shared CGI env for CLI smoke
3	#881 + #766 + #753 + #801	Retire #568 copy in scripts/docs; accurate examples README

---

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

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/#806 ✅; #878/#867 open
JSON api/status AOT	📋	#849 class-method json_encode
Bisect DevEx	📋	#879 script, #880 PHPUnit group
Self-host probe CI	📋	#829 wire probe; #830 inventory; #868 cast/isset link
phpc build --list-units	📋	#847 debug graph
JIT compliance root fix	⚠️	#98 (not #174)
examples/README AOT row	⚠️ stale	#753 cites #568
examples-aot-smoke 003	⚠️ stale skip	#881 — script still skips #568
Bootstrap inventory CI	⚠️	#765, #830
Deploy shell smoke	✅	#718 ✅ (001/002)

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|nested_include_two_tier'
cd examples/003-MiniWebApp && QUERY_STRING=route=home REQUEST_METHOD=GET ./.phpc/bin/app | wc -c
phpc doctor --gates
# When #879 lands:
MINIWEBAPP_AOT_BISECT_GATE=1 ./script/miniwebapp-aot-bisect.sh

---

New issues (batch 59, #878–#881)

#	Title
#878	Testing: nested_include_two_tier.phpt AOT execute (layout scope, #764)
#879	DevEx: script/miniwebapp-aot-bisect.sh — ordered #764 fixture runner
#880	Testing: PHPUnit @group miniwebapp-bisect for ordered #764 AOT fixtures
#881	CI: examples-aot-smoke.sh 003 — link probe + execute bytes (#809, #764)

Expanded (batch 59): #48 (README north-star table), #113 (php-parser patch workflow).

De-dupe comments (batch 59): #98 ↔ #174; #881 supersedes stale #568 skip in examples-aot-smoke.sh (with #809 policy).

Prior 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).

---

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, #878–#880, #867–#866	Bisect then integrate
MiniWebApp AOT execute tests	#747	#485 umbrella only
ServeAotTest MiniWebApp	#610	#478 umbrella only
examples-aot-smoke 003	#881 (impl), #809 (policy)	Link ✅; execute #764
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, #881, #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–#881.

[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).