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: Compile a small PHP web application (living document) #78 ROADMAP north-star Phase 4 (Polish)