Stdlib: Throwable getTrace()/getTraceAsString()/__toString() — VM introspection missing (zend_exceptions.c)

[PurHur]

Category

stdlib | runtime

Problem

Builtin Throwable / Exception / Error objects are missing core introspection methods that Zend exposes on every thrown object:

Method	Zend PHP 8.x	This compiler VM (2026-06-06)
getTrace()	true (method_exists)	false
getTraceAsString()	true	false
__toString()	echo $e prints message + stack	Error: Object of class Exception could not be converted to string

ExceptionTrace::captureOnThrow() already stores a trace property on throw (#3351), but there is no public getTrace() accessor. getPrevious() landed in lib/VM/Builtin/ExceptionGetPrevious.php (#5104 partial) — this issue covers the remaining Throwable surface.

Nested exception string formatting (Next Exception: chain) also depends on __toString() + getPrevious() working together.

php-src reference

• php/php-src Zend/zend_exceptions.c — zend_exception_get_trace(), zend_exception_get_trace_as_string(), zend_exception_object_get_properties(), zend_std_cast_object_tostring
• php/php-src Zend/zend_exceptions.stub.php — Throwable method table

Repro

Save as test/repro-maintainer/throwable_introspection.php:

<?php
declare(strict_types=1);

$inner = new Exception('inner');
$outer = new Exception('outer', 0, $inner);

echo 'getTrace ', method_exists($outer, 'getTrace') ? 'yes' : 'no', "\n";
echo 'getTraceAsString ', method_exists($outer, 'getTraceAsString') ? 'yes' : 'no', "\n";

try {
    throw new Exception('x');
} catch (Exception $e) {
    echo 'trace_is_array ', is_array($e->getTrace()) ? 'yes' : 'no', "\n";
    echo 'trace_str ', substr($e->getTraceAsString(), 0, 9), "\n";
}

echo $outer, "\n";

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php test/repro-maintainer/throwable_introspection.php
php bin/vm.php test/repro-maintainer/throwable_introspection.php'

Check	Zend	VM today
method_exists(..., 'getTrace')	yes	no
getTrace() after catch	array	undefined method
getTraceAsString() prefix	#0	undefined method
echo $outer	chained text with Next Exception	fatal: could not be converted to string

Scope (this repo)

Path	Work
lib/VM/Builtin/ExceptionGetTrace.php	new — return captured trace property array
lib/VM/Builtin/ExceptionGetTraceAsString.php	new — format like debug_backtrace() string renderer
lib/VM/Builtin/ExceptionToString.php	new — __toString with previous-chain formatting
lib/VM/BuiltinClasses.php / ext/standard/ThrowableManifest.php	register methods on Throwable hierarchy
lib/VM/ExceptionTrace.php	ensure trace populated for Error subclasses too
JIT/AOT	VM fallback acceptable v1; note in capabilities if deferred
Tests	test/compliance/cases/stdlib/throwable_get_trace.phpt, throwable_to_string_chain.phpt

PHP-in-PHP: implement in lib/VM/Builtin/* + manifest; do not add new C in lib/AOT/runtime/.

Done when

• Repro: all four checks match Zend on bin/vm.php
• TypeError / Error subclasses expose the same methods (not only Exception)
• ./script/ci-fast.sh --filter throwable_get_trace green
• Pairs Language: #[\SensitiveParameter] — JIT/AOT trace redaction (phase 2 of #3351, Zend zend_attributes.c) #4621 (SensitiveParameter trace redaction) and Stdlib: Exception::getPrevious() / Throwable chain — missing VM method (zend_exceptions.c) #5104 (getPrevious — already green)

Verification

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

[PurHur]

Parity audit refresh (2026-06-07)

Verified on master via ./script/docker-exec.sh:

php bin/vm.php -r '
try { (new Exception("x"))->getTrace(); } catch (Throwable $t) { echo "Ex getTrace: ", get_class($t), "\n"; }
try { (new Error("x"))->getTrace(); } catch (Throwable $t) { echo "Er getTrace: ", get_class($t), "\n"; }
try { echo (new Exception("x"))->getTraceAsString(); } catch (Throwable $t) { echo "Ex gTAS: ", get_class($t), "\n"; }
try { echo (string)(new Exception("x")); } catch (Throwable $t) { echo "Ex __toString: ", get_class($t), "\n"; }
'

VM today: all four paths → Error: Call to undefined method … (not catchable TypeError).

getMessage() / getCode() / getFile() / getLine() / getPrevious() ✅ (#5104).

Worker repro script

Save as test/repro-maintainer/throwable_trace_matrix.php (same as filed on closed duplicate #7192):

<?php
declare(strict_types=1);
function probe(string $class): void {
    $e = new $class('probe');
    foreach (['getTrace', 'getTraceAsString', '__toString'] as $m) {
        echo $class, '::', $m, ' ';
        try {
            $r = $m === '__toString' ? (string) $e : $e->$m();
            echo is_array($r) ? 'array(' . count($r) . ')' : 'string', "\n";
        } catch (Throwable $t) {
            echo get_class($t), "\n";
        }
    }
}
probe(Exception::class);
probe(Error::class);
probe(TypeError::class);

Done when: all three classes print array, string, string on VM; compliance throwable_get_trace.phpt green.

[PurHur]

claim: worker-lane-c — starting this run

[PurHur]

Merged via #7496.

Verification
```bash
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./vendor/bin/phpunit --filter throwable_get_trace'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./vendor/bin/phpunit --filter throwable_to_string'
```
PHPUnit: OK (4 tests, 4 assertions) — VM + JIT compliance for getTrace/getTraceAsString/__toString on Exception, Error, TypeError; previous-chain __toString formatting matches Zend.