Language: throw expressions and Exception object propagation

[PurHur]

Problem

#57 tracks try/catch/finally lowering, but throw and built-in Exception are not usable in app code today. Web apps need throwable errors for validation and HTTP error paths (complements #152 serve 500 mapping).

MiniWebApp contact validation and API error responses will eventually need throw new Exception(...) instead of ad-hoc echo + exit.

Goal

throw new Exception('Invalid input');

works in VM; catchable when #57 lands.

Implementation hints

Layer	Files	Notes
Compiler	lib/Compiler.php	Lower PHPCfg\Op\Expr\Throw_ to opcode(s); unwind to nearest catch or top
VM	lib/VM.php	Stack unwind; minimal trace; pair with #152 bin/serve.php
Objects	lib/ class table	Builtin Exception (message, code, file, line) — needs #58 object model
JIT	lib/JIT.php	Defer: VM fallback via PHP_COMPILER_JIT_FALLBACK until stable
AOT	lib/AOT/	Same as JIT or stub with link-time message
Serve	lib/Web/	Uncaught → HTTP 500; PHP_COMPILER_DEBUG=1 body (#152 ✅)
Tests	test/compliance/cases/exception_throw_*.phpt	caught vs uncaught

Suggested PHPT cases

1. throw inside function, caught in caller → continues with expected output
2. Uncaught in CLI → non-zero exit / stderr
3. Uncaught in phpc serve → 500 generic body

Tasks

• Lower PHPCfg\Op\Expr\Throw_ in lib/Compiler.php
• VM: unwind stack, attach trace (minimal), match Web: Map uncaught exceptions to HTTP 500 in serve driver #152 at top level
• Builtin Exception class (message, code, file, line)
• JIT: VM fallback initially
• PHPT: throw uncaught; throw caught
• Integration with bin/serve.php HTTP 500

Acceptance criteria

./phpc run -r 'try { throw new Exception("x"); } catch (Exception $e) { echo $e->getMessage(); }'
# → x

./script/ci-fast.sh --filter exception_throw

Caught exception returns 200 with body in serve; uncaught returns 500 (with PHP_COMPILER_DEBUG).

Dependencies

• Language: try/catch/finally lowering #57 — try/catch/finally (required for catch paths)
• Language: Class methods and property access in JIT #58 — methods on objects (Exception::getMessage)
• Web: Map uncaught exceptions to HTTP 500 in serve driver #152 ✅ — HTTP error mapping at serve boundary
• Language: Visibility, constructors, and destructors #145 — user classes (Exception can be builtin first)

Not blocking north-star MiniWebApp AOT execute (#764) — Phase 1 Language polish.

Verification

Local/Docker — ./script/ci-fast.sh for VM; @group llvm optional later.

Links

• Language: try/catch/finally lowering #57, Web: Map uncaught exceptions to HTTP 500 in serve driver #152, Security: MiniWebApp contact POST validation and body limits (dev + deploy) #697 (contact validation may use exceptions later)
• ROADMAP 🗺️ ROADMAP: Compile a small PHP web application (living document) #78 Phase 1 Language

[PurHur]

Implementation hints (batch 47 — expanded)

Compiler lowering

Step	File	Notes
Parse	lib/Compiler.php compileExpr()	Handle PhpCfg\Op\Expr\Throw_ — emit TYPE_THROW with exception value slot
Opcode	lib/OpCode.php	TYPE_THROW + unwinding hook (coordinate #57 TYPE_CATCH)
VM	lib/VM.php	On throw: capture message, walk stack for handler; top-level → exit code / #152 serve 500
Builtin class	ext/standard/ or minimal Exception in VM object model	getMessage(), getCode() — #58 method calls

PHPT matrix (add under test/compliance/cases/language/)

Case	Expect
throw_uncaught.phpt	Non-zero exit / uncaught message
throw_caught.phpt	catch (Exception $e) → continue
throw_in_function.phpt	Stack unwind through user function

Serve integration (#152)

• lib/Web/DevServer.php — map uncaught throw to HTTP 500 when PHP_COMPILER_DEBUG unset
• test/real/ServeTest.php — optional: invalid route throws → 500

JIT / AOT

• v1: VM-only throw; JIT stub calls VM interpreter path (document in docs/capabilities.md)
• Do not block AOT: Native user-class object model for phpc build --project #568 follow-ups

Verify (local)

./script/ci-fast.sh --filter throw
make docker-build-22
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev ./script/ci-fast.sh --filter throw

Dependencies (ordered)

1. Language: try/catch/finally lowering #57 try/catch CFG blocks
2. Language: Class methods and property access in JIT #58 Exception::getMessage method
3. Web: Map uncaught exceptions to HTTP 500 in serve driver #152 HTTP error mapping