Web: Map uncaught exceptions to HTTP 500 in serve driver

[PurHur]

Category

runtime | stdlib (web)

Problem

bin/serve.php catches Throwable but production apps need Zend-aligned HTTP 500 behavior: configurable debug vs generic body, no stack leak in prod, stderr logging always. Today behavior is minimal plain-text and not env-gated like php-src SAPI error display.

php-src reference

• main/main.c — display_errors, html_errors INI interaction
• Zend/zend_exceptions.c — uncaught exception string formatting
• sapi/apache2handler/sapi_apache2.c (and php_cli.c) — SAPI output of fatal/uncaught errors

Repro (today)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
cat > /tmp/throw.php <<\"PHP\"
<?php throw new Exception(\"boom\");
PHP
php bin/serve.php /tmp/throw.php &
sleep 1
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/ || true
'

Document actual status code + body before fix. After #195 lands, uncaught Exception must be catchable by serve wrapper.

Target behavior

Mode	Body	HTTP
PHP_COMPILER_DEBUG=0	Generic Internal Server Error (no stack)	500
PHP_COMPILER_DEBUG=1	Exception class + message + trace (like dev)	500

Scope (this repo)

• bin/serve.php — map uncaught Throwable / Exception to 500 response
• lib/Web/ — shared helper if MiniWebApp reuses
• Env: PHP_COMPILER_DEBUG=1 (document in README dev section)
• Always error_log() / stderr with full trace
• Tests: test/real/ or test/unit/Web/ServeExceptionTest.php

Done when

• Uncaught exception returns HTTP 500 on phpc serve / bin/serve.php
• Debug=0 hides stack; debug=1 includes exception class name (acceptance from original issue)
• Depends on Language: throw expressions and Exception object propagation #195 for real Exception objects (string-throw path documented if still supported)
• ./script/ci-fast.sh --filter ServeException green

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter ServeException'

Dependencies

• Language: throw expressions and Exception object propagation #195 builtin Exception / Throwable
• Language: try/catch/finally lowering #57 try/catch in user scripts (orthogonal)
• Reference app: examples/003-MiniWebApp (router, templates, forms) #67 / Reference: MiniWebApp lint-first skeleton (examples/003-MiniWebApp) #246 reference app error pages

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 1 web-runtime
• Self-host Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 (serve not required for M5, but web subset north star)