[simon-mundy]

Branched from fix/resultset-object-rows (#201), which this depends on for the current() body it modifies. That branch is not on this repo, so GitHub cannot use it as a base and this diff includes #201's four commits. The commit to review here is the last one, Honour ResultSetReturnType::Prototype. Merge #201 first and this reduces to it.

ResultSetReturnType::Prototype was added in f394207 with no consumer. Nothing in the codebase read it, so selecting it silently gave you Array behaviour:

              getReturnType()   current()      current()
                                before         after
ArrayObject   ArrayObject       ArrayObject    ArrayObject
Array         Array             array          array
Prototype     Prototype         array          ArrayObject

The constructor accepted it, getReturnType() reported it back correctly, and current() tested only for ArrayObject and let everything else fall through to return $data. Every observable signal said it worked, which is what made it hard to spot.

Prototype is the successor name for ArrayObject. It follows the rename already in flight in this class — TYPE_ARRAYOBJECT giving way to the enum, setArrayObjectPrototype() to setRowPrototype(), getArrayObjectPrototype() to getRowPrototype() — and for ResultSet the ArrayObject is the row prototype. Both cases now fill it.

Resolved once, not per row

The return type cannot change after construction, so the decision belongs there:

private readonly ResultSetReturnType $returnType;

private readonly bool $fillsRowPrototype;

public function __construct(...)
{
    $this->returnType        = is_string($returnType) ? ResultSetReturnType::from($returnType) : $returnType;
    $this->fillsRowPrototype = match ($this->returnType) {
        ResultSetReturnType::ArrayObject, ResultSetReturnType::Prototype => true,
        ResultSetReturnType::Array => false,
    };
}

current() runs once per row, so evaluating this there was repeated work for an answer fixed at construction. Per-row cost is now a bool property read, below the ResultSetReturnType::ArrayObject === $this->returnType comparison it replaces.

Both properties are readonly. That costs nothing today — $returnType was already private and assigned once — and it stops a later setReturnType() leaving the derived flag stale, which is the one real hazard in caching derived state.

The exhaustive match is the actual fix

Wiring Prototype is the symptom; the defect is that an identity check against one case lets every other case vanish into the fall-through. A match with no default arm closes that:

$ new ResultSet(ResultSetReturnType::Hydrated)      # a case added without a decision
UnhandledMatchError: Unhandled match case of type PhpDb\ResultSet\ResultSetReturnType

It fails at construction, before any row is touched, rather than part-way through an iteration. returnTypeProvider() covers every case and asserts its own completeness against ResultSetReturnType::cases(), so the same omission also fails the suite:

$ vendor/bin/phpunit --filter everyReturnTypeYieldsItsRowType
every ResultSetReturnType case needs a row type asserted here
Failed asserting that 3 is identical to 4.

Both were verified by temporarily adding a fourth case.

Compatibility

No signature changes. Prototype stops behaving as Array, which is observable only for a caller relying on that accident; nothing in the repo referenced the case.

ResultSetReturnType::ArrayObject is not deprecated here, though completing the rename would suggest it. It is the constructor's default, so deprecating it means either leaving the default pointing at a deprecated case or changing the default to Prototype — and that changes what getReturnType() returns for a default-constructed ResultSet, which returnTypeIsObjectByDefault asserts. Worth doing, but a separate decision from making the case work.

	Before	After
PHPUnit	2040 tests, 3965 assertions	2043 tests, 3968 assertions

mago lint, mago analyze and mago format --check are clean, and src/ResultSet stays at 100% line coverage.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[simon-mundy]

Folded into #201 rather than stacked; this was never meant to be a separate pull request.