Language: try/catch/finally lowering

[PurHur]

Problem

No try/catch support in the compiler pipeline (lib/Compiler.php / CFG lowering). Real PHP web apps use exceptions for error handling, validation failures, and 500 fallbacks. #195 covers throw; without catch, scripts cannot recover.

Goal

Minimal exception model for the web subset:

try {
    route($uri);
} catch (Exception $e) {
    http_response_code(500);
    echo 'Error: ', htmlspecialchars($e->getMessage());
}

VM first; JIT branch model or landing pads deferred to a follow-up if LLVM complexity blocks.

Implementation hints

1. CFG — php-cfg already emits try/catch/finally nodes; wire Compiler::compileStmt() for Stmt\TryCatch (grep TryCatch in vendor php-cfg).
2. VM — exception stack on Runtime / VMContext; unwind to catch block; rethrow if no handler (Web: Map uncaught exceptions to HTTP 500 in serve driver #152 maps uncaught to HTTP 500 in serve).
3. Builtin — minimal Exception class in object model (message + code); defer full hierarchy.
4. JIT — start with VM fallback or explicit branch table; document in docs/capabilities.md until fast path lands.
5. Tests — test/real/cases/web_try_catch.phpt; ServeTest optional uncaught → 500 body.

Tasks

• CFG lowering for try/catch (finally v2 later)
• VM: exception stack, unwind, catch (Exception $e) binding
• PHPT: caught exception returns controlled body; uncaught → 500 in serve
• Register in UnsupportedRegistry until implemented (Lint: Register Phase-2 blockers in UnsupportedRegistry (ternary, .=, break) #258 closed — re-audit mappings)
• JIT: document stub or initial lowering

Acceptance criteria

./script/ci-local.sh --filter web_try_catch

→ VM compliance passes; phpc lint on snippet without catch still maps to tracking issue until done.

Verification (local / Docker only)

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  ./script/ci-local.sh --filter web_try_catch

Do not require GitHub Actions.

Dependencies

• Language: throw expressions and Exception object propagation #195 throw expressions (coordinate exception object type)
• Language: while, do-while, and for loops (CFG → VM → JIT) #192 / Language: Implement foreach (CFG → VM → JIT) #53 — not hard blockers for v1 try/catch
• Blocks production-hardened Reference app: examples/003-MiniWebApp (router, templates, forms) #67 / Reference: MiniWebApp lint-first skeleton (examples/003-MiniWebApp) #246 error pages

Priority

Phase 2 — after #54 includes; before reference app polish.

Files

• lib/Compiler.php, lib/VM.php, lib/VM/, test/real/cases/

Related

• Web: Map uncaught exceptions to HTTP 500 in serve driver #152 serve exception mapping
• 🗺️ ROADMAP: Compile a small PHP web application (living document) #78 ROADMAP Phase 2