Language: throw expressions and Exception object propagation

[PurHur]

Category

language | runtime

Problem (May 2026 status)

#57 landed VM/JIT try/catch/finally lowering, but throw new Exception(...) still fails because built-in exception classes are not registered in the VM class table. User code cannot instantiate Exception, Error, or Throwable for validation / HTTP error paths.

MiniWebApp and #697 contact validation will need real exception objects, not only string throws.

php-src reference

• php/php-src Zend/zend_exceptions.c — zend_throw_exception, zend_exception_get_default()
• php/php-src Zend/zend_exceptions.h — zend_ce_exception, zend_ce_error, zend_ce_throwable
• php/php-src ext/standard/basic_functions.c — error_get_last integration
• php/php-src ext/spl/spl_exceptions.c — SPL exception hierarchy (phase 2)

Repro (failure today)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php -r '"'"'try { throw new Exception("x"); } catch (Exception $e) { echo $e->getMessage(); }'"'"''

Expected (Zend): x
Actual:

LogicException: Attempting to instantiate non-existing class Exception
  in lib/VM.php (TYPE_NEW)

Uncaught path (after class exists):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php -r '"'"'throw new Exception("boom");'"'"''
# expect non-zero exit / uncaught handler

Scope (this repo)

• lib/VM/ — register builtin Exception, Error, Throwable (minimal: message, code, file, line, getMessage())
• lib/Compiler.php — throw already lowers; ensure catch (Exception $e) type filter uses class entry
• lib/JIT/ — JIT: try/catch/finally lowering phase 2 (#57, after VM #2084) #2114 phase 2 for full JIT exception objects; VM fallback acceptable v1
• bin/serve.php, lib/Web/ — uncaught → HTTP 500 (Web: Map uncaught exceptions to HTTP 500 in serve driver #152 ✅ boundary)
• test/compliance/cases/exception_throw_caught.phpt, exception_throw_uncaught.phpt

Done when

• Repro above prints x on VM
• $e->getMessage(), $e->getCode(), $e->getFile(), $e->getLine() match Zend for thrown exception
• catch (Throwable $e) catches Exception and Error subclasses
• ./script/ci-fast.sh --filter exception_throw green
• Runtime: set_exception_handler() / restore_exception_handler() (ext/standard parity) #3146 set_exception_handler can receive object (follow-up if split)

Dependencies

• Language: try/catch/finally lowering #57 ✅ try/catch opcodes
• JIT: try/catch/finally lowering phase 2 (#57, after VM #2084) #2114 — JIT exception object parity (parallel, not blocker for VM)
• Runtime: set_exception_handler() / restore_exception_handler() (ext/standard parity) #3146 — exception handler stdlib

Verification

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

Docker: ./script/docker-exec.sh — not raw docker run -v "$(pwd):/compiler".

Links

• Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 self-host — compiler uses exceptions in vendor code
• 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 ROADMAP Phase 2 language
• Supersedes stale “blocks Language: Class methods and property access in JIT #58” notes — OOP methods are landed; gap is builtin exception classes

[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

[PurHur]

Implementation hints (batch 78 — backlog architect)

Opcode / CFG plan

Step	File	Work
1	lib/Compiler.php	Lower PHPCfg\Op\Expr\Throw_ → TYPE_THROW with exception value on stack
2	lib/OpCode.php	Add TYPE_THROW if missing
3	lib/VM.php	Unwind to innermost catch frame; if none, propagate to top-level handler
4	Builtin class	Register minimal Exception with $message, getMessage() — needs object model #58
5	lib/Web/DevServer.php / #152	Uncaught → HTTP 500 generic body

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

• exception_throw_caught.phpt — caught in same function
• exception_throw_uncaught_cli.phpt — non-zero exit
• exception_throw_in_method.phpt — requires Language: Class methods and property access in JIT #58 method + Language: Visibility, constructors, and destructors #145 ctor optional

JIT / AOT (phase 2)

Defer LLVM unwind; gate with PHP_COMPILER_JIT_FALLBACK=1 until #57 try/catch CFG stable.

Dependencies

• Language: try/catch/finally lowering #57 try/catch/finally (catch blocks must exist before throw is useful)
• Language: Class methods and property access in JIT #58 / Language: Visibility, constructors, and destructors #145 — new Exception(...) object construction
• Web: Map uncaught exceptions to HTTP 500 in serve driver #152 ✅ serve 500 mapping
• MiniWebApp contact validation — future consumer, not NS1 blocker

Verify

./script/ci-fast.sh --filter Exception
./script/ci-local.sh --filter Exception

No GitHub Actions.

[PurHur]

Implementation hints (batch 96 — backlog architect)

Opcode / CFG search

rg 'Throw_|Op\\\\Expr\\\\Throw' lib/Compiler.php lib/VM.php vendor/ircmaxell/php-cfg
rg 'class Exception|TYPE_EXCEPTION' lib/ ext/

Suggested lowering order

1. Builtin Exception object — minimal lib/ or ext/standard class with message property (needs Language: Class methods and property access in JIT #58 object ctor path).
2. Op\Expr\Throw_ — emit OP_THROW (new) with value on stack; unwind to innermost catch or fatal.
3. throw expression (PHP 8+) — compile as statement expression; reject in unsupported positions until lint allows.
4. VM — pair with Language: try/catch/finally lowering #57 try/catch frames; reuse Web: Map uncaught exceptions to HTTP 500 in serve driver #152 serve 500 mapping for uncaught.
5. JIT/AOT — PHP_COMPILER_JIT_FALLBACK=1 until unwind tables exist.

First PHPT slices

PHPT	Proves
throw_catch_simple.phpt	throw new Exception('x'); inside try/catch
throw_uncaught.phpt	serve/VM fatal path (optional)

Verification

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

Dependencies: #57 try/catch · #58 objects · ROADMAP #78 Phase 1 long tail.

[PurHur]

claim: worker-lane-a — starting this run

[PurHur]

claim: cursor-agent-lane-a — continuing PR #3215 (merge-block getFrame fix on master)

[PurHur]

Update (lane-a, May 30)

Rebased onto current master. Builtin Exception/Error/Throwable registration is already on master; remaining gap was try/catch merge block getFrame failing with Could not resolve argument when unwinding into a catch handler.

Fix: inheritUndefinedLocals = true on the try/catch merge (stmt->end) block in lib/Compiler.php (#195, #2084).

Verified:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./vendor/bin/phpunit --filter ExceptionBuiltinTest test/unit/ExceptionBuiltinTest.php'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./vendor/bin/phpunit --filter exception_throw'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php -r '"'"'try { throw new Exception("x"); } catch (Exception $e) { echo $e->getMessage(); }'"'"''
# x

PR #3215 updated (force-pushed).

[PurHur]

claim: cursor-agent-lane-a — continuing PR #3215 (exception catch $e binding + merge frame setup)