Web: MiniWebApp routing pattern (front controller + path dispatch)

[PurHur]

Problem

#67 defines the reference app. This issue specifies the routing architecture so implementers know the target before writing 003-MiniWebApp.

Goal

Document and implement a minimal front-controller pattern:

examples/003-MiniWebApp/
  public/index.php      # front controller (only web-exposed PHP)
  src/Router.php        # dispatch table (functions or array routes)
  templates/layout.php  # shared HTML shell
  templates/home.php
  templates/hello.php
  templates/contact.php
  assets/style.css      # static (served by DevServer **#150** ✅)

Routes (minimum)

Method	Path	Behavior
GET	/	Home template
GET	/hello?name=	Greet (#1 parity)
POST	/contact	Form validate + thank-you (#248, #259)
GET	/api/status	JSON (#61)

Implementation hints

1. Entry: public/index.php reads $_SERVER['REQUEST_URI'] or PATH_INFO (Web: PATH_INFO and front-controller routing ($_SERVER) #121 ✅, integration Testing: ServeTest PATH_INFO front-controller dispatch #276) — avoid hard-coded example.php (Web: DevServer default document (index.php) instead of hard-coded example.php #254).
2. Router: simple match on method + path prefix (use ?: when Language: Ternary operator (?:) in compiler pipeline #114 lands; switch when JIT: Implement switch/case opcodes (TYPE_CASE) — VM works, JIT stubbed #96/Compiler: Register JIT-stubbed switch in UnsupportedRegistry (lint parity) #288 ready).
3. Templates: require layout with include partials (Language: include/require in JIT and AOT (multi-file applications) #54); variables via locals or Stdlib: extract() and compact() for PHP template includes #275 extract() when available.
4. Lint-first: land skeleton with phpc lint --all (DevEx: phpc lint --all for project trees (MiniWebApp blocker report) #286) before JIT/AOT; track blockers in Reference: MiniWebApp lint-first skeleton (examples/003-MiniWebApp) #246.
5. Serve matrix: document VM phpc serve, optional JIT (Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207), AOT phpc build + phpc serve --aot (DevEx: phpc serve --aot runs precompiled CGI binary per project #213 ✅), production CGI (Web: CGI/1.1 request driver (stdin/stdout, env, Status line) #50).

Acceptance criteria

• examples/003-MiniWebApp/ exists with structure above
• All routes return expected bodies via phpc serve curl recipes in README
• Routes covered by PHPT/web tests in Testing: Expand web PHPT suite (redirects, empty input, POST merge) #68
• make test-docker green (serve tests when loopback allowed)

Verification (local / Docker only)

make docker-build-22
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev ./script/ci-local.sh
./script/examples-web-smoke.sh   # after **#298** — extend for 003

Dependencies

• Reference app: examples/003-MiniWebApp (router, templates, forms) #67 reference app umbrella
• Language: while, do-while, and for loops (CFG → VM → JIT) #192 / Language: Implement foreach (CFG → VM → JIT) #53 loops & iteration for route tables
• Language: include/require in JIT and AOT (multi-file applications) #54 include/require, Language: Magic constants __DIR__, __FILE__, __LINE__ for multi-file apps #85 __DIR__
• Stdlib: json_encode and json_decode for API endpoints #61 JSON, JIT: htmlspecialchars() native fast path (ENT_QUOTES, UTF-8) #124 htmlspecialchars
• Web: Runtime-populated superglobals for JIT and AOT (per-request $_GET/$_POST) #49 runtime superglobals, Web: DevServer default document (index.php) instead of hard-coded example.php #254 index.php default
• Web: $_SERVER['SCRIPT_FILENAME'] for CGI routing and includes #302 SCRIPT_FILENAME, Web: $_SERVER['SERVER_PROTOCOL'] from HTTP request line #306 SERVER_PROTOCOL

Links

• examples/001-SimpleWeb/, lib/Web/Superglobals.php (derivePathInfo)
• 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 ROADMAP north-star Phase 4 (Polish)

[PurHur]

Implementation hints (backlog batch 16)

File map

Area	Files
Dev server routing	lib/Web/DevServer.php (handleConnection, PATH_INFO split ~L95–122)
Superglobals	lib/Web/Superglobals.php, lib/AOT/runtime/superglobals_refresh.c
PATH_INFO tests	#276 test/real/ServeTest.php
Default document	#254 index.php before example.php fallback
Lint scaffold	#246 examples/003-MiniWebApp/public/index.php

Router sketch (until #53 foreach)

Prefer switch on $_GET['route'] ?? 'home' (#96 JIT stubbed — use if/elseif chain in lint-first scaffold, or accept VM-only):

$route = $_GET['route'] ?? 'home';
if ($route === 'home') { require __DIR__.'/../templates/home.php'; }
elseif ($route === 'api/status') { header('Content-Type: application/json'); echo json_encode(['ok' => true]); }
else { http_response_code(404); }

PATH_INFO mode (after #276)

Request GET /index.php/hello?name=Dev → SCRIPT_NAME=/index.php, PATH_INFO=/hello, parse segment after script.

Test matrix (local only)

./phpc serve 127.0.0.1:8080 examples/003-MiniWebApp/public
curl -s 'http://127.0.0.1:8080/?route=home'
curl -s 'http://127.0.0.1:8080/index.php/api/status'
make test-docker   # ServeTest + future mini_web PHPT (**#68**)

Dependency order

1. Reference: MiniWebApp lint-first skeleton (examples/003-MiniWebApp) #246 skeleton + test(aot): add array_shift LLVM compile-and-run PHPT #283/phpc lint --all blocker report
2. Web: DevServer default document (index.php) instead of hard-coded example.php #254 / → index.php
3. Language: while, do-while, and for loops (CFG → VM → JIT) #192 / Language: Implement foreach (CFG → VM → JIT) #53 / Language: Null coalescing operator (??) in compiler pipeline #99 language blockers
4. Testing: ServeTest POST form submission via phpc serve #248 + Testing: ServeAotTest POST form submission via phpc serve --aot #285 POST serve tests
5. Web: CGI/1.1 request driver (stdin/stdout, env, Status line) #50 CGI for production deploy

Blocks #67; unblocks README curl table in #262.