Stdlib: ReflectionGenerator — generator introspection (ext/reflection/php_reflection.c)

[PurHur]

Category

stdlib · php-src-strict · spec refresh 2026-06-19

Problem

Zend exposes ReflectionGenerator for introspecting live Generator objects (getFunction(), getExecutingLine(), getTrace(), getThis(), etc.). Debuggers, test harnesses, and async libraries use it alongside ReflectionFiber (#4609).

This compiler runs generators on VM (#167) but ReflectionGenerator is not registered.

Verified 2026-06-19:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php bin/vm.php -r "var_export(class_exists(\"ReflectionGenerator\"));"'
# bool(false)

php-src reference

• php/php-src ext/reflection/php_reflection.c — ReflectionGenerator class, constructor guards
• php/php-src Zend/zend_generators.c — generator execute state, trace slots
• Tests: ext/reflection/tests/ReflectionGenerator_*.phpt

Repro (failure today)

<?php
declare(strict_types=1);
function gen(): Generator {
    yield 1;
    yield 2;
}
$g = gen();
$g->rewind();
$ref = new ReflectionGenerator($g);
echo $ref->getFunction()->getName(), "\n";
echo $ref->getExecutingLine(), "\n";
echo $ref->getExecutingFile(), "\n";

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php repro.php
php bin/vm.php repro.php 2>&1 | head -3
'

Check	Zend PHP 8.x	VM today
class_exists('ReflectionGenerator')	true	false ❌
Repro after rewind	prints gen, line int, file path	Class "ReflectionGenerator" not found ❌
new ReflectionGenerator(new stdClass())	TypeError	N/A until class exists

v1 method surface (must implement)

Method	Notes
__construct(Generator $gen)	Reject non-generator with TypeError
getFunction(): ReflectionFunction	User function name
getExecutingLine(): int	Line of current yield/suspend
`getExecutingFile(): string	false`
getExecutingGenerator(): Generator	PHP 8.4+ — optional same PR if small

Defer v2: getTrace(), getThis() — follow-up OK if large.

Scope (this repo)

Module	Path
Builtin class	ext/standard/VmReflection.php + register in reflection spine
State bridge	read GeneratorState from VM (lib/VM/GeneratorState.php)
Tests	test/compliance/cases/stdlib/reflection_generator.phpt
JIT/AOT	defer VM-only (same as other reflection builtins)

PHP-in-PHP: implement in ext/standard/VmReflection.php + VM hooks; no new C in runtime/.

Done when

• class_exists('ReflectionGenerator') true on VM
• Repro prints function name + executing line + file matching Zend
• Non-generator constructor → TypeError message matches Zend
• ./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter reflection_generator' green
• php script/capability-matrix.php notes ReflectionGenerator

Related

• Stdlib: ReflectionFiber — introspection for Fiber objects (ext/reflection/php_reflection.c) #4609 ReflectionFiber · Language: generators (yield / yield from) — Generator object + send/throw/getReturn parity #4489 / Language: Generator::send()/throw()/getReturn() — JIT/AOT parity (phase 2 of #167) #4558 Generator semantics · Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

[PurHur]

claim: cursor-agent-lane-a — starting this run

[PurHur]

Merged via #16638.

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php test/repro/maintainer_gap_reflection_generator.php
php bin/vm.php test/repro/maintainer_gap_reflection_generator.php
vendor/bin/phpunit --filter reflection_generator
'

Both repro paths print ok; PHPUnit reflection_generator green (2 tests).